CloudConsole

GitHub Actions OIDC: IAM role trust policy

Updated 17 November 2026 · How we write and check guides

Short answer

Register GitHub's OIDC token issuer as an identity provider in IAM, then give the role a trust policy allowing sts:AssumeRoleWithWebIdentity from it when the audience is sts.amazonaws.com and the subject (sub) names your repository and branch. No long-lived keys are stored in GitHub.

Policy diagram: 1 statement(s); first Allow sts:AssumeRoleWithWebIdentity on * (all resources)
The policy on this page drawn statement by statement: who it applies to, the actions, the resources and any condition.

The trust policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GitHubActionsMainBranch",
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:my-org/my-repo:ref:refs/heads/main"
        }
      }
    }
  ]
}

Then attach a permissions policy to the role with only what the workflow deploys, for example ECR push or S3 uploads.

What the conditions check

  • Principal.Federated: tokens must come from the GitHub OIDC provider registered in your account.
  • :aud: the audience the official configure-aws-credentials action requests, sts.amazonaws.com.
  • :sub: who is asking. This is the condition that keeps every other GitHub repository in the world out. Its format depends on what triggered the job:
Triggersub value
Push to a branchrepo:my-org/my-repo:ref:refs/heads/main
Tagrepo:my-org/my-repo:ref:refs/tags/v1.2.0
Job with environment: productionrepo:my-org/my-repo:environment:production
Pull requestrepo:my-org/my-repo:pull_request

Note that a job using an environment gets the environment form, not the branch form, even when it runs on main. That is the usual reason a working role suddenly fails with "Not authorized to perform sts:AssumeRoleWithWebIdentity".

Set it up

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com

aws iam create-role --role-name github-deploy \
  --assume-role-policy-document file://github-trust.json

AWS secures this provider using its own trusted certificate authorities, so you no longer need to supply a thumbprint. In the workflow:

permissions:
  id-token: write
  contents: read
steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789012:role/github-deploy
      aws-region: eu-west-2

Debug a failing assume

The quickest check is the token's actual claims. Print the sub from a test workflow, compare it with the trust policy, and look for the failed AssumeRoleWithWebIdentity event in CloudTrail, which records the subject and the reason.

aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=EventName,AttributeValue=AssumeRoleWithWebIdentity \
  --max-results 5 --query 'Events[].CloudTrailEvent' 

Variations and dangerous mistakes

  • Several branches or all branches: switch to StringLike and use repo:my-org/my-repo:ref:refs/heads/release-* or repo:my-org/my-repo:*. Keep the organisation and repository literal.
  • Dangerous: no sub condition, or repo:*. Any public repository can then mint a token and assume your role. Never deploy a trust policy without a sub condition naming your organisation.
  • Pull requests from forks should not get a deploy role. Give PR workflows a separate read-only role, or none.
  • Missing id-token: write in the workflow permissions: the action fails before reaching AWS, with an error about fetching the OIDC token.
  • GitHub Enterprise Server or a customised issuer uses a different provider URL and condition key prefix.

Questions

Do I still need a thumbprint for the GitHub OIDC provider?

No. AWS validates GitHub's certificate itself. The ThumbprintList parameter is optional and any value you supply is not used for this provider.

Why does sts:AssumeRoleWithWebIdentity fail only for some jobs?

The sub claim differs by trigger. Jobs using an environment, tags or pull requests send a different sub from branch pushes. Check the trigger against the table above.

Can one role trust several repositories?

Yes. Use StringLike with a list of sub patterns, one per repository. Keep each pattern as specific as you can.

When this happens away from your desk

Deploys from GitHub often finish while you are away from your desk. Knowing which role a run assumed, and what it changed, is a CloudTrail lookup you can do from a phone.

About the app → · Download on the App Store

Sources