DEV Community

Cover image for Bitbucket Pipelines for AWS using OpenID Connect (OIDC)
Mel Cadano
Mel Cadano

Posted on

Bitbucket Pipelines for AWS using OpenID Connect (OIDC)

#bitbucket #aws #oidc #cicd

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

OpenID Connect

Step 2 — Configure the Identity Provider in AWS

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

Add Identity 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>"
        }
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

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.

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Run custom pipeline

Running pipeline

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

AWS STS

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 🇵🇭

Top comments (0)