How to Authenticate Bitbucket Pipelines to AWS with OIDC

Bitbucket Pipelines issues an OIDC token per step (when you opt in) that you exchange for short-lived AWS credentials.

Set oidc: true on the step to get $BITBUCKET_STEP_OIDC_TOKEN, then call aws sts assume-role-with-web-identity to assume a role - no stored AWS keys.

Assume a role with the step OIDC token

Enabling oidc: true sets the token; pass it to STS to get temporary credentials.

pipelines:
  default:
    - step:
        name: Deploy
        oidc: true
        image: amazon/aws-cli:2
        script:
          - echo "$BITBUCKET_STEP_OIDC_TOKEN" > /tmp/web-identity-token
          - >
            aws sts assume-role-with-web-identity
            --role-arn "$AWS_ROLE_ARN"
            --role-session-name "bb-$BITBUCKET_BUILD_NUMBER"
            --web-identity-token "file:///tmp/web-identity-token"
          - aws s3 ls

Gotchas

• Without oidc: true on the step, $BITBUCKET_STEP_OIDC_TOKEN is not set.
• The IAM identity provider audience is your workspace OIDC aud (from Repository settings > OpenID Connect); the sub is the repository UUID.
• The token is per-step - set oidc: true on every step that needs AWS.

Related guides