OIDC from pipelines to AWS¶
Status: AI draft, 2026-11-16. Not yet verified by me. Written from the GitHub, Bitbucket and AWS documentation; nothing was run.
In one line¶
Instead of storing AWS access keys in CI, the CI provider issues each job a short-lived signed token (OIDC); AWS trusts that provider as an IAM identity provider, and the job exchanges the token with AssumeRoleWithWebIdentity for temporary credentials of a role whose trust policy checks the token's aud and sub, pinning which repository, branch or environment may use it.
The plain idea¶
A pipeline that deploys to AWS needs AWS credentials. The old way was an IAM user's access key stored as a CI secret: it never expires, works from anywhere, gets copied into other projects, and shows up in leaked logs. Rotating it is a chore nobody does.
OIDC federation removes the stored key. The CI system already knows exactly which repository, branch and job is running. It writes that down in a signed token. AWS has been told to trust tokens signed by that CI system, and a role's trust policy says which token contents are acceptable. The job swaps the token for credentials that expire within the hour. Nothing long-lived exists to leak (IAM roles and STS, Federation and SSO).
How it works¶
sequenceDiagram
participant J as CI job
participant P as CI provider
participant S as AWS STS
J->>P: request token<br/>for sts.amazonaws.com
P-->>J: signed JWT:<br/>iss, aud, sub
J->>S: AssumeRoleWithWebIdentity<br/>(role ARN, token)
S->>S: verify signature,<br/>check aud and sub
S-->>J: temporary<br/>credentials
One-time AWS setup¶
- Create an IAM OIDC identity provider for the CI system: for GitHub,
https://token.actions.githubusercontent.comwith audiencests.amazonaws.com; for Bitbucket, the workspace-specific URL and audience shown in the repository's OpenID Connect settings. - Create a role whose trust policy allows
sts:AssumeRoleWithWebIdentityfrom that provider, with conditions. - Attach a permissions policy with only what that pipeline needs (Least privilege and AccessDenied).
The trust policy is the security¶
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
"token.actions.githubusercontent.com:sub": "repo:sample-org/sample-app:environment:production"
}
}
}
audmust be the expected audience.subsays which workflows may assume the role. Without it, any repository on GitHub that can request a token for that audience could assume your role. AWS recommends always evaluating thesubcondition key.- GitHub
subformats includerepo:ORG/REPO:ref:refs/heads/BRANCH,repo:ORG/REPO:environment:NAMEand pull request forms. Pinning to an environment combines with GitHub's environment protection rules (approvals, allowed branches) (GitHub Actions in depth). StringLikewithrepo:sample-org/sample-app:*allows every branch and pull request of that repository: acceptable for a read-only plan role, not for a deploy role.
GitHub Actions side¶
permissions:
id-token: write # allow the job to request an OIDC token
contents: read
jobs:
deploy:
environment: production
runs-on: ubuntu-latest
steps:
- uses: aws-actions/configure-aws-credentials@<pinned-version>
with:
role-to-assume: arn:aws:iam::123456789012:role/sample-app-deploy
aws-region: ap-south-1
- run: aws sts get-caller-identity
The action requests the token, calls STS, and exports the temporary credentials for later steps.
Bitbucket Pipelines side¶
- Add
oidc: trueto the step; the token is in theBITBUCKET_STEP_OIDC_TOKENvariable. - Write it to a file and set
AWS_ROLE_ARNandAWS_WEB_IDENTITY_TOKEN_FILE; the AWS CLI and SDKs then assume the role themselves. - The
subclaim is made of UUIDs:{repository-uuid}:{environment-uuid}:{step-uuid}. Trust conditions pin the repository UUID, and for deploy roles the deployment environment UUID (Bitbucket Pipelines).
A concrete example¶
Two roles for sample-app's Terraform pipeline (Testing and CI for Terraform):
| Role | Trust sub |
Permissions |
|---|---|---|
sample-app-plan |
repo:sample-org/sample-app:* (any branch or pull request) |
Read-only, plus read and lock the state |
sample-app-deploy |
repo:sample-org/sample-app:environment:production |
What the apply needs, nothing more |
Pull requests can plan but never apply; only a job in the production environment, which requires approval and runs only from main, can deploy.
Why not just...?¶
- ...keep the access key, but rotate it regularly? It still exists in the CI system, works from anywhere until rotated, and rotation is the step teams skip. Temporary credentials expire on their own.
- ...trust the whole GitHub provider without a
subcondition? Then any workflow in any repository that can get a token with your audience can become your role. Always pinsub. - ...use one role for every pipeline? One compromised repository then has every permission any pipeline needs. One role per pipeline and purpose.
Commands to know¶
| Command | What it does |
|---|---|
aws iam list-open-id-connect-providers |
OIDC providers in the account. |
aws iam get-role --role-name sample-app-deploy --query Role.AssumeRolePolicyDocument |
The role's trust policy, to check aud and sub. |
aws sts get-caller-identity |
In the job: which role it is actually using. |
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventName,AttributeValue=AssumeRoleWithWebIdentity |
Who assumed roles through OIDC, with the token's subject (CloudTrail, Athena and Config). |
How it breaks¶
| Symptom | Layer | Check | Likely cause |
|---|---|---|---|
Not authorized to perform sts:AssumeRoleWithWebIdentity |
Trust policy | sub and aud conditions against the token |
Branch, environment or repository does not match; typo in the condition key |
Credentials could not be loaded or no token requested |
Workflow permissions | permissions: block |
Missing id-token: write |
No OpenIDConnect provider found |
IAM provider | list-open-id-connect-providers |
Provider missing in this account, or wrong URL |
Incorrect token audience |
Audience | Provider audiences, the action's audience | Provider registered with another audience |
Works on main, fails on a tag release |
sub format |
Tag sub is ref:refs/tags/... |
Trust policy only allows the branch form |
Deploy succeeds but AccessDenied on a call |
Permissions | Role's permissions policy | Role can be assumed but lacks the action |
Interview questions¶
1. Why use OIDC instead of access keys in CI?
Answer
- No long-lived secret stored in the CI system, so nothing to leak or rotate.
- Credentials are temporary and tied to a specific repository, branch or environment.
- CloudTrail shows which workflow assumed the role.
2. Walk through the OIDC flow from a GitHub Actions job to AWS.
Answer
- The job (with
id-token: write) requests a signed JWT from GitHub's provider. - It calls
AssumeRoleWithWebIdentitywith the token and role ARN. - STS verifies the signature against the registered provider, checks the trust policy's
audandsub, and returns temporary credentials.
3. Why must the trust policy pin sub?
Answer
subidentifies the repository and branch or environment.- Without it, any repository's workflow that can get a token for the audience could assume the role.
- Pin deploy roles to an environment or protected branch.
4. A job fails with "Not authorized to perform sts:AssumeRoleWithWebIdentity". Debug it.
Answer
- Compare the token's
sub(branch, tag, environment, pull request form) with the trust policy conditions. - Check
aud, the provider ARN in the principal, and that the provider exists in that account. - Check the workflow requested a token (
id-token: write).
5. How does Bitbucket's OIDC differ from GitHub's?
Answer
- The provider URL and audience are per workspace;
subis built from repository, environment and step UUIDs. - The step needs
oidc: true; the token comes inBITBUCKET_STEP_OIDC_TOKEN, written to a file for the SDK. - The trust policy pins repository UUID and, for deploys, environment UUID.
6. How would you design roles for plan and deploy?
Answer
- A read-only plan role trusted by all branches and pull requests of the repository.
- A deploy role trusted only by the production environment's jobs, with approval required.
- Separate roles per account and per pipeline.
Try it¶
Without AWS:
- Write the trust policy for a role that only release tags
v*ofsample-org/sample-appmay assume. (Hint: the tagsubform isrepo:ORG/REPO:ref:refs/tags/TAG, so useStringLikewithrefs/tags/v*.) - Decode a JWT you have (for example a kind service account token, as on RBAC and service accounts) and identify
iss,audandsub. - List every place in your current pipelines where a long-lived cloud key is stored.
Zoom out¶
OIDC from CI is the same pattern as IRSA and Pod Identity on EKS and as SSO for people: short-lived credentials from a trusted identity provider, narrowed by conditions (Cluster access, IRSA and Pod Identity, OAuth 2.0, OIDC and JWTs). It is the single biggest improvement to most pipelines' security (Pipeline security).