How to Use OIDC to Authenticate GitHub Actions to AWS

Stop storing AWS keys in secrets. OIDC lets GitHub Actions assume an IAM role with short-lived credentials.

OpenID Connect lets a workflow exchange its identity token for temporary AWS credentials, so you never store static keys. Set up the IAM trust once.

Steps

1. Add the GitHub OIDC provider to AWS IAM (token.actions.githubusercontent.com).
2. Create an IAM role with a trust policy scoped to your repo/branch (sub condition).
3. Grant the role only the permissions the workflow needs.
4. Add permissions: id-token: write to the job.
5. Use aws-actions/configure-aws-credentials with role-to-assume.

Workflow snippet

permissions:
  id-token: write
  contents: read
steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::1234567890:role/gha-deploy
      aws-region: us-east-1

Common pitfalls

• Forgetting id-token: write → "Unable to get OIDC token".
• Trust policy sub too broad or mismatched → AssumeRole denied.
• Wrong audience (aud) value.

Related guides