How to Assume an AWS Role With OIDC Instead of Static Keys in GitHub Actions

OIDC lets the runner exchange a signed GitHub token for temporary AWS credentials, so no static access keys live in the repo.

Grant id-token: write, then use aws-actions/configure-aws-credentials with role-to-assume. The action calls AssumeRoleWithWebIdentity and exports temporary credentials.

Steps

• Create an IAM OIDC provider for token.actions.githubusercontent.com.
• Create a role whose trust policy restricts sub to your repo and branch.
• Add permissions: id-token: write to the job.
• Use configure-aws-credentials with role-to-assume and aws-region (no keys).

Workflow

permissions:
  id-token: write
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::111122223333:role/gha-deploy
          role-session-name: gha-${{ github.run_id }}
          aws-region: us-east-1
      - run: aws sts get-caller-identity

Gotchas

• The trust policy must set the audience condition sts.amazonaws.com and a sub like repo:org/name:ref:refs/heads/main.
• Without id-token: write the action fails with a missing OIDC token URL error.

Related guides