Bitbucket Pipelines OIDC support in Google cloud pipes

[#1]

Overview

Bitbucket Pipelines could automatically request an OIDC token for a running step. User can send the OIDC token to Google’s Security Token Service (STS) to exchange it for a short‐lived Google access token. With this token, a pipeline can call GCP APIs (or use gcloud) without storing long‐lived credentials.

The high-level steps are:

1. Create a Workload Identity Pool and OIDC provider in GCP.

2. Create (and configure) a GCP service account and grant it permission to be impersonated.

3. Create an external credentials file that tells GCP how to exchange an OIDC token.

4. Configure a Bitbucket pipeline to request the OIDC token and use it to call GCP.

Prerequisites

All needed values to create a workload identity pool in GCP you could find in Bitbucket Cloud under "Repository Settings" / "OpenID Connect":

Step 1: In GCP: Create a Workload Identity Pool and OIDC Provider

      1. Open the GCP Console and navigate to IAM & Admin > Workload Identity Federation.

      2. Create a new Workload Identity Pool:

• Click “Create Pool”.
• Give the pool a descriptive name (e.g. bitbucket-pool) and an ID.
• Choose an appropriate location (typically leave as global).
• Configure any advanced settings as needed.
• Click “Create”.

Add an OIDC provider to the pool:

• In your new pool’s details, click “Add Provider”.
• Provider type: Choose “OIDC”.
• Provider name/ID: For example, bitbucket-provider.
• Issuer URL: Set this to Bitbucket’s OIDC issuer URL.

Allowed audiences: You can leave this empty or (if required) specify allowed audiences.

Attribute mapping: Map the claims you expect. For example, you might want to map the sub claim (which in Bitbucket Pipelines encodes the repository identity) to an attribute that you can later use in an IAM condition:

attribute.repository = "assertion.sub"

(If you want to restrict access to a specific repository, note what the sub value is in your pipeline run and use that value in a later IAM binding.)

Click “Create”.

> Tip: Later you will use the fully qualified resource name for your provider. It will look similar to:

//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/bitbucket-pool/providers/bitbucket-provider

Step 2: In GCP: Create a Service Account and Grant It Permission to Be Impersonated

3. Create a service account that your pipeline will impersonate. For example, in the Cloud Console go to IAM & Admin > Service Accounts and click “Create Service Account”. Name it something like bitbucket-runner.

4. Grant the service account any roles your pipeline requires (for example, roles/Storage Admin or Storage Object Admin, if your pipeline needs to work with Cloud Storage).

5. Allow the federated identity to impersonate the service account. In a terminal (or using Cloud Shell), run a command like:

gcloud iam service-accounts add-iam-policy-binding \
  bitbucket-runner@YOUR_PROJECT.iam.gserviceaccount.com \
  --role=roles/iam.workloadIdentityUser \
  --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/bitbucket-pool/attribute.repository/REPOSITORY_ID"

Replace the placeholders as follows:

• YOUR_PROJECT with your GCP project ID.
• PROJECT_NUMBER with your GCP project number.
• REPOSITORY_ID with the value from the OIDC token’s sub claim. (For example, if your repository is identified as workspace/repo-slug, use that exact string.)

Important: By binding based on the attribute (here, attribute.repository), you restrict which Bitbucket repositories may assume this service account.

Step 3: Create an External Account Credentials File for GCP

GCP’s Workload Identity Federation works with External Account Credentials. Create a JSON file (with name workload-identity-federation.json) that tells Google how to exchange your Bitbucket OIDC token.

Grant access to the service account

After the service account is created, go to the identity pool and grant it access to the created service account.

Download the file for usage in the next step as content for GOOGLE_OIDC_CONFIG_FILE variable.

Below is a sample file:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/bitbucket-pool/providers/bitbucket-provider",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "file": "./oidc_token.txt"
  },
  "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/bitbucket-runner@YOUR_PROJECT.iam.gserviceaccount.com:generateAccessToken"
}

Step 4: In Bitbucket: Configure Your Pipeline

Now configure your Bitbucket Pipeline to request an OIDC token and use it to obtain GCP credentials.

1. Enable OIDC in your pipeline step. In your bitbucket-pipelines.yml file, include the oidc: true key in the step that needs to call GCP:

pipelines:
  default:
    - step:
        oidc: True
        name: Test
        script:
          - echo "Hello"
          - pipe: atlassian/google-cloud-storage-deploy:2.2.0
            variables:
              GOOGLE_OIDC_CONFIG_FILE: $GOOGLE_OIDC_CONFIG_FILE
              PROJECT: $PROJECT
              BUCKET: $BUCKET
              SOURCE: './bitbucket-pipelines.yml'

Bitbucket Pipelines automatically injects the OIDC token into the environment variable BITBUCKET_STEP_OIDC_TOKEN.

The pipe's script writes the token to a file (oidc_token.txt) so that the credential file (created in Step 4) can find it.

Troubleshooting and Additional Resources

IAM Binding: Ensure that the value of the attribute (e.g. sub from the token) exactly matches what you put in the IAM policy binding’s member string.

Documentation:

Google Cloud Workload Identity Federation documentation

Bitbucket Pipelines OIDC documentation

Summary

By following these steps, your Bitbucket Pipeline will:

1. Request an OIDC token when running a step.

2. Write the token to a file.

3. Use an external account credentials file to have Google’s STS exchange that token for an access token.

4. Impersonate a GCP service account (with only the permissions you’ve granted) so that your pipeline can safely call GCP APIs.

This setup avoids storing long‐lived service account keys in a repository and leverages modern, short‐lived credentials via OIDC and Workload Identity Federation.