Integrate Pipelines with resource servers using OIDC

You can use Bitbucket Pipelines OpenID Connect Provider (OIDC IDP) to allow your pipelines to access your resource server, such as AWS, GCP, or Vault. This means that you and your team can access the resource server without storing credentials in Bitbucket.

OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. It allows clients to:

Verify the identity of the end user based on the authentication performed by Bitbucket Pipelines.
Obtain basic profile information about the end-user in an interoperable and REST-like manner.

Getting started

To enable OIDC, you must configure Pipelines as an external OpenID Connect provider for the resource server. The following section helps you configure OpenID Connect in Bitbucket Pipelines, and then provides links to further information about the setup within the various resource servers.

You must be using Pipelines in your repository to integrate OpenID Connect.

Enable OIDC for Pipelines builds

In order to use OpenID Connect with Pipelines and your resource server, you need to set oidc to ‘true’ in the Bitbucket Pipelines YAML file.

Edit bitbucket-pipelines.yml so ‘oidc’ equals ‘true’

image: amazon/aws-cli

pipelines:
  default:
    - step:
        oidc: true
        max-time: 5
        script:
          - aws sts assume-role-with-web-identity --role-arn arn:aws:iam::XXXXXX:role/projectx-build --role-session-name build-session  --web-identity-token "$BITBUCKET_STEP_OIDC_TOKEN" --duration-seconds 1000

Retrieve unique identifiers and claims

In order to configure Bitbucket Pipelines as an external OIDC IDP, you will need to retrieve the workspace, repository, and deployment environment UUID.

Select Repository settings on the left navigation sidebar of the repository you want to associate with an ODIC provider.
Select OpenID Connect under Pipelines on the left sidebar.
Copy the Identity provider URL and Audience. Keep those somewhere accessible as you will need them to complete the steps necessary to configure Pipelines as a External OpenID Connect Provider (OIDC IDP) and set up the build to assume the created role prior to running your build in your cloud environment.

Example payload

The example payload that is displayed under the Unique identifiers heading provides you with the various claims you need to configure OpenID Connect or to set access policies on the resource server side.

The claims in the provided example that are displayed with ‘xxxxx’ as the value are unique to your pipeline and the environment you are currently using.

Example payload displaying claims for OIDC

UUIDs - The UUIDs are displayed under the ‘Example payload’ for ease of use, since you will need to copy/paste these when configuring the resource server side for OIDC.

Deployment environments - These are the deployment environments you have associated with this build in Bitbucket Cloud. Select the dropdown to display and choose the environment in which you want to integrate OIDC.

Setting access policies

Once you have integrated OpenID Connect with Bitbucket Pipelines, you can set various access policies on the resource server side. Below is a list of the access policies which are mostly configured on the resource server side, such as AWS, GCP, or Vault.

Restricting access per repository
Restricting access per environment
Restricting access to only Bitbucket Pipelines IP ranges
Restricting step duration - This access policy is agnostic of any particular resource server. See the steps below.

Restricting step duration

Bitbucket Pipelines allows you to configure the maximum duration of a step explicitly. You may want to set the duration time to ensure you are not using unnecessary build minutes or to pinpoint the time needed to complete your builds successfully.

In this step, you are going to edit your bitbucket-pipelines.yml to configure step maximum duration time by updating the ‘max-time’ value that works best for your builds and workflow. The example below reconfigures the step maximum duration time to 5 minutes.

image: amazon/aws-cli

pipelines:
  default:
    - step:
        oidc: true
        max-time: 5
        script:
          - aws sts assume-role-with-web-identity --role-arn arn:aws:iam::XXXXXX:role/projectx-build --role-session-name build-session  --web-identity-token "$BITBUCKET_STEP_OIDC_TOKEN" --duration-seconds 1000

By default, the system adds extra 5 minutes as buffer in case of any delays when starting the step.

For more information about configuring bitbucket-pipelines.yml, check out our Configure bitbucket-pipelines.yml support doc.

Resource server-specific help

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community