OIDC Federation for Pipeline Credentials

Exchange identity for short-lived access

OpenID Connect federation lets a CI pipeline present a short-lived signed identity token and exchange it for temporary cloud credentials. The pipeline does not store a long-lived access key in repository secrets. The cloud provider trusts a configured identity issuer and evaluates token claims before granting a role or service identity. This reduces the lifetime and persistence of credentials, but trust policy must be precise; an overly broad subject can let an unrelated repository or branch assume the role.

A token includes claims such as issuer, audience, subject, repository, ref, workflow, and environment, depending on the CI provider. The trust relationship should pin the expected issuer and audience and restrict subject claims to the repository and protected branch or deployment environment that needs access. Prefer exact matching where supported. A wildcard that accepts every branch or repository weakens the boundary and can expose production credentials to untrusted code.

Scope the role by environment and action

Use separate roles for plan and apply when their permissions differ. A plan identity may need read access to state and cloud resources, while apply requires mutation permissions. Scope each role to the target account, subscription, project, workspace, and resource actions. Do not give a development pipeline a trust path into production. Use protected environment approvals for production and bind the token subject to the environment or workflow context that is actually protected.

Temporary credentials have an expiration. Set the session duration to cover the expected run with modest headroom, and ensure the pipeline can refresh safely if supported. Avoid printing tokens or credential responses. Masking logs is a defense in depth, not permission to expose secrets. Keep Terraform state and plan artifacts protected because federation does not remove secrets stored in those artifacts.

Provider configuration differs

Cloud providers implement federation differently. AWS commonly exchanges a CI OIDC token through STS for a role session, with trust conditions on claims. Azure uses a federated credential associated with an identity and matches issuer, subject, and audience. Google Cloud uses workload identity federation to map external claims to a service account or principal. Follow the current provider and CI documentation for exact claim names and syntax; assumptions copied between providers can create a trust gap.

Keep claim mapping explicit and minimal. A repository name alone may be insufficient if branches, pull requests, or environments have different trust. A subject claim for a pull-request workflow can differ from one for a branch deployment. Test the token context from the actual workflow and verify the cloud-side policy denies an untrusted repository, fork, branch, or audience.

Protect the workflow identity

OIDC removes static secrets but does not make workflow code trusted. A contributor who can change a privileged workflow may cause it to request a token and use the role. Protect workflow files, reusable workflows, environment definitions, and trust policies with review. Do not grant production federation to arbitrary pull requests. Use a dedicated apply job on a protected branch after approval, and keep plan permissions separate where practical.

Audit role assumptions with repository, subject, audience, and session context. Alert on unexpected principals, regions, or actions. Define token lifetime and role permissions so a leaked short-lived credential has limited value. Review trust conditions when repository names, default branches, or CI workflow identities change. Federation is a credential-delivery mechanism; least privilege and workflow integrity remain essential.

Establish a narrow trust relationship

Create a dedicated cloud role for Terraform production apply. Configure the cloud identity provider for the CI issuer and expected audience. Restrict the trust policy to the repository, protected deployment branch or environment, and the workflow that performs the apply. Use separate identities for development and production. Keep the role's permissions limited to the resources and operations managed by the Terraform root, and review any broad permissions the provider requires for discovery or deletion.

Configure the CI job to request an OIDC token only when it enters the protected apply stage. Exchange it for a temporary role session and expose the resulting credentials only to the Terraform process. Do not save them as long-lived repository variables or print them. Set a session duration appropriate for the apply; if a run can exceed the limit, understand whether the provider session can refresh and how a partially completed apply is reconciled.

Bind plan and apply separately

For a pull-request plan, use a low-privilege identity and avoid exposing production write credentials to untrusted code. If a cloud-backed plan needs read access, run only for trusted contributors or use an isolated preview account. After merge and approval, a protected job can assume the production apply role. Confirm that plan and apply target the same backend, workspace, and commit, and that a changed plan requires new approval.

The OIDC subject should reflect the actual CI event. A branch deployment, environment deployment, and pull-request workflow can produce different subject claims. Inspect a token in a safe test environment or use provider logs to confirm the claims. Do not infer the correct subject format from a tutorial for another CI system. Pin issuer and audience exactly and test negative cases.

Test allowed and denied identities

Verify that the protected production workflow can assume the role and that a feature branch, fork, different repository, wrong audience, or altered workflow cannot. Test environment protection and required reviewers. Confirm a developer who can edit Terraform but not approve production cannot bypass the approval stage. Ensure the role session cannot access unrelated accounts or administrative APIs.

Inspect cloud audit logs for a successful run. Confirm the principal, repository or subject, session name, duration, and actions are attributable. Trigger a denied assumption and verify the event is visible to security operators. Rotate or disable the federated credential as part of an incident exercise and confirm the pipeline fails closed rather than falling back to a static access key.

Maintain the federation contract

Document which repositories, refs, workflows, environments, and roles are trusted. Assign owners to both the cloud trust policy and the CI workflow. Changes to branch names, repository transfers, reusable workflows, or environment names can break federation or broaden access. Review the relationship during repository and platform migrations, and remove stale credentials and trust entries.

OIDC is only as strong as the integrity of the workflow allowed to request a token. Protect workflow files, pin third-party actions or reusable components, minimize job permissions, and avoid executing untrusted pull-request code in a privileged context. The final check is not merely that authentication succeeds; it is that only the intended workflow can obtain only the intended temporary permissions.

Short-lived does not mean harmless

Federated credentials reduce long-lived key storage and narrow the exposure window, but a valid token can still perform powerful actions during its lifetime. A compromised workflow can request a token if its repository and event match the trust policy. Restrict permissions, subject claims, audience, and session duration, and protect the code that requests the token. Monitor assumptions and use a clear revocation procedure.

Trust policies often fail through overbroad matching. A repository-wide wildcard can include pull requests, feature branches, or forks depending on the issuer's claim semantics. Pin the protected branch or environment and test denied cases. Reusable workflows and organization-level runners need special attention because they can expand which code executes under a trusted identity.

Keep the job boundary secure

Request the token only in the job that needs cloud access. Avoid passing credentials to later steps or uploading them as artifacts. Separate plan from apply and isolate untrusted validation. Limit job-level permissions and third-party actions. If a workflow can be modified by the same contributor whose code it runs, require review for workflow changes before any production trust is granted.

Session duration must cover the operation without creating unnecessarily long access. Short expiration does not undo a destructive action already started. A canceled job can leave partial infrastructure changes, so inspect state and provider events before retrying. Keep the Terraform state and plan protected independently; federation does not encrypt those data stores.

Interview framing

In an interview, explain the token exchange, the trust claims, and the least-privilege role. Name issuer, audience, repository, ref or environment, and why a wildcard is dangerous. Distinguish development plan access from production apply authority. Describe tests for both allowed and denied contexts and how cloud audit events identify a run. Finish by noting that workflow integrity remains part of the trust boundary.

Federation is a strong choice when CI can provide verifiable workload identity and the cloud supports narrow trust conditions. A static secret may remain necessary in legacy systems, but it should be a time-bounded exception with rotation and removal work. The goal is not simply to eliminate a secret field; it is to make identity short-lived, attributable, scoped, and difficult for untrusted code to obtain.

Claim formats are an integration contract between the CI issuer and cloud trust service. Repository renames, branch protection changes, environment naming, and reusable workflow updates can alter the subject or audience that appears in a token. Maintain a small non-production test role to verify expected claims after platform changes, and use cloud audit logs rather than assuming the workflow's displayed repository name is authoritative. If a policy condition stops matching, fail closed and diagnose the claim rather than falling back to a static key.

Restrict token access at the job level. A job should request an identity token only when it needs cloud access, and the token should not be passed to untrusted steps or stored in a cache. Pin third-party actions and protect reusable workflow revisions because trusted workflow code can exercise the role. Use environment approval and branch rules together; a claim for a branch is only as strong as the process protecting that branch.

During an incident, disable the federated trust or narrow its conditions, then review role-assumption logs for the affected window. Short token lifetime limits future use but does not undo completed API calls. Preserve the run id, commit, subject, and cloud principal to support investigation. Test revocation and re-enablement procedures before a production incident so responders do not broaden trust while trying to restore a pipeline.