Workload identity federation: short-lived, scoped identities for services and CI

A workload identity system issues credentials to a running service based on evidence about where and how it is running. Examples include a platform-issued token or a SPIFFE identity document. The application uses that credential directly or exchanges it for a resource-specific credential. The bootstrap question is who is allowed to claim the workload identity.

A typical sequence is platform attestation, identity issuance, credential retrieval through a controlled local interface, presentation or exchange, and resource authorization. Each step has an audience and trust boundary. A token proving a CI job’s identity is not automatically a database login or permission to administer every cloud resource.

Short-lived credentials reduce the period during which a copied token can be replayed. They do not prevent misuse while valid, nor do they stop a compromised workload from repeatedly obtaining fresh credentials while its attestation and permissions remain valid. Incident response must disable the issuance or authorization path as well as wait for tokens to expire.

For federation, configure the expected issuer, audience and subject constraints using authoritative platform claims. For GitHub Actions a deployment policy might require repository_owner_id 123456, repository_id 456789, ref refs/heads/main, the deploy.yml workflow in job_workflow_ref, and the protected production environment. A repository name alone can leave pull request runs, other branches or a recreated repository able to satisfy the policy; the GitHub Actions hardening guide at /domains/supply-chain/ci-cd/github-actions-hardening/ covers the workflow side.

Review which claims the platform signs and which values the job itself can choose. A branch name in an environment variable is not the same evidence as an issuer-signed claim. Prefer numeric IDs to names: GitHub repository, organization and user names can be renamed or deleted and then registered by someone else, while repository_id, repository_owner_id and actor_id never change. For repositories created after 15 July 2026, GitHub also puts those IDs in the subject, as repo:octo-org@123456/billing@456789:environment:production.

For SPIFFE, the SPIFFE ID identifies the workload within a trust domain, while an SVID carries a verifiable identity assertion. Trust bundles and federation configuration determine which issuers are accepted. A local identity socket is sensitive: a neighboring process that can retrieve another workload’s credentials can cross the intended identity boundary.

Mutual TLS can authenticate both peers and protect transport. Authorization must still map the peer identity to specific services, actions, and resource scope. A mesh that accepts every workload certificate in one trust domain has established membership, not an application-specific access policy.

All three exchange the GitHub token for short-lived cloud credentials, but they match claims differently. Write the narrowest condition each one supports.

• Dangerous: a subject ending in :*, which admits repo:org/app:pull_request and every branch.
• Dangerous: a repository-name condition alone, which a recreated repository with the same name satisfies.
• Dangerous: no audience condition, which lets a token minted for another service assume the role.
• Dangerous: allowing every event, which includes Dependabot update jobs (event_name of dynamic).

This role trust policy admits only jobs that run in the production environment of one repository, identified by its immutable owner and repository IDs. Protect the environment in GitHub with required reviewers and deployment branch rules. The JSON was checked for syntax and its conditions were evaluated against sample token claims with IAM’s documented exact-match semantics; AWS itself was not called.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::111122223333:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:octo-org/billing:environment:production",
          "token.actions.githubusercontent.com:repository_owner_id": "123456",
          "token.actions.githubusercontent.com:repository_id": "456789"
        }
      }
    }
  ]
}

A deployment service or internal broker can accept GitHub tokens directly. This Python function verifies the token against GitHub’s published keys, requires your own audience, and compares the immutable claims exactly. It was tested with PyJWT 2.15.0 on Python 3.14 against tokens signed by a local key: the deploy workflow is accepted, while a recreated repository, another owner, another workflow file or branch, a different-case environment, a missing environment, pull request and Dependabot events, GitHub’s default audience, another issuer, an expired token and an unknown key are all refused. The JWT validation lab at /labs/token-validation/ practices the same audience and purpose checks.

import jwt  # PyJWT 2.x

ISSUER = "https://token.actions.githubusercontent.com"
jwks = jwt.PyJWKClient(ISSUER + "/.well-known/jwks", cache_keys=True, lifespan=600)

# Exact values for the one workflow allowed to deploy. Use the numeric IDs: a deleted or
# renamed repository's name can be registered again by someone else.
POLICY = {
    "repository_owner_id": "123456",
    "repository_id": "456789",
    "job_workflow_ref": "octo-org/billing/.github/workflows/deploy.yml@refs/heads/main",
    "ref": "refs/heads/main",
    "environment": "production",
}
ALLOWED_EVENTS = {"push", "workflow_dispatch"}


def verify_deploy_token(token: str) -> dict:
    key = jwks.get_signing_key_from_jwt(token)
    claims = jwt.decode(
        token,
        key.key,
        algorithms=["RS256"],
        issuer=ISSUER,
        audience="https://deploy.example",  # your service, never the default audience
        options={"require": ["exp", "iat", "sub", "aud"]},
    )
    for name, expected in POLICY.items():
        if claims.get(name) != expected:  # exact match: no prefixes, wildcards or case folding
            raise PermissionError(f"{name} does not match the deployment policy")
    if claims.get("event_name") not in ALLOWED_EVENTS:  # excludes pull requests and Dependabot runs
        raise PermissionError("event not allowed to deploy")
    return claims

Give each workload a role appropriate to its job, and issue resource credentials with the intended audience and lifetime. If one worker processes multiple tenants, tenant authorization still belongs in each request or job context; the worker’s identity does not by itself prove which customer’s data a job may touch.

Refresh before expiry with jitter and bounded retries so thousands of instances do not stampede the issuer at once. Preserve a clear expiry cutoff and fail closed when no valid credential remains. Avoid a static emergency token embedded in the image, because it can become the permanent bypass around the identity system.

An issuer outage presents a real availability tradeoff. A valid cached credential can continue within its existing authority and lifetime if policy allows; an expired one cannot become valid because refresh failed. Longer lifetimes reduce dependence on refresh availability while increasing theft and revocation exposure.

Record identity, target audience, policy version, and decision outcome in logs. Do not log complete bearer tokens or private keys. For certificate identities, preserve a way to trace the issuing trust domain and key lifecycle without assuming certificate expiry is immediate revocation.

A permitted workload should obtain a correctly scoped credential and complete its intended operation. The same credential at a different audience must fail. A neighboring namespace, forked repository, wrong workflow, or unrelated trust domain must not receive equivalent authority merely because it shares infrastructure.

Test expiry at the exact boundary, refresh failure with a still-valid cache, refresh failure after expiry, and disabling the workload’s issuance rule. Include an authorization test showing that identity success cannot read a different tenant’s resource. These outcomes distinguish a working credential refresh loop from a sound workload trust policy.

Sources & further reading

The standards, specifications and documentation behind the guidance above. Each is the evidence for a claim on this page; consult it for detail beyond the defaults and versions listed here.

1. SPIFFE concepts
2. SPIFFE Workload API
3. RFC 8693: OAuth token exchange. January 2020.
4. GitHub: OpenID Connect reference for GitHub Actions
5. AWS IAM: create a role for OpenID Connect federation (GitHub)
6. Google Cloud: workload identity federation with deployment pipelines
7. Microsoft Entra: workload identity federation

Reference information

Tags

Workload identityCI/CD security

SDLC phase

DesignDevelopmentRelease

Role

Platform engineers and SREs

ASVS 5.0.0 requirements

v5.0.0-13.2.1 · v5.0.0-13.2.2 · v5.0.0-13.3.1

Download this guide as Markdown

Continue exploring