Not authorized to perform: sts:AssumeRoleWithWebIdentity

WHAT IT MEANS

What this error means

The workflow asked STS to exchange a GitHub OIDC token for temporary AWS credentials via AssumeRoleWithWebIdentity, and STS said no. The token itself arrived, so the network path and the credentials action are working. The mismatch is between what the token claims and what the IAM role's trust policy requires. In practice one of three things is wrong:

• The job never got a real token. The workflow or job is missing the id-token: write permission, so the credentials action falls back and STS receives nothing it can trust.
• The audience does not match. The trust policy checks token.actions.githubusercontent.com:aud, and the token was minted for something other than sts.amazonaws.com.
• The sub condition does not match this run. The trust policy pins a repository, branch, tag, or GitHub Environment, and the job that ran does not match it exactly — a renamed repo, a deploy from a different branch, or an Environment name that differs from the condition.

FIX

How to fix it

1. Confirm the job can request a token. The workflow or the deployment job must declare:

   permissions:
     id-token: write
     contents: read

   A job-level permissions block overrides the workflow-level one, and reusable workflows need the permission granted by the caller.
2. Check the audience. The role trust policy should accept token.actions.githubusercontent.com:aud equal to sts.amazonaws.com — that is what aws-actions/configure-aws-credentials requests by default. If you passed a custom audience input, the trust policy must match it.
3. Compare the sub condition with the actual run. A branch deploy produces a claim like repo:OWNER/REPO:ref:refs/heads/main; a job bound to a GitHub Environment produces repo:OWNER/REPO:environment:NAME instead. The two forms are not interchangeable. Use StringLike with an explicit wildcard only where you have decided that breadth is acceptable. Note that newer repositories can include immutable owner and repository IDs in the claim.
4. Verify the OIDC provider exists in the target account. The account needs an IAM OIDC identity provider for token.actions.githubusercontent.com, and the role's federated principal must name that provider's ARN. Assuming a role in the wrong account is a common variant of this failure.
5. Re-run the deploy only after a trust-policy check passes. Rotating secrets or widening permissions does not help here — the failure is in the trust relationship, not in an identity policy.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor recognizes this failure (high confidence) plus the neighboring OIDC variants — missing id-token: write, wrong audience, and missing OIDC provider — and tells you which one your log shows. Runs locally; no AWS access, no log upload.

python -m pip install sam-doctor
sam-doctor diagnose deployment.log --format markdown

RELATED

Related errors

• The security token included in the request is expired — the credentials worked earlier and then aged out mid-job.
• no basic auth credentials — the OIDC role works but the runner never logged in to ECR.
• InsufficientCapabilitiesException — the identity is fine and CloudFormation wants an explicit IAM acknowledgement.

Longer walkthrough: the OIDC deployment debugging guide.