Every GitHub repository in the world gets OIDC tokens from the same issuer, so a cloud trust policy that checks only the issuer and audience will hand your cloud role to anyone who can run a workflow. Replacing stored cloud keys with GitHub Actions OIDC removes long-lived secrets, but it moves the security decision into the trust condition on the cloud side: which repository, which branch or environment, which workflow file and which runner type may exchange a token for credentials. This guide covers how the GitHub OIDC token is built, how to pin trust in AWS, Microsoft Entra ID and Google Cloud, how to use environments and subject customisation so a trust cannot be borrowed by another repository, branch or pull request, and how to log and detect misuse. It assumes you know the basics of federation; for that, see the Workload Identity Federation Guide. Product details are from GitHub, AWS, Microsoft and Google documentation checked on 27 October 2026.
This is an independent guide from NHI Mgmt Group, based on GitHub's public documentation as of November 2026. It is not sponsored or reviewed by GitHub. Product features change, so confirm settings against GitHub's current documentation.
Key takeaways
- The subject claim is the trust boundary. Pin
subto an exact repository and environment or branch with an equality match; arepo:org/*orrepo:org/repo:*pattern trusts far more than you intend. - Use deployment environments as the gate. Environment-scoped subjects (
repo:org/repo:environment:prod) combined with deployment branch rules and required reviewers stop a feature branch or pull request from reaching production credentials. - Prefer immutable IDs over names. Repositories created after 15 July 2026 get a subject containing owner and repository IDs; older repositories can opt in. Names can be re-registered after deletion, IDs cannot.
- OIDC does not fix a poisoned workflow. Anyone who can change workflow code on a trusted ref can mint the token, so pin actions to commit SHAs, protect
.github/workflowswith code owners and avoidpull_request_targetwith untrusted code. - One role per trust, least privilege per role. Separate roles for plan, deploy and read-only jobs, with short session durations, and alert on
AssumeRoleWithWebIdentityfrom unexpected subjects.
How identity and access work in GitHub Actions OIDC
When a job has the id-token: write permission, the runner can request a signed JWT from GitHub's issuer, https://token.actions.githubusercontent.com. GitHub documents that the permission only allows requesting the token; it does not grant write access to any other resource. The cloud provider validates the signature, issuer, audience and the claims you specify, then returns short-lived cloud credentials. GitHub describes the token as valid for a single job and short-lived.
Claims that matter for trust decisions
| Claim | Example value | Use in a trust condition |
|---|---|---|
sub | repo:octo-org/octo-repo:environment:Production | Primary match; format depends on environment, event and ref (see below) |
aud | sts.amazonaws.com, api://AzureADTokenExchange | Must equal the value the cloud expects; default is the repository owner URL |
repository_id, repository_owner_id | Numeric IDs | Stable across renames; resist re-registration of deleted names |
environment | prod | Ties credentials to a protected deployment environment |
ref, ref_type | refs/heads/main, branch | Restrict to a branch or tag |
job_workflow_ref, job_workflow_sha | octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main | Restrict to a central, reviewed reusable workflow |
workflow_ref | Path and ref of the calling workflow file | Restrict which workflow file may deploy |
event_name | push, pull_request, dynamic (Dependabot) | Allow only the events your deployment uses |
runner_environment | github-hosted or self-hosted | Keep production trust off self-hosted runners you do not fully control |
repository_visibility | internal, private, public | Block public repositories from sensitive roles |
Subject formats
- Environment:
repo:ORG/REPO:environment:NAME, used whenever the job references an environment. - Pull request:
repo:ORG/REPO:pull_request, used when there is no environment. Microsoft's documentation writes this aspull-request; check the value in a real token before writing the credential. - Branch or tag:
repo:ORG/REPO:ref:refs/heads/BRANCHorrepo:ORG/REPO:ref:refs/tags/TAG, used when there is no environment and the event is not a pull request. - Immutable default:
repo:OWNER@OWNER-ID/REPO@REPO-ID:ref:refs/heads/BRANCHfor repositories created after 15 July 2026, and for repositories renamed or transferred after that date. Older repositories keep the name-based format unless they opt in at organisation or repository level. This format is not available on GitHub Enterprise Server, so match your trust policy to what your repository actually emits. - Customised templates: the REST endpoint
PUT /repos/{owner}/{repo}/actions/oidc/customization/subacceptsinclude_claim_keys, for example["repo", "context", "job_workflow_ref"], which produces a subject that names both the environment and the reusable workflow. GitHub warns that a template of only["repo"]grants access across all branches, tags and environments. Create the matching cloud condition before changing the template, or tokens will be rejected.
Pinning trust in each cloud
| Cloud | Where trust lives | Matching behaviour | Built-in guardrail | Hardened pattern |
|---|---|---|---|---|
| AWS IAM | Role trust policy with sts:AssumeRoleWithWebIdentity | StringEquals or StringLike on token.actions.githubusercontent.com:sub and :aud | IAM rejects a GitHub trust policy whose sub condition is missing or only a wildcard or null | StringEquals on aud = sts.amazonaws.com and an exact environment subject |
| Microsoft Entra ID | Federated identity credential on an app registration or user-assigned managed identity | Exact match on issuer, subject and audience; no wildcards | Exact match by design; maximum of 20 federated credentials per application or managed identity | One credential per environment subject, audience api://AzureADTokenExchange |
| Google Cloud | Workload identity pool provider with attribute mapping and attribute condition | CEL attribute condition on mapped claims | Google says you must set an attribute condition, because GitHub uses one issuer for all organisations | Condition on repository_owner_id and repository_id, plus ref or environment; grant roles to a narrow principalSet |
AWS
- AWS warns that if the
subkey is not limited to an organisation or repository, workflows from organisations outside your control can assume the role. The save-time check only rejects a bare wildcard:repo:GitHubOrg/*still passes and trusts every repository in the organisation, and AWS advises a narrower value. - Prefer
StringEqualswith a list of exact subjects overStringLike. If you must use a pattern, constrain it to one repository and add a second condition such asjob_workflow_refwhere your provider and claims allow it. GitHub notes that custom OIDC claims are not supported in AWS conditions, so in AWS the subject template carries the extra context. - Set a short
MaxSessionDurationon the role and keep one role per purpose (for example read-only plan versus deploy). See the AWS IAM Policies and Roles Guide.
Microsoft Entra ID
- Subjects must exactly match. A wrong subject does not fail when you create the credential; the token exchange fails later without a clear message, so test in a pilot pipeline.
- Pattern matching is not supported for branches and tags. Microsoft recommends using an environment where a push workflow runs against many branches. A flexible federated identity credential option with claim matching expressions is in preview; treat it as a pattern match and review it with the same care as an AWS
StringLike. - Creating or changing federated credentials requires the app owner or roles such as Application Administrator or Cloud Application Administrator, which makes those roles part of your CI/CD attack surface. See the Azure Managed Identities Security Guide.
Google Cloud
- Map at least
google.subject=assertion.sub, and map any claim you use in a condition. Google warns that name-based claims such asrepositoryandrepository_ownercarry a cybersquatting and typosquatting risk if a name is deleted and re-registered; use the numeric*_idclaims. - Google recommends direct resource access, granting roles to the federated principal on the resource. Where an API needs it, use service account impersonation with
roles/iam.workloadIdentityUsergranted to a specificprincipal://orprincipalSet://member, not the whole pool. See the Google Cloud IAM and Service Accounts Guide.
Admin roles and privileged access
The people who can change any link in the chain can issue themselves cloud credentials. Treat these as privileged roles and review them with the same rigour as cloud administrators.
| Control point | Who can change it | What a change enables | Control |
|---|---|---|---|
| Workflow files on a trusted branch | Anyone with write access who can merge | Run arbitrary code with the trusted subject | Branch protection, CODEOWNERS on .github/workflows, required reviews |
| Environment protection rules | Repository administrators | Remove reviewers or branch limits on a production environment | Disallow admin bypass, audit environment changes |
| OIDC subject template | Repository or organisation administrators | Change what the cloud sees as the subject | Manage templates centrally, alert on changes |
| Cloud trust policy or federated credential | IAM administrators, Entra application administrators, GCP IAM admins | Widen trust to other repositories | Infrastructure as code with review, policy-as-code checks on wildcards |
| Self-hosted runner hosts | Runner operators | Steal tokens from jobs on the host | Ephemeral runners, no production trust for self-hosted unless isolated |
Environment protection features vary by plan: GitHub documents that for private repositories on Free, Pro and Team plans, required reviewers, wait timers, custom protection rules and the admin bypass setting are available for public repositories only, while deployment branch and tag rules are available on Pro and Team. Check what your plan provides before relying on reviewers as a control. Required reviewers can be up to six users or teams, and an optional setting prevents the person who triggered a deployment from approving it.
Integrations, API tokens and service accounts
- Remove the stored keys you replaced: once a job uses OIDC, delete the old cloud access keys or service principal secrets from repository, environment and organisation secrets, and deactivate them in the cloud. OWASP lists static pipeline credentials under NHI6 Insecure Cloud Deployment Configurations. See the OWASP NHI Top 10 NHI6 Insecure Cloud Deployment Configurations Guide.
- Scope the GITHUB_TOKEN: set read-only defaults and raise permissions per job. Grant
id-token: writeonly to the jobs that federate, not at workflow level. - Centralise deployment in reusable workflows: a reviewed reusable workflow in a central repository, matched through
job_workflow_refin the subject, means individual repositories cannot alter the deployment steps that hold the credential. - Bot and maintainer tokens: OIDC covers cloud access, not tokens such as personal access tokens used to push tags or publish packages. The tj-actions/changed-files compromise began with a stolen bot account token that let attackers move release tags and dump runner memory, exposing cloud keys and other secrets into public logs. Replace such tokens with GitHub App tokens or OIDC where possible. See the GitHub Personal Access Tokens Security Guide.
- Third-party actions: any action in a job that holds the OIDC token can request or read it. Pin actions to full commit SHAs verified against the action's own repository, or use lockfiles where adopted, which GitHub describes as stronger than SHA pinning.
Logging and detection
| Source | Event or field | What to alert on |
|---|---|---|
| AWS CloudTrail | AssumeRoleWithWebIdentity: userIdentity.type WebIdentityUser, userName and responseElements.subjectFromWebIdentityToken carry the subject; roleArn, roleSessionName | Subjects not on the allow list for that role, new repositories, pull_request subjects on deploy roles, assumptions outside deployment windows |
| Microsoft Entra ID | Service principal sign-in logs for the application | Sign-ins for federated credentials not used by any approved pipeline, failed exchanges after credential changes |
| Google Cloud | Cloud Audit Logs for the Security Token Service and the target resources | Token exchanges from unexpected principal:// subjects |
| GitHub | Organisation audit log and workflow run history | Changes to environment protection rules, OIDC subject templates and workflow files; runs on unexpected refs |
Correlate cloud sessions back to the run: put github.run_id into the AWS role session name so CloudTrail actions can be traced to a specific job. Metrics that show the programme is working:
- Percentage of cloud deployments using OIDC rather than stored keys, and count of remaining static cloud secrets in GitHub.
- Number of trust policies or federated credentials using wildcards or name-based conditions (target zero for production).
- Percentage of production roles bound to an environment subject with protection rules.
- Percentage of third-party actions pinned to SHAs in workflows that request OIDC tokens.
- Count of
AssumeRoleWithWebIdentityevents from subjects outside the allow list (should be zero, and investigated when not).
See the AWS CloudTrail Guide for collection and retention.
Hardening baseline
- Inventory: list every cloud role, federated credential and pool provider that trusts
token.actions.githubusercontent.com, with its condition, and every stored cloud secret in GitHub. - Classify trust: flag conditions that use wildcards, name-based owners,
pull_requestsubjects on write roles, or["repo"]templates. - Create protected environments: one per deployment target, with deployment branch rules, required reviewers where your plan supports them and admin bypass disabled.
- Re-pin trust: move production roles to exact environment subjects, or to
repo+context+job_workflow_reftemplates for central reusable workflows. Adopt immutable ID subjects where available. - Test in a pilot: run the new condition in a non-production account first. For Entra ID, expect silent failures on mismatches and check a decoded token. Keep the old role in place but unused during the pilot.
- Cut over and remove keys: switch the workflow, then delete stored keys and disable them in the cloud.
- Roll back: if deployments fail, revert the workflow to the previous role ARN or credential through a reviewed change; never roll back by re-adding a wildcard.
- Guard with policy as code: add CI checks that reject trust policies with
StringLikeonsubbeyond one repository, and alert on drift.
Decision guidance: small teams with a handful of repositories can pin exact environment subjects per repository and stop there. Large organisations should centralise deployments in reusable workflows and include job_workflow_ref in subjects, so hundreds of repositories share a small number of reviewed trust relationships. Choose branch subjects only where environments are unavailable on your plan, and never trust pull_request subjects for anything beyond read-only test resources.
Framework mapping
| Framework | Reference | Relevance |
|---|---|---|
| OWASP NHI Top 10 | NHI6:2025 Insecure Cloud Deployment Configurations; NHI7 Long-Lived Secrets | Unrestricted sub trust and static pipeline keys |
| NIST CSF 2.0 | PR.AA-01, PR.AA-05 | Managed workload credentials; least privilege access |
| NIST SP 800-53 Rev. 5 | IA-9, AC-6, SR-3, AU-12 | Service authentication, least privilege, supply chain controls, audit generation |
| MITRE ATT&CK | T1078.004, T1195.002, T1528 | Valid cloud accounts via borrowed trust, compromised workflow supply chain, theft of access tokens |
Common misconfigurations
- Organisation-wide or repository-wide wildcards:
repo:org/*passes the AWS save-time check but lets any repository, including a new or forked-in one, assume the role;repo:org/repo:*includes every branch and pull request. - Trusting name-based owners: a Google attribute condition on
repository_owneror an old name-based subject can be satisfied by whoever registers a deleted organisation or repository name. - Environments without protection: an environment subject means nothing if any branch can deploy to it and admins can bypass the rules.
- Pull request triggers with credentials: granting
id-token: writeinpull_request_targetworkflows that check out untrusted code gives fork authors your token. GitHub says such workflows must not explicitly check out untrusted code. - Self-hosted runners in trust: a persistent runner shared across repositories lets one compromised job read tokens from the next. GitHub advises self-hosted runners should almost never be used for public repositories.
- Keeping the old keys: migrating to OIDC but leaving the original access keys in secrets leaves the exposure in place. In the Megalodon GitHub Actions attack, injected workflows harvested both static cloud keys and OIDC tokens; the OIDC tokens expire within minutes and reach only what the trust policy allows, while static keys stay usable until someone revokes them.
Practitioner checklist
- Inventory every trust on
token.actions.githubusercontent.comacross AWS, Entra ID and Google Cloud. - Pin
audandsubwith exact matches; remove organisation-wide and repository-wide wildcards. - Bind production roles to protected environments with branch rules, reviewers and no admin bypass.
- Use numeric owner and repository IDs or the immutable subject format where available.
- Grant
id-token: writeper job, and keepGITHUB_TOKENread-only by default. - Pin third-party actions to verified commit SHAs and protect workflow files with code owners.
- Keep production trust off shared self-hosted runners.
- Delete stored cloud keys once OIDC is live and verify they are disabled in the cloud.
- Alert on token exchanges from subjects outside the allow list and on changes to trust, environments and subject templates.
- Enforce trust-policy rules with policy-as-code in the infrastructure pipeline.
Standards and references
- GitHub Docs: OpenID Connect reference
- GitHub Docs: OpenID Connect
- GitHub Docs: Secure use reference
- GitHub Docs: Deployments and environments
- AWS: Create a role for OpenID Connect federation
- Microsoft Learn: Configure an app to trust an external identity provider
- Google Cloud: Configure Workload Identity Federation with deployment pipelines
- OWASP: NHI6:2025 Insecure Cloud Deployment Configurations
Related NHI Mgmt Group resources: Workload Identity Federation Guide · GitHub and GitHub Actions Security Guide · CI/CD Pipeline Identity Security Guide · OWASP NHI Top 10 NHI6 Insecure Cloud Deployment Configurations Guide