OIDC Workload Identity Federation for CI/CD

Updated on Oct 17, 2026

9 min read

Continuous integration and deployment jobs often need permission to publish an image, update a cluster, or change cloud infrastructure. OIDC workload identity federation for CI/CD lets a trusted job prove which repository and workflow it belongs to, then exchange a short-lived identity token for temporary cloud credentials. This guide explains the trust chain, the controls that make it safe, and how to configure a GitHub Actions deployment without saving a cloud access key as a repository secret.

Why CI/CD Workload Identity Is Being Talked About

Build systems have become part of the production security boundary. A workflow can publish software or modify infrastructure, so a stolen deployment credential may be as powerful as a compromised administrator account. Long-lived access keys stored in repository or organization secrets are convenient, but they must be distributed, rotated, scoped, and protected from every job that can read them.

Hosted CI platforms can issue signed identity tokens for individual jobs. Cloud identity systems can verify those tokens against a policy and grant a limited role without requiring the pipeline to possess a permanent cloud key. The GitHub Actions project supports this pattern through its OIDC token endpoint; its OIDC documentation describes the claims and job permissions involved.

What Is OIDC Workload Identity Federation?

OpenID Connect (OIDC) defines an identity layer built on OAuth 2.0. In CI/CD federation, the runner receives a signed OIDC JSON Web Token (JWT) describing the workload that requested it. A cloud provider validates the token’s issuer and signature, checks selected claims against a trust policy, and issues temporary credentials for an authorized role.

The OpenID Connect Core specification defines the standard identity claims and validation model. In this deployment pattern, the runner’s token is evidence for the cloud identity system; it is not itself the cloud credential used to call services. The token is exchanged or presented through the provider’s federation flow, which returns credentials constrained by the role’s permissions and lifetime.

This differs from a person signing in through a web application. The principal is a workload, and the policy can bind it to a repository, branch, tag, or protected deployment environment. It also differs from a machine-to-machine OAuth client that authenticates with a stored client secret.

The Problem: Long-Lived Deployment Secrets

A static cloud access key is usually valid until it is disabled or rotated. Even if it is stored in a secret manager, every workflow authorized to read it becomes a possible path to that key. Rotation requires changing both the cloud identity and every pipeline configuration that depends on it. A key copied into logs, a build artifact, or an unsafe action can remain usable after the job ends.

Federation changes the credential lifecycle. A runner asks for an identity token when a job is running; the provider issues temporary credentials only if the token’s claims match the trust policy. When the job ends, those credentials expire. This reduces the value of accidental disclosure, but it does not make a running job harmless: malicious workflow code can still use credentials that are available to that job.

Property	Stored cloud access key	OIDC-federated role
Pipeline credential	Long-lived key stored as a secret	Short-lived token requested by an authorized job
Trust decision	Key possession identifies the principal	Provider validates issuer, audience, and workload claims
Rotation	Key and dependent secret references must be rotated	Provider issues fresh credentials per eligible job
Scope	Key permissions apply wherever the key is accepted	Role policy limits cloud actions; trust policy limits who can assume it
Main exposure	Secret may persist in settings, logs, or copies	A compromised authorized job can use credentials until they expire

Federation is therefore a way to reduce standing credentials, not a replacement for least privilege, secure workflows, or review of deployment changes.

How the Trust Flow Works

The exchange has several independent checks:

A workflow runs under an intended context. A push to a protected branch or an approved deployment environment can start the job. Repository rules and environment approvals determine which changes may reach that point.
The job requests an OIDC token. On GitHub Actions, the workflow needs the id-token: write permission. This permits requesting a token; it does not grant cloud API access by itself.
The identity provider signs the token. Claims identify the issuer (iss), intended audience (aud), subject (sub), and other workflow context. The token is short-lived and signed so the cloud provider can verify its origin.
The cloud provider evaluates trust. The provider must recognize the issuer and validate the signature. A trust policy then checks the audience and matches the subject or other supported claims to a role.
The job receives temporary permissions. If the checks pass, the identity service returns temporary credentials. The job uses them to call cloud APIs, and the role’s permission policy limits those operations.

For example, an AWS role can trust the GitHub Actions OIDC provider only when the audience is sts.amazonaws.com and the subject identifies one repository’s protected production environment. AWS’s OIDC identity provider guide explains how to register an issuer and create trust relationships. Google Cloud uses attribute mappings and conditions for its corresponding Workload Identity Federation flow.

The standards-based OAuth 2.0 Token Exchange specification describes a general model for exchanging one security token for another. Cloud providers expose their own federation configuration and APIs, so follow the provider’s documented protocol rather than assuming every exchange endpoint is identical.

Components and Policy Choices

Issuer: The CI platform that signs the token. A cloud provider must trust the expected issuer, not an arbitrary token URL.
Audience: The identifier for the intended recipient. Match it exactly to the provider or exchange endpoint; a token for one audience should not be accepted by another.
Subject and claims: The subject should narrow the identity to the expected repository and deployment context. Depending on the provider, policies can also evaluate branch, repository owner, or environment claims.
Federated identity provider: The cloud-side configuration that recognizes the external issuer and maps token claims to a cloud principal.
Role trust policy: Controls which external identities may assume the role. The role’s separate permission policy controls what an assumed identity can do.
Temporary credentials: The provider-issued credentials used for API calls. Their lifetime and scope depend on provider configuration and should be no broader or longer than the job requires.

Scope the trust policy to the smallest practical identity. A repository-wide subject may allow workflows from multiple branches; a protected environment can add an approval boundary, while a branch-specific subject can limit deployments to a release branch. Pull-request jobs require special attention: forked code and untrusted changes should not receive production identity merely because they run in the same repository’s workflow.

Real-World Uses

Deploying an application: A release workflow assumes a role that can update only the production service and read the required image.
Publishing build artifacts: A tagged release can obtain narrowly scoped permission to upload packages or container images.
Infrastructure changes: A reviewed plan job can read state while a separately gated apply job receives write access.
Multi-cloud delivery: A trusted CI identity can be mapped independently to roles at more than one provider, with distinct audiences and permissions for each trust relationship.

Federation is most useful when workflows need access to cloud resources and permanent keys have become difficult to govern. It does not eliminate secrets for unrelated systems, such as signing material that cannot use a federated identity, nor does it automatically make a deployment safe.

Getting Started: GitHub Actions to AWS

The example assumes an AWS OIDC provider has already been registered for the GitHub issuer, and that an IAM role has a trust policy scoped to the repository’s production environment. Replace the example account and repository values with your own. The role should have only the permissions needed by the deployment.

An AWS trust policy can restrict role assumption to one audience and one environment-bound subject:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012: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:ACME/widget:environment:production"
        }
      }
    }
  ]
}

The workflow grants token-request permission only to the deployment job, uses a protected environment, and asks the AWS credentials action to assume the role:

name: Deploy

on:
  push:
    branches: [main]

permissions: {}

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v7

      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/WidgetDeploy
          aws-region: us-east-1

      - name: Verify assumed identity
        run: aws sts get-caller-identity

Use the provider’s recommended action and pin actions according to your repository’s supply-chain policy; immutable commit-SHA pins make updates reviewable. The production environment must exist in repository settings, and its protection rules should require the appropriate reviewers or branch restrictions. The example’s sub condition must match the subject format emitted for that environment. If you use a branch or tag instead, update both the trust policy and workflow trigger to match that context.

After configuring the provider and role, run the workflow and confirm that get-caller-identity returns the expected role. Then verify that an untrusted branch or different repository cannot assume it, and test that the deployment fails when a required permission is removed. Do not add an AWS access key as a fallback: that would preserve the long-lived credential the federation setup is intended to remove.

Common Misconceptions

“id-token: write gives the job cloud access.” It only allows the job to request an identity token. The issuer registration, trust conditions, role assumption, and role permissions still control access.
“OIDC means the pipeline has no credentials.” A job still receives temporary cloud credentials after it is trusted. The security benefit is that they are issued for a specific job and expire, rather than being a permanent key saved in repository settings.
“A valid token means the workflow is safe.” A compromised or malicious workflow running in an authorized context can request and use credentials. Protect workflow changes, restrict third-party actions, use environment approvals where appropriate, and keep role permissions narrow.
“The trust policy is the permission policy.” Trust determines who may assume a role; the role’s permissions determine what that role can do. Both must be reviewed.

Changelog

Initial publication.

Last updated: October 17, 2026