Bitbucket Pipelines for AWS using OpenID Connect (OIDC)

Overview

Storing permanent AWS Access Keys (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY) in your CI/CD variables introduces significant security risks. OpenID Connect (OIDC) solves this by establishing a direct trust relationship between Bitbucket and AWS.

To keep things clean, we will walk through creating a fresh Bitbucket repository to isolate and test this OIDC connection easily. Once this foundation is built, you can mirror the exact same pipeline configuration to securely handshake with AWS across any of your other repositories!

Prerequisites

• Bitbucket Account: Permissions to create a workspace and a repository.
• AWS Account: Administrative or IAM management access to create Identity Providers and Roles.

Step 1 — Initialize a Bitbucket Repository

1.1 - Create a new repository for testing the OIDC connection.
For this guide, I will use: phub-oidc-check

1.2 - Head over to OIDC information of your repository:
[https://bitbucket.org/[workspace-name]/phub-oidc-check/admin/pipelines/openid-connect]

1.3 - Secure the Identity provider URL and Audience

Step 2 — Configure the Identity Provider in AWS

2.1 - Navigate to the IAM Console > Identity Providers > Add Provider.

Step 3 — Create the IAM Role for Bitbucket

3.1 - In the IAM Console, go to Roles > Create Role.
3.2 - Select Custom Trust Policy and paste the following JSON setup:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowBitbucket",
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<AWS_ACCOUNT_ID>:oidc-provider/api.bitbucket.org/2.0/workspaces/<WORKSPACE_NAME>/pipelines-config/identity/oidc"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "api.bitbucket.org/2.0/workspaces/<WORKSPACE_NAME>/pipelines-config/identity/oidc:aud": "ari:cloud:bitbucket::workspace/<WORKSPACE_UUID>"
        }
      }
    }
  ]
}

3.3 - Attach AWS-managed policy is PowerUserAccess for a quick setup. For production, you can use below in-line policy to restrict to the least privilege required (recommended).
3.4 - Name the role (e.g., bitbucket-pipeline-oidc-role) and copy its ARN.

Step 4 — Enable OIDC in Bitbucket Pipelines

Enable Bitbucket to generate the OIDC token (Repository Variables config) and update your pipeline script.
[https://bitbucket.org/[workspace-name]/phub-oidc-check/admin/pipelines/repository-variables]

4.1 - In your Bitbucket Repository settings, go to Pipelines > Repository variables and add the AWS_OIDC_ROLE_ARN and AWS_DEFAULT_REGION.

🛠️ You need to enable pipelines first to be able to add repository variables.

4.2 - Add the bitbucket-pipelines.yml

image: amazon/aws-cli:latest

pipelines:
  custom:
    test-aws-oidc:
      - step:
          name: Test AWS OIDC Connection
          oidc: true # Very Important
          script:
            - yum install -y jq

            # Handshake with AWS IAM using OIDC token
            - |
              ASSUME_ROLE_JSON=$(aws sts assume-role-with-web-identity \
                --role-arn "$AWS_OIDC_ROLE_ARN" \
                --role-session-name "BitbucketTestSession" \
                --web-identity-token "$BITBUCKET_STEP_OIDC_TOKEN" \
                --output json)              

            # Activating session
            - |
              export AWS_ACCESS_KEY_ID=$(echo "$ASSUME_ROLE_JSON" | jq -r '.Credentials.AccessKeyId')
              export AWS_SECRET_ACCESS_KEY=$(echo "$ASSUME_ROLE_JSON" | jq -r '.Credentials.SecretAccessKey')
              export AWS_SESSION_TOKEN=$(echo "$ASSUME_ROLE_JSON" | jq -r '.Credentials.SessionToken')

            # Verify the activated role
            - aws sts get-caller-identity

4.3 - Commit, push and validate the pipeline.
Push the bitbucket-pipelines.yml to repository.

git add bitbucket-pipelines.yml
git commit -m "ci: Add pipeline configuration"
git push origin main

Head over to pipelines and trigger the custom pipeline manually.
[https://bitbucket.org/[workspace-name]/phub-oidc-check/pipelines]

Finally, check the aws sts get-caller-identity sub step you should see the familiar OIDC role ARN.

Conclusion

By switching to OpenID Connect (OIDC), you have successfully eliminated long-lived, high-risk AWS credentials from your Bitbucket environment. Your pipeline now handles deployments using secure, short-lived tokens that rotate automatically with every single run.

Safe deploying! 🚀

If you are interested in deploying pipelines like this, you may check out my companion guide: Automating Python Package Releases to AWS CodeArtifact via Bitbucket Pipelines. In that article, we build right on top of this setup to configure automated version bumping, tagging, and secure package distribution.

Salamat po 🇵🇭