How to Authenticate CircleCI to AWS with OIDC

CircleCI issues an OIDC token (CIRCLE_OIDC_TOKEN) you exchange for short-lived AWS credentials - no static keys.

When a job runs in a context, CircleCI sets $CIRCLE_OIDC_TOKEN. Pass it to aws sts assume-role-with-web-identity to get temporary credentials.

Assume a role with the OIDC token

The job runs in a context (which enables the token), then exchanges it for AWS credentials.

jobs:
  deploy:
    docker:
      - image: cimg/aws:2024.03
    steps:
      - run: |
          CREDS=$(aws sts assume-role-with-web-identity \\
            --role-arn "$AWS_ROLE_ARN" \\
            --role-session-name "circleci-$CIRCLE_WORKFLOW_ID" \\
            --web-identity-token "$CIRCLE_OIDC_TOKEN" \\
            --query Credentials --output json)
          export AWS_ACCESS_KEY_ID=$(echo "$CREDS" | jq -r .AccessKeyId)
          export AWS_SECRET_ACCESS_KEY=$(echo "$CREDS" | jq -r .SecretAccessKey)
          export AWS_SESSION_TOKEN=$(echo "$CREDS" | jq -r .SessionToken)
          aws s3 ls

Gotchas

• $CIRCLE_OIDC_TOKEN is only set when the job runs inside a context - attach one in the workflow.
• The IAM trust policy sub must match org/<org-id>/project/<project-id>/...; copy the exact value from CircleCI org settings.
• The token audience is your CircleCI organization ID - set it as the aud condition in the trust policy.

Related guides