Bitbucket Pipelines Openid Connect AWS Identity Format
The bitbucket pipelines openid connect aws identity format uses a unique token string to verify your build jobs in AWS. This string joins your repo ID, deployment target ID, and step ID so AWS knows which build is calling. Teams use this setup to remove static cloud keys from their source control settings. Still, teams often set up wildcards in their trust rules to get builds working fast. Broad trust rules let any branch or repo assume powerful cloud roles during a build run. How the bitbucke
Bitbucket Pipelines Security + AWS IAM Policies: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
The bitbucket pipelines openid connect aws identity format uses a unique token string to verify your build jobs in AWS. This string joins your repo ID, deployment target ID, and step ID so AWS knows which build is calling. Teams use this setup to remove static cloud keys from their source control settings. Still, teams often set up wildcards in their trust rules to get builds working fast. Broad trust rules let any branch or repo assume powerful cloud roles during a build run.
How the bitbucket pipelines openid connect aws identity format works
When a build job starts, Bitbucket creates a signed token for that single step. This token includes an issuer URL, an audience value, and a subject claim. The subject claim follows the bitbucket pipelines openid connect aws identity format to identify the exact source of the job.
Inside the subject string, Bitbucket places unique IDs for your repo and your step. If the build step targets a specific deployment tier, the string also includes that target ID. Your build job sends this signed token to the AWS token service.
AWS checks the token signature against the public keys from your Bitbucket workspace. Next, AWS reads the subject claim and compares it to the trust rule on the IAM role. If the strings match, AWS sends back temporary session keys for that build step.
Teams must copy the exact workspace URL and audience string from their repo settings into AWS. A single typo in the subject string blocks the build from getting temporary keys. Because these IDs use long random strings, teams must check them with great care.
Where native cloud role trust rules fall short
Federated identity tokens solve a major problem by removing long-lived keys from build settings. You no longer need to rotate static secrets or worry about leaked repo variables. The cloud provider checks the identity of the build runner before it grants any role.
Yet this check only happens at the start of the session when the build logs in. Once AWS grants the temporary role, the build script can run any command allowed by that role. IAM trust rules cannot inspect individual database queries or shell commands while they run in flight.
Bitbucket Pipelines Security + AWS IAM Policies: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
To deploy code or run database migrations, a build role often needs broad write rights. If a bad script or dependency enters the repo, it inherits those same broad rights. Native role checks also do not mask sensitive data like emails or card numbers in build logs.
Scoping trust rules for safer build jobs
To reduce risk, teams should avoid wildcards in the subject match condition on AWS. Bind each production role to the exact repo ID and deployment tier ID. This stops a test branch in another repo from assuming a production role.
You should also split build roles by task instead of sharing one admin role. Use one small role to push container images and a separate role to update app servers. Keep session durations short so temporary keys expire right after the build step finishes.
Even with tight role scoping, teams still need visibility into what build scripts do after login. Checking every query and command during the run closes the gap left by login-only role checks.
Govern statements and responses across databases and APIs
Good config and scoped roles are needed setup. They do not check single queries in flight or mask sensitive fields in returned rows. Across Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, and internal HTTP endpoints, hoop.dev runs beside each supported service as an open-source proxy, a sidecar for your database or API.
First, hoop.dev guardrails block banned queries before they run. Then hoop.dev data masking rewrites matched sensitive values in responses in memory. The audit trail records every statement and verdict per resource. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.
Frequently asked questions
What values make up the Bitbucket OIDC subject claim for AWS?
The subject claim combines the unique repo ID, the optional deployment target ID, and the step ID. AWS reads this combined string to check if the build step matches your IAM role trust rule.
Why does my Bitbucket build fail to assume the AWS role?
Role failures usually happen when the subject string or audience value in AWS does not match your repo IDs. Check that your build step enables OIDC token creation and that the trust rule matches the exact format.
Can I restrict an AWS role to a single deployment stage in Bitbucket?
Yes, you can include the unique deployment tier ID in the subject condition of your AWS trust rule. This ensures only build steps assigned to that specific stage can assume the cloud role.