In Bitbucket Pipelines, how does a deployment step get short-lived cloud credentials through OIDC, and how do you stop other steps assuming the same role?
answer
- a signed token per step
- exchanged, never stored
- issuer and audience per workspace
- sub carries repository and environment
- the YAML is editable by writers
basics
~20 sSet oidc: true on the Bitbucket Pipelines step; it receives a signed ID token in BITBUCKET_STEP_OIDC_TOKEN to exchange with the cloud for temporary credentials. Scope the cloud role's trust to the repository and Production environment UUIDs in the token's sub claim.
solid answer
~40 sBitbucket Pipelines runs an OpenID Connect identity provider per workspace. A step with `oidc: true` gets a signed ID token in `BITBUCKET_STEP_OIDC_TOKEN`, and its script presents that token to the cloud provider's token exchange for temporary credentials on a role, so no long-lived key is stored as a secured variable. The cloud side is configured with the **Identity provider URL** and **Audience** shown on the repository's OpenID Connect settings page. Scoping comes from the claims: `sub` is `{REPOSITORY_UUID}[:{ENVIRONMENT_UUID}]:{STEP_UUID}`, and the environment part appears only when the step has a `deployment` environment. Trusting `{repo}*:{production-env}:*` rather than just the repository limits the role to Production deployment steps. Because anyone with write access can add `deployment: production` to a step on their branch, pair it with Premium deployment permissions and branch restrictions on that environment.
code
yaml · 12 linespipelines:
branches:
main:
- step:
name: Deploy to production
deployment: production
trigger: manual
oidc: true
max-time: 15
script:
- ./fetch-deploy-credentials.sh "$BITBUCKET_STEP_OIDC_TOKEN"
- ./deploy.sh productiongo deeper
Recall that oidc: true gives a step a token in BITBUCKET_STEP_OIDC_TOKEN that the cloud swaps for temporary credentials.
Explain where the identity provider URL and audience come from and what the token's claims hold, including when sub carries an environment.
Show that you pin trust to repository and environment in sub, and close the YAML-edit route with deployment permissions and branch restrictions.
Weigh migrating every stored cloud key to federation against the credentials that cannot move, and how environment controls differ by plan.
## What OIDC replaces The traditional way to let a Bitbucket Pipelines deployment reach a cloud account is a long-lived access key stored as a **secured variable**. Secured variables are encrypted, cannot be edited (only replaced or deleted), and their values are masked in build logs, but the key itself lives indefinitely, and any script in any step that receives it can copy it somewhere masking does not reach. With **OpenID Connect**, nothing long-lived is stored. Each step that asks for it gets a short-lived, signed identity token; the cloud verifies the signature and the claims and hands back temporary credentials for one role. ## How the exchange works 1. **Configure the cloud side once.** In the repository's settings, the *OpenID Connect* page under Pipelines shows the **Identity provider URL** and the **Audience**. The issuer has the form `https://api.bitbucket.org/2.0/workspaces/<workspace>/pipelines-config/identity/oidc`, and the default audience identifies the workspace (`ari:cloud:bitbucket::workspace/<workspace UUID>`). You register that provider with the cloud and create a role whose trust policy accepts its tokens. 2. **Enable it on the step.** `oidc: true` on a step makes Pipelines mint a token for that step and expose it as `BITBUCKET_STEP_OIDC_TOKEN`. 3. **Exchange it in the script.** The script passes the token to the cloud's web-identity token exchange along with the role to assume and receives temporary credentials. ## The claims you can scope on The token carries, among others: | Claim | Holds | |---|---| | `iss` | the workspace's identity provider URL | | `aud` | the audience, by default the workspace | | `sub` | `{REPOSITORY_UUID}[:{ENVIRONMENT_UUID}]:{STEP_UUID}` | | `repositoryUuid`, `workspaceUuid` | the repository and workspace | | `deploymentEnvironment` | the environment name, when there is one | | `branchName` | the branch the pipeline runs for | | `pipelineUuid`, `stepUuid` | this run and this step | The key detail is in `sub`: the **environment UUID appears only when the step is assigned to a deployment environment**. Because some clouds only let a trust policy test a few standard claims, Bitbucket packs repository and environment into `sub` so that a pattern can match them: - `{REPO_UUID}:*` lets **any** OIDC step in the repository assume the role, on any branch, deploying or not; - `{REPO_UUID}*:{PRODUCTION_ENV_UUID}:*` lets only steps with `deployment: production` in that repository assume it. The trailing wildcard is needed because the step UUID changes on every run. The documentation lists further access policies: restricting requests to Pipelines' published IP ranges, and restricting step duration with a short `max-time` on the steps that use OIDC. ## Why the environment pin is not the whole answer The environment claim says which environment a step *declared*, not that anyone approved it. `bitbucket-pipelines.yml` is a file in the repository; a user with write access can push a branch whose YAML adds `deployment: production` to a step and get a token carrying the Production environment UUID. What closes that route sits on the environment, not in the trust policy: - **Deployment permissions** (Premium) limit who can run Production deployment steps, and also halt scheduled or automated deployments until an approved user resumes them. - **Branch restrictions on the environment** (Premium) limit which branches can deploy to Production at all. - Where the cloud's trust conditions can read it, the `branchName` claim is a further pin. On plans without those controls, the realistic boundary is who holds write access and who can change the YAML on the branches that deploy. ## Secured variable or OIDC | | Secured variable holding a cloud key | OIDC token | |---|---|---| | Lifetime | until someone rotates it | one step, then temporary credentials | | Stored in Bitbucket | yes, encrypted | nothing stored | | Scope | every step that receives the variable | what the trust policy's claim patterns allow | | Leak impact | usable anywhere until revoked | short-lived credentials for one role | Credentials that a cloud cannot federate, such as a third-party service's API token, still belong in secured variables, ideally as deployment variables of the one environment that needs them. ## Rolling it out 1. Register the workspace's identity provider URL and audience with the cloud account once. 2. Create one role per environment, each trusting a `sub` pattern with that environment's UUID, and grant each only what that environment's deploy needs. 3. Add `oidc: true` only to the steps that deploy, and switch their scripts from the stored key to the token exchange. 4. Watch a few deployments succeed, then delete the old secured variables and revoke the keys they held. 5. On Premium, add deployment permissions and branch restrictions to Production so the environment claim means what the trust policy assumes.
- Why is pinning the role to the Production environment UUID not enough on its own?The environment claim only reflects what the step declared. Anyone with write access can push a branch whose `bitbucket-pipelines.yml` adds `deployment: production` to a step and receive a matching token. On Premium, deployment permissions and branch restrictions on the Production environment close that route; otherwise the boundary is who can write to the repository.
- Which credentials stay as secured variables after moving to OIDC?Anything the target cannot federate with Bitbucket's identity provider, such as a third-party service's static API token or a signing key. Keep those as secured deployment variables on the one environment that needs them, so only that environment's deployment steps receive them, and rotate them on a schedule.
- OIDC still needs the cloud access key stored as a secured variable.
- The token's sub claim always contains an environment UUID.
- Trusting the repository UUID alone limits the role to production deploys.
- A production environment claim proves someone approved the deployment.
- Masked secured variables cannot leak, so OIDC adds nothing.