GitHub Actions OIDC Trust Policy Security

OIDC replaces a secret with a live authorization decision

GitHub Actions OIDC trust policy security fails when the cloud accepts a valid GitHub token without proving that the exact repository, ref, environment, and workflow should receive the requested role. The signature proves GitHub issued the token. It does not make every GitHub workflow an authorized deployer.

A workflow job with id-token: write requests a short-lived JSON Web Token from GitHub’s issuer. The cloud security token service validates issuer, audience, expiry, and configured claims, then creates temporary credentials. This removes long-lived cloud keys from repository secrets and reduces standing credential exposure.

Authority moves rather than disappears. A compromised workflow, unsafe pull-request path, mutable third-party action, or overly broad subject wildcard can request a fresh token on demand. Pair federation with CI/CD secrets management, least-privilege role permissions, protected deployment environments, pinned dependencies, and cloud-side audit.

Validate claims that describe the deployment boundary

The GitHub OIDC reference documents claims including iss, aud, sub, repository and owner identifiers, ref, environment, actor, event, workflow, and reusable-workflow context. Provider support differs, so design from the claims the destination can actually enforce.

For AWS, validate aud as sts.amazonaws.com when using the normal integration and constrain sub to the intended repository plus branch or protected environment. AWS now documents immutable repository_id, repository_owner_id, and related identifiers as safer than names where claim support and rollout state permit. Names can be renamed and later reclaimed.

This authored trust-policy fragment illustrates the decision shape; replace identifiers and verify the token format enabled for your repositories:

"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:repository_owner_id": "1234567",
    "token.actions.githubusercontent.com:repository_id": "7654321",
    "token.actions.githubusercontent.com:ref": "refs/heads/main"
  }
}

The AWS OIDC condition-key guidance is authoritative for supported mappings. Do not paste conditions from another cloud or assume every custom GitHub claim is available in AWS.

The workflow path must be as controlled as the token subject

A branch-bound subject is weak when anyone can merge unreviewed workflow changes into that branch. Protect the repository and environment: required review, deployment branch restrictions, separate production environments, minimal GITHUB_TOKEN permissions, and no production credentials in jobs that execute untrusted pull-request code.

Reusable workflows can centralize deployment controls. GitHub tokens include job_workflow_ref for the called workflow, and the reusable workflow identity guidance explains provider-dependent enforcement. Pin the reusable workflow to a reviewed commit when practical; trusting @main permits future changes to redefine the deployment path.

Third-party actions execute inside the job’s authority boundary. Pin actions to reviewed full commit SHAs or an enforced lock mechanism, constrain credentials to the smallest job, and request the OIDC token immediately before exchange. A malicious earlier step can alter artifacts or workspace state even if it cannot read a token that has not yet been minted.

Correlate the workflow run with the cloud role session

Preserve GitHub run ID, job, workflow path and commit, repository ID, ref, environment, actor, event, token subject, audience, cloud role, and cloud session identifier. On the cloud side, alert on web-identity role assumptions that violate the deployment baseline, occur from unexpected repositories or refs, use new roles, or lead to unusual resource actions.

A successful role assumption proves the trust policy matched. It does not prove the artifact was reviewed or the workflow was uncompromised. Join the cloud audit event back to the exact GitHub run, then connect deployment actions to build provenance and artifact signing. Preserve gaps when a provider does not expose every token claim in the session audit.

Test with a non-production role and an authored workflow matrix: approved branch, pull request, fork, tag, environment, renamed repository, and reusable workflow at an unapproved ref. Label these events as simulation. A denial is expected evidence, not a failed test, when an untrusted context requests authority.

Migrate from stored keys without creating wildcard trust

Inventory existing deployment keys and map each to repository, workflow, environment, target account, permissions, owner, and rotation path. Create separate roles for materially different deployment purposes. Begin with exact conditions and a non-production target, observe denied assumptions, then expand only for documented workflows.

Run old and new authentication paths in a short controlled overlap if availability requires it. Remove the stored key after OIDC evidence is stable; leaving it active preserves the old attack path. Rollback should restore a narrowly controlled deployment mechanism, not a permanent administrator secret.

Monitor policy changes as high-impact control-plane events. A pull request that safely changes application code can become dangerous when paired with an out-of-band trust-policy wildcard.

Make federation evidence part of the release record

Next step: choose one production deployment and document its issuer, audience, immutable repository identity, ref or environment, reusable workflow, exact role, permissions, and audit join key. Then test every disallowed context before removing the old secret.

Connect the result to your software supply chain attacks model. A trustworthy release should show not only what artifact was built, but which reviewed workload received cloud authority to publish or deploy it.