How to Fix GitHub Actions OIDC AssumeRoleWithWebIdentity Failures on AWS

The failure surfaces at the aws-actions/configure-aws-credentials step of a workflow, after several retried attempts, with output that looks like this:

Run aws-actions/configure-aws-credentials@v4
Assuming role with OIDC
Assuming role with OIDC
Assuming role with OIDC
Error: Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentity

That message is the action's wrapper around a generic AWS STS AccessDenied response to an AssumeRoleWithWebIdentity call. AWS STS deliberately does not tell the caller which part of the request was rejected. It will not say "your aud claim did not match," or "your sub claim was repo:acme/api:environment:prod but the policy expected repo:acme/api:ref:refs/heads/main." Revealing that level of detail to an unauthenticated-looking caller would hand an attacker a way to iterate toward a valid claim value, so STS collapses every rejection reason into one response.

The practical effect is that the same error string covers at least six distinct root causes, only one of which is a genuine IAM permissions problem (the role's permissions boundary or an explicit deny, which is comparatively rare). The rest are trust-policy condition mismatches, and the fix for each looks different once you know which one you're facing.

Before working through the diagnostic steps, confirm you actually have the two pieces this failure assumes are already in place:

Work through these steps in order. Each one narrows down whether the problem is on the GitHub side (the claim the token actually presents) or the AWS side (the condition the trust policy expects).

Step 1: Confirm the workflow requests an ID token at all.

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::111122223333:role/gh-deploy-role
          aws-region: us-east-1

permissions can be set at the workflow level or the job level; a workflow-level read-all or a restrictive org default can silently override a job-level grant, so check both. Missing id-token: write produces a different, more specific error (Error: Not able to fetch an OpenID Connect JWT ID Token), so if you're seeing the AssumeRoleWithWebIdentity error specifically, the token is being issued fine and the problem is downstream of this step.

Step 2: Decode the actual claims the token presents for this exact job.

GitHub documents the underlying request the action makes to fetch the token: a GET to ACTIONS_ID_TOKEN_REQUEST_URL with the workflow's ephemeral bearer token. Add a temporary debug step to see what sub and aud your workflow really produces (never leave this in a workflow that a wide group can trigger, since it prints identity claims to the log):

- name: Debug OIDC token claims
  run: |
    JWT=$(curl -sSL -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
      "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=sts.amazonaws.com" | jq -r '.value')
    echo "$JWT" | cut -d '.' -f2 | base64 -d 2>/dev/null | jq '{sub, aud, repository, ref, job_workflow_ref}'

The sub claim differs depending on how the job triggered: a branch push produces repo:org/repo:ref:refs/heads/main, a job that declares an environment: produces repo:org/repo:environment:name instead (the ref-based form is dropped, not appended), and a pull request from a fork produces repo:org/repo:pull_request. This is precisely the mismatch documented in aws-actions/configure-aws-credentials issue #1137, where adding environment: production to a job broke a trust policy that only matched the branch-ref form, and removing the environment: line made the same policy work again.

Step 3: Read the role's actual trust policy from AWS, not from memory.

aws iam get-role \
  --role-name gh-deploy-role \
  --query 'Role.AssumeRolePolicyDocument' \
  --output json

A correctly scoped trust policy looks like this:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::111122223333:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:acme-corp/api-service:ref:refs/heads/main"
        }
      }
    }
  ]
}

Step 4: Diff the claim from Step 2 against the condition from Step 3, byte for byte. Look specifically for: the audience string (must be exactly sts.amazonaws.com unless you customized audience: in the action's inputs), the claim shape (ref: vs environment: vs pull_request), the exact org and repo name casing, and whether the operator is StringEquals (exact match only) or StringLike (supports * wildcards). A StringEquals condition against a sub value that needs a wildcard, or a sub value written for the wrong claim shape, both produce the identical AccessDenied.

Step 5: Confirm the OIDC provider ARN referenced in the trust policy belongs to the same AWS account as the role, using aws iam list-open-id-connect-providers and comparing the account ID segment of the ARN. A role's trust policy can only reference an OIDC provider registered in that same account; a copy-pasted trust policy from a different account's Terraform module is a common source of this specific mismatch, which is one more reason to treat OIDC provider and role definitions as reviewed infrastructure rather than boilerplate, a gap covered in more depth in this site's guide to Infrastructure as Code security scanning (most IaC scanners check for public S3 buckets and open security groups long before they check whether a sub condition in a Terraform-managed trust policy actually matches your workflow's real claim shape).

After changing the trust policy, validate with both a direct workflow check and an out-of-band AWS-side confirmation, rather than assuming a green checkmark means the condition logic is now correct for every branch and trigger type you use.

In the workflow, add a step immediately after configure-aws-credentials that confirms which identity was actually assumed:

- name: Verify assumed identity
  run: aws sts get-caller-identity

The output's Arn field should show the assumed-role session, formatted as arn:aws:sts::111122223333:assumed-role/gh-deploy-role/GitHubActions. If this step runs, the OIDC exchange succeeded; if it still fails, you have not yet found the mismatched condition.

In AWS CloudTrail, confirm the event and its outcome independently of the workflow log:

aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=EventName,AttributeValue=AssumeRoleWithWebIdentity \
  --max-results 10

Each event's errorCode and errorMessage fields confirm whether a given attempt succeeded or was denied, and the eventTime lets you correlate a specific workflow run to a specific AssumeRoleWithWebIdentity call. CloudTrail does not log the full OIDC token or every individual claim value for privacy and security reasons, so it confirms whether the call succeeded and roughly when, but it will not hand you the exact claim that mismatched; that still comes from decoding the token in Step 2 above. Re-run the debug decode step against every trigger type your workflow actually uses (a normal push, a pull request from a fork, a manual workflow_dispatch, a run inside a declared environment:) since each can produce a different sub shape and a trust policy that passes for one can still fail for another.

These are not hypothetical failure modes. Each of the following has a documented GitHub issue or official AWS/GitHub guidance behind it.

Use this checklist to jump directly to the likely cause based on what changed or what you observe, before working through the full diagnostic procedure above.

The fastest way to make this error disappear is to loosen the sub condition to something broad, such as repo:acme-corp/* or, worse, dropping the sub condition entirely and relying only on the aud check. Both make the trust policy pass regardless of which repository, branch, or workflow in the organization is requesting the role, which is precisely the property you don't want.

An overly broad sub condition means any workflow in any repository under that GitHub organization, including a low-privilege internal tool, a public fork with Actions enabled, or a compromised dependency's postinstall script running inside CI, can assume the same role as your production deployment pipeline. The trust policy is the only thing standing between "a GitHub Actions job exists somewhere in this org" and "this job can obtain AWS credentials for this specific role." Widening the sub condition to make a debugging session end faster converts a scoped, single-repository, single-branch credential into an organization-wide one, which is exactly the kind of non-human identity sprawl that makes lateral movement from a single compromised workflow into a much larger blast radius; see this site's broader guide to non-human identity security for how these federated identities fit into the wider inventory of service accounts, API keys, and machine identities most organizations under-track relative to their human accounts.

The better fix, in every case above, is to identify the exact claim shape your workflow legitimately produces and scope the condition to match that shape precisely, using StringLike with a narrow wildcard only where genuinely necessary (for example, matching any tag under refs/tags/v* for a release workflow), rather than widening the match to make the error go away without understanding why it was failing.