How to federate Bitbucket Pipelines to AWS: Swap stored AWS keys for OIDC role credentials

Bitbucket Pipelines repositories commonly hold AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as secured repository or workspace variables, which are long-lived keys available to every step that can read them. Bitbucket Cloud can instead issue an OpenID Connect token to each step, which AWS STS exchanges for temporary credentials for a role whose trust policy names the workspace, the repository and, ideally, the deployment environment. This page is the runbook: collect the identifiers, create the provider and role, update bitbucket-pipelines.yml, test, roll back and delete the keys. It is for DevOps and platform engineers who administer Bitbucket workspaces and AWS accounts. For the wider platform hardening picture see the Bitbucket Security Guide; this page focuses on the migration.

This is an independent guide from NHI Mgmt Group, based on Atlassian's and AWS's public documentation as checked in November 2026. It is not sponsored or reviewed by Atlassian or AWS. Confirm settings against the current vendor documentation before changing production.

Key takeaways

• Without a sub condition, the whole workspace is trusted. Atlassian states that by default any repository in the workspace can assume the role, and so can anyone holding a token. The issuer and audience are per workspace, so they do not narrow anything inside it.
• The subject is built from UUIDs, not names. It takes the form {REPOSITORY_UUID}[:{ENVIRONMENT_UUID}]:{STEP_UUID}. Renaming a repository does not break or transfer the trust, which is safer than name-based subjects.
• Bind production roles to a deployment environment. The environment UUID only appears in the subject when the step is a deployment step, so a trust policy that requires it cannot be met by an ordinary branch or pull request build.
• The token is a file you write yourself. The step exposes BITBUCKET_STEP_OIDC_TOKEN; you write it to the path in AWS_WEB_IDENTITY_TOKEN_FILE and set AWS_ROLE_ARN. Never echo it into logs or save it as an artifact.
• Finish by deleting keys. The migration is done only when the IAM user's keys are deleted and the secured variables removed at repository, deployment and workspace level.

When you need this

• AWS keys sit in secured variables. Workspace-level variables are the widest exposure: every repository in the workspace receives them. Secured variables are masked in logs, but any step can still use or exfiltrate them. A researcher's demonstration of a Bitbucket pipeline leading to server takeover shows how pipeline configuration and secrets become an attack path.
• One IAM user serves many repositories. CloudTrail cannot tell which repository made a call. Federated sessions record the repository and step UUIDs.
• You are already reviewing Atlassian credentials. If you are moving off app passwords, do this at the same time. See Atlassian App Passwords to API Tokens.

Before you start

Bitbucket shows UUIDs wrapped in curly braces. Copy the identifiers exactly as the OpenID Connect settings page shows them, including the braces, and confirm the final subject from a real token or CloudTrail event before tightening the policy.

Choosing the subject condition

Atlassian's own example for deployment steps uses {REPO_UUID}*:{ENVIRONMENT_UUID}:*. The step UUID changes every run, so a wildcard on the final segment is unavoidable; that is why the environment segment, not the step, carries the production boundary.

Step-by-step

1. Inventory first (read-only). List repositories, deployment environments and the workspace with AWS variables, and record which IAM user each key belongs to. In AWS, check for an existing provider with aws iam list-open-id-connect-providers; there is one provider per URL per account, and one Bitbucket provider covers the whole workspace.
2. Create the OIDC identity provider.

   aws iam create-open-id-connect-provider \
     --url https://api.bitbucket.org/2.0/workspaces/<WORKSPACE>/pipelines-config/identity/oidc \
     --client-id-list ari:cloud:bitbucket::workspace/<WORKSPACE_UUID>

   AWS verifies the issuer certificate against its trusted root CA library and uses a thumbprint only as a fallback. Atlassian's AWS page publishes a thumbprint for manual setups; you do not normally need to supply one.
3. Write the trust policy for a production environment. Save as trust.json:

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

   The condition key prefix is the provider URL without https://, path included. AWS maps generic OIDC providers to aud, sub, amr, email and oaud only, so repository and environment scoping must live in sub.
4. Create the role and attach permissions.

   aws iam create-role --role-name bbp-payments-api-prod-deploy \
     --assume-role-policy-document file://trust.json --max-session-duration 3600
   aws iam put-role-policy --role-name bbp-payments-api-prod-deploy \
     --policy-name deploy --policy-document file://deploy-permissions.json

   Build the permissions from what the pipeline actually calls. See the AWS IAM Policies and Roles Guide.
5. Restrict the deployment environment in Bitbucket. Limit which branches can deploy to the environment and, where your plan allows it, which users can run deployments. Bitbucket only releases an environment's variables to a step when the branch and admin permission checks pass, and manual steps can only be triggered by users with write access.
6. Update bitbucket-pipelines.yml.

   pipelines:
     branches:
       main:
         - step:
             name: Deploy to production
             deployment: production
             oidc: true
             image: amazon/aws-cli
             script:
               - export AWS_REGION=eu-west-2
               - export AWS_ROLE_ARN=arn:aws:iam::<ACCOUNT_ID>:role/bbp-payments-api-prod-deploy
               - export AWS_WEB_IDENTITY_TOKEN_FILE=$(pwd)/web-identity-token
               - echo $BITBUCKET_STEP_OIDC_TOKEN > $(pwd)/web-identity-token
               - aws sts get-caller-identity

   The AWS CLI and SDKs read AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE and call AssumeRoleWithWebIdentity themselves. Atlassian's documentation is inconsistent about whether OIDC is on by default, so set oidc: true on steps that need it and oidc: false on steps that do not, such as pull request builds.
7. Pilot on staging. Create a staging role bound to the staging environment UUID and run it first. Keep the old variables in place but unused by the federated step until both environments deploy cleanly.

Verify it worked

• Step output: aws sts get-caller-identity returns an assumed-role ARN for the new role, not an IAM user.
• CloudTrail: find AssumeRoleWithWebIdentity with userIdentity.type WebIdentityUser. responseElements.subjectFromWebIdentityToken shows the repository, environment and step UUIDs, and responseElements.audience the workspace audience. Global STS endpoint calls are logged in us-east-1.
• Negative tests: run the same step from a feature branch without deployment: production, and from another repository in the workspace. Both must be denied.
• Token hygiene: confirm the token file is not listed under artifacts and that no script prints it.

Rollback and common errors

Rollback: during the pilot, revert the YAML change to restore key-based login; nothing in AWS needs undoing. After cut-over, deactivate the old keys (aws iam update-access-key --status Inactive), wait a full release cycle, then delete the keys and the secured variables at every level. See How to rotate an AWS IAM access key without downtime. To withdraw access, edit or delete the role's trust policy; sessions already issued last until they expire.

Decisions: environments, runners and IP conditions

Small organisations with a handful of repositories can manage roles by hand. Larger ones should create provider and roles from a dedicated infrastructure pipeline whose own role is not trusted by ordinary repositories, so a compromised repository cannot rewrite the trust that governs it. The same pattern for other platforms is in How to set up workload identity federation for GitLab CI to Azure.

Hardening and monitoring afterwards

• Disable OIDC where unused: set oidc: false on pull request and fork-triggered steps.
• Protect the environments: branch restrictions on production deployment environments are part of the trust boundary.
• Alert on drift: UpdateAssumeRolePolicy on bbp-* roles, CreateOpenIDConnectProvider outside change windows, and AssumeRoleWithWebIdentity whose subject contains a repository UUID not on your list.
• Remove workspace-level AWS variables: they are inherited by every repository.

Migrating a whole workspace

1. Rank repositories by exposure. Start with repositories whose keys reach production or hold IAM write rights, then shared workspace-level keys, then the long tail of read-only keys.
2. Create the provider once per account. Because the issuer and audience are per workspace, one provider in each AWS account serves every repository; only roles are per repository and environment.
3. Template the roles. Generate trust policies from a list of repository and environment UUIDs held in code, so every new repository gets a reviewed role rather than a copied key.
4. Track the old IAM users. For each user, record the repositories that used it and its key last-used date. A user is ready for deletion only when every consumer has moved and the key has shown no use for a full release cycle.
5. Close the door. Once migration is complete, use an SCP or a detective control to flag any new IAM user access key created for CI, so the old pattern does not creep back. See How to find unused AWS IAM roles and access keys.

Framework mapping

Practitioner checklist

• List every repository, deployment and workspace variable that holds AWS keys.
• Create one Bitbucket OIDC provider per workspace in each target AWS account.
• Pin aud with StringEquals and always include a sub condition.
• Bind production roles to repository UUID plus deployment environment UUID.
• Restrict which branches can deploy to production environments.
• Set oidc: true only on steps that need AWS access.
• Run positive and negative tests and check the subject in CloudTrail.
• Deactivate, then delete, old keys and secured variables at every level.

Standards and references

• Atlassian: Deploy on AWS using Bitbucket Pipelines OpenID Connect
• Atlassian: Integrate Pipelines with resource servers using OIDC
• Atlassian: Step options
• Atlassian: Variables and secrets
• AWS: Create an OpenID Connect identity provider in IAM
• AWS: IAM and AWS STS condition context keys
• AWS: Logging IAM and AWS STS API calls with AWS CloudTrail
• OWASP: Non-Human Identities Top 10

Related NHI Mgmt Group resources: CI/CD Pipeline Identity Security Guide · How to set up workload identity federation for GitHub Actions to AWS · How to federate Terraform Cloud to AWS · How to Audit CI/CD Secrets Scope · Multi-Cloud Workload Identity Troubleshooting Guide