Make GitHub Actions OIDC trust depend on the claims you can enforce
GitHub Actions can obtain a short-lived OpenID Connect token and exchange it for cloud access without storing a long-lived cloud secret in the repository. The convenience shifts the security question to the trust policy outside GitHub. That policy must decide which token subjects and audiences are allowed to assume which role.
The subject is a scoped statement
GitHub documents the OIDC token's subject and audience claims as the values a cloud provider checks against a preconfigured trust definition. The default subject can identify the repository and context, and organizations can customize the format to require claims such as job_workflow_ref. A custom audience can also be supplied when an action needs one.
The subject is not merely a repository name. Different workflow triggers can produce different subject claims, so a policy that accepts a broad pattern may include workflows the role owner did not intend. Pull request workflows, branch workflows, environment jobs, and reusable workflows can carry different context. Review the actual claim for each trusted path.
GitHub provides an OIDC debugger action to visualize claims before integrating a provider. Use a non-production role for that test. A copied example policy is not evidence that the claim format in the organization matches the example.
Build a narrow trust policy
The cloud trust policy should combine the issuer, audience, subject, and any provider-specific conditions that distinguish the intended workflow. Require the repository owner and repository identity, not just a human-readable name. Where the provider supports immutable repository identifiers, use them to reduce the effect of future renames.
Add environment protection rules when a workflow uses an environment. A trust condition that references an environment is stronger when the environment has reviewers or deployment restrictions. Otherwise the claim identifies a context that any eligible workflow may be able to request.
Separate deployment roles by environment and purpose. A production deployment role should not be assumable by every branch or every pull request workflow. A read-only inventory job should not receive a role that can change infrastructure. The cloud provider's session policy can narrow the exchange further.
Watch for workflow-level changes
The trust policy can remain unchanged while a workflow change expands who can obtain a token. A new permissions block, a new reusable workflow, a changed branch protection rule, or a new environment reviewer can alter the path. Treat those changes as security-sensitive.
Review actions that receive the OIDC token. A third-party action with unnecessary token access can exchange it for credentials if the trust policy permits its subject. Pin actions to reviewed versions, limit workflow permissions, and avoid passing tokens into steps that do not need them. The token itself is short lived, but the cloud session it creates may outlive the job.
Log the assumed role and the token claims that the provider accepted. Do not log the token. Alert on a new subject assuming a sensitive role, an unexpected audience, or a role assumption from a workflow that normally has no cloud access.
Test the negative cases
Attempt the exchange from an untrusted branch, a workflow without the required environment, a reusable workflow whose subject differs, and a token with the wrong audience. Every case should fail. Then test the intended workflow and confirm the resulting cloud session has only the permissions the job needs.
GitHub Actions OIDC reduces standing credentials when the trust policy is precise. The design should make the accepted workflow identity explicit and test the claim values that the cloud provider actually sees.
Top comments (0)