Skip to main content

Keyless Workload Identity Federation

Long-lived API keys are a structural liability. They live in secrets managers, in CI/CD environment variables, in deployment configs, in .env files — every copy is a potential exfiltration point, and rotation is operational pain. The right pattern is keyless: the calling workload presents an OIDC token (which it can obtain from its own identity provider — GitHub Actions, AWS EKS, GCP Workload Identity, etc.), and Kilimanjaro exchanges it for a short-lived, hardware-scoped session credential.

There is no API key stored anywhere. There is no rotation to schedule. There is no credential to leak.

This tutorial wires GitHub Actions to Kilimanjaro via OIDC, but the pattern is identical for any OIDC-emitting identity surface.

Prerequisites​

  • A Kilimanjaro project with admin access
  • A GitHub repository with Actions enabled

Step 1 — Configure the OIDC trust relationship in Kilimanjaro​

In the Console, navigate to Identity → Federated workloads → New trust.

Select GitHub Actions as the issuer. The trust configuration requires:

FieldValue
Issuer URLhttps://token.actions.githubusercontent.com (auto-populated for GitHub)
AudienceThe audience claim Kilimanjaro accepts (per the platform's federation reference)
Subject patternrepo:<your-org>/<your-repo>:ref:refs/heads/main — restricts trust to commits on main branch of your repo
Granted roleThe role to issue to authenticated workloads (e.g., ci-deployer)
Session TTLPer the project's session policy

Save the trust. The Console returns a trust ID; you do not need to copy it (the workflow uses the issuer + audience, not the trust ID).

Step 2 — Configure the GitHub Actions workflow​

In .github/workflows/deploy.yml:

name: Deploy to Kilimanjaro
on:
push:
branches: [main]

permissions:
id-token: write # required for the workflow to request an OIDC token
contents: read

jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Request OIDC token
id: oidc
run: |
OIDC_TOKEN=$(curl -sLS "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$AUDIENCE" \
-H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" | jq -r .value)
echo "::add-mask::$OIDC_TOKEN"
echo "oidc_token=$OIDC_TOKEN" >> $GITHUB_OUTPUT
env:
AUDIENCE: <the audience configured in step 1>

The workflow step requests the OIDC token from GitHub. The token is then submitted to Kilimanjaro, which:

  1. Verifies the token against the issuer's published JWKS
  2. Checks the issuer matches the configured trust
  3. Checks the subject matches the pattern
  4. On success, issues a short-lived session credential scoped to the granted role
GitHubOIDC issuerWorkflowGitHub Actions runKilimanjarofederated trust1 request OIDC token2 OIDC token3 submit tokenKilimanjaro checkstoken signature (JWKS)issuer matches trustsubject matches pattern4 short-lived session credential
The workflow never holds a static key: it trades a token from its own identity provider for a short-lived session credential.

The result is a short-lived session credential, so no static API key is used anywhere.

:::note CLI support The federation exchange is an HTTP flow between your workflow and Kilimanjaro; the k9o CLI has no federation command. CI pipelines that run the CLI authenticate it with a service token (K9O_SERVICE_TOKEN, together with K9O_ORG and K9O_PROJECT). :::

Step 3 — Verify the federation event​

Open Audit → Recent events and filter for federation events. You should see:

  • The federation event with the calling subject's federated-workload identity
  • The issuer + subject claim from the OIDC token preserved on the audit entry
  • The granted role and the issued session
  • The session expiration

Subsequent operations under the federated session reference the same session identifier, so the chain from "GitHub workflow run X" → "Kilimanjaro session Y" → "specific platform operations" is complete.

Step 4 — Restrict the trust further​

Real production trusts should narrow the subject pattern as much as the workflow's structure allows:

PatternUse case
repo:org/repo:ref:refs/heads/mainAny workflow run on main
repo:org/repo:ref:refs/heads/main:environment:productionOnly runs in the production environment
repo:org/repo:job_workflow_ref:org/repo/.github/workflows/deploy.yml@refs/heads/mainOnly the specific workflow file

Tighter patterns reduce the blast radius if a workflow is compromised. The platform supports as many concurrent trusts as you need; one trust per workflow per role is a common pattern.

Step 5 — Pattern for AWS EKS, GCP Workload Identity, etc.​

The same pattern works for any OIDC issuer:

  • AWS EKS — pods authenticate via IRSA (IAM Roles for Service Accounts), which emits an OIDC token. Configure the Kilimanjaro trust with https://oidc.eks.<region>.amazonaws.com/id/<cluster> as the issuer.
  • GCP Workload Identity Federation — GCP service accounts emit OIDC tokens consumable by external systems; Kilimanjaro trusts the GCP issuer.
  • Kubernetes ServiceAccount tokens — projected SA tokens are OIDC-signed; configure the cluster's API server as the issuer.

The trust configuration is the only thing that varies; the workload-side flow (request token → submit to Kilimanjaro → use returned session) is identical.

What just happened​

You replaced a static API key with a federation trust. The benefits:

  • Zero stored credentials — no key in CI/CD secrets, no key in environment variables, nothing to rotate
  • Tight blast radius — the federation is constrained to specific issuer + subject patterns; a compromised workflow grants access only to the role its trust permits
  • Auditable provenance — every operation traces back through the federation event to the originating workflow run, with the OIDC claims preserved in the audit log
  • No password-class threats — there is no API key to phish, leak, or guess

Next​