Join our Newsletter — 33% off our NHI Course
Home› Guides› GitHub Actions OIDC Federation Hardening Guide: Trust Policies…
Guide Cloud & Workload Identity

GitHub Actions OIDC Federation Hardening Guide: Trust Policies That Cannot Be Borrowed

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 8 November 2026 15 min read
On this page

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 sub to an exact repository and environment or branch with an equality match; a repo:org/* or repo: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/workflows with code owners and avoid pull_request_target with 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 AssumeRoleWithWebIdentity from 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

ClaimExample valueUse in a trust condition
subrepo:octo-org/octo-repo:environment:ProductionPrimary match; format depends on environment, event and ref (see below)
audsts.amazonaws.com, api://AzureADTokenExchangeMust equal the value the cloud expects; default is the repository owner URL
repository_id, repository_owner_idNumeric IDsStable across renames; resist re-registration of deleted names
environmentprodTies credentials to a protected deployment environment
ref, ref_typerefs/heads/main, branchRestrict to a branch or tag
job_workflow_ref, job_workflow_shaocto-org/octo-automation/.github/workflows/oidc.yml@refs/heads/mainRestrict to a central, reviewed reusable workflow
workflow_refPath and ref of the calling workflow fileRestrict which workflow file may deploy
event_namepush, pull_request, dynamic (Dependabot)Allow only the events your deployment uses
runner_environmentgithub-hosted or self-hostedKeep production trust off self-hosted runners you do not fully control
repository_visibilityinternal, private, publicBlock 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 as pull-request; check the value in a real token before writing the credential.
  • Branch or tag: repo:ORG/REPO:ref:refs/heads/BRANCH or repo: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/BRANCH for 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/sub accepts include_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

CloudWhere trust livesMatching behaviourBuilt-in guardrailHardened pattern
AWS IAMRole trust policy with sts:AssumeRoleWithWebIdentityStringEquals or StringLike on token.actions.githubusercontent.com:sub and :audIAM rejects a GitHub trust policy whose sub condition is missing or only a wildcard or nullStringEquals on aud = sts.amazonaws.com and an exact environment subject
Microsoft Entra IDFederated identity credential on an app registration or user-assigned managed identityExact match on issuer, subject and audience; no wildcardsExact match by design; maximum of 20 federated credentials per application or managed identityOne credential per environment subject, audience api://AzureADTokenExchange
Google CloudWorkload identity pool provider with attribute mapping and attribute conditionCEL attribute condition on mapped claimsGoogle says you must set an attribute condition, because GitHub uses one issuer for all organisationsCondition on repository_owner_id and repository_id, plus ref or environment; grant roles to a narrow principalSet

AWS

  • AWS warns that if the sub key 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 StringEquals with a list of exact subjects over StringLike. If you must use a pattern, constrain it to one repository and add a second condition such as job_workflow_ref where 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 MaxSessionDuration on 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 as repository and repository_owner carry a cybersquatting and typosquatting risk if a name is deleted and re-registered; use the numeric *_id claims.
  • 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.workloadIdentityUser granted to a specific principal:// or principalSet:// 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 pointWho can change itWhat a change enablesControl
Workflow files on a trusted branchAnyone with write access who can mergeRun arbitrary code with the trusted subjectBranch protection, CODEOWNERS on .github/workflows, required reviews
Environment protection rulesRepository administratorsRemove reviewers or branch limits on a production environmentDisallow admin bypass, audit environment changes
OIDC subject templateRepository or organisation administratorsChange what the cloud sees as the subjectManage templates centrally, alert on changes
Cloud trust policy or federated credentialIAM administrators, Entra application administrators, GCP IAM adminsWiden trust to other repositoriesInfrastructure as code with review, policy-as-code checks on wildcards
Self-hosted runner hostsRunner operatorsSteal tokens from jobs on the hostEphemeral 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: write only 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_ref in 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

SourceEvent or fieldWhat to alert on
AWS CloudTrailAssumeRoleWithWebIdentity: userIdentity.type WebIdentityUser, userName and responseElements.subjectFromWebIdentityToken carry the subject; roleArn, roleSessionNameSubjects not on the allow list for that role, new repositories, pull_request subjects on deploy roles, assumptions outside deployment windows
Microsoft Entra IDService principal sign-in logs for the applicationSign-ins for federated credentials not used by any approved pipeline, failed exchanges after credential changes
Google CloudCloud Audit Logs for the Security Token Service and the target resourcesToken exchanges from unexpected principal:// subjects
GitHubOrganisation audit log and workflow run historyChanges 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 AssumeRoleWithWebIdentity events from subjects outside the allow list (should be zero, and investigated when not).

See the AWS CloudTrail Guide for collection and retention.

Hardening baseline

  1. 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.
  2. Classify trust: flag conditions that use wildcards, name-based owners, pull_request subjects on write roles, or ["repo"] templates.
  3. Create protected environments: one per deployment target, with deployment branch rules, required reviewers where your plan supports them and admin bypass disabled.
  4. Re-pin trust: move production roles to exact environment subjects, or to repo + context + job_workflow_ref templates for central reusable workflows. Adopt immutable ID subjects where available.
  5. 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.
  6. Cut over and remove keys: switch the workflow, then delete stored keys and disable them in the cloud.
  7. 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.
  8. Guard with policy as code: add CI checks that reject trust policies with StringLike on sub beyond 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

FrameworkReferenceRelevance
OWASP NHI Top 10NHI6:2025 Insecure Cloud Deployment Configurations; NHI7 Long-Lived SecretsUnrestricted sub trust and static pipeline keys
NIST CSF 2.0PR.AA-01, PR.AA-05Managed workload credentials; least privilege access
NIST SP 800-53 Rev. 5IA-9, AC-6, SR-3, AU-12Service authentication, least privilege, supply chain controls, audit generation
MITRE ATT&CKT1078.004, T1195.002, T1528Valid 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_owner or 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: write in pull_request_target workflows 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.com across AWS, Entra ID and Google Cloud.
  • Pin aud and sub with 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: write per job, and keep GITHUB_TOKEN read-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

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

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 8 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.