What is GitHub Actions OIDC for AWS, and why replace static access keys?
OIDC federation lets a GitHub Actions job prove its identity to AWS without holding any AWS secret. When a job runs with permission to request an ID token, GitHub's OIDC provider issues a short-lived signed JSON Web Token. The token's claims describe the job: the repository, the branch or tag, the environment, and the triggering event. AWS IAM checks that token against a trust policy and, if it matches, STS returns temporary credentials for a specific role. Nothing long-lived is stored in the repository.
This applies to backend and platform engineers who deploy from GitHub Actions to AWS. Those teams most often have an AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY sitting in repository or organization secrets.
Static keys are a standing liability for four reasons:
- They stay valid until someone revokes them. A key copied once remains usable for months.
- They can leak. A debug step can echo them into logs, or a malicious pull request can modify a workflow to send them somewhere.
- They are hard to rotate. Rotating means updating every repository that holds a copy.
- They are not tied to the workflow. CloudTrail shows the IAM user, not which repository, branch or run made the call.
| Property | Static access keys | OIDC federation |
|---|---|---|
| Credential lifetime | Until revoked | Minutes to hours |
| Stored in GitHub | Yes | No |
| Rotation | Manual, per repo | Not needed |
| Bound to repo/branch | No | Yes, via trust policy |
OIDC improves security only when the trust policy is tightly scoped. If the policy trusts any repository, OIDC grants access to anyone who can run a workflow.
Who should use GitHub Actions OIDC for AWS?
Use it if your GitHub Actions workflows call AWS APIs, whether to deploy, upload artifacts, run migrations or apply infrastructure. It fits these groups:
- Teams that currently store IAM user keys in GitHub secrets. These teams gain the most. Each repository that holds a key copy is a separate place where that key can leak and a separate place to update during rotation.
- Platform and infrastructure teams that own several AWS accounts. One OIDC provider per account and one role per repository or environment produce a federation setup you can review in code. That is easier to audit than a list of IAM users whose keys are spread across repositories.
- Security and compliance reviewers. Each session is bound to a repository, a ref or environment, and a run through the trust policy and
role-session-name. CloudTrail then answers "which workflow did this" without extra correlation work. - Organizations with protected environments and required reviewers. OIDC lets the AWS side enforce the GitHub-side approval. A production role can accept only tokens from jobs that declared the approved environment.
It needs the most care when outsiders can influence workflow code, as with fork pull requests and pull_request_target. It is also not the only option for jobs that already run on self-hosted runners with an AWS instance or task role. Both cases are covered in the final section.
How does it work? The AssumeRoleWithWebIdentity flow from a GitHub Actions job
When a job declares permissions: id-token: write, the runner receives a request URL and a bearer token for GitHub's OIDC endpoint. The job, or the AWS credentials action acting for it, calls that endpoint with an audience value, normally sts.amazonaws.com. GitHub returns a JWT signed with its private key. The token describes this specific run and expires within minutes.
The job then sends the JWT to STS through AssumeRoleWithWebIdentity, along with the target role ARN. STS takes several steps before it issues anything. It matches the token's issuer to the IAM OIDC provider registered for token.actions.githubusercontent.com. It checks the signature against GitHub's published signing keys. It confirms the aud claim appears in the provider's client ID list. Finally, it evaluates the role's trust policy conditions against the token's claims. If every check passes, STS returns an access key, secret key and session token. These credentials last one hour by default, up to the role's maximum session duration. Nothing long-lived is stored anywhere.
Three claims carry most of the weight:
issidentifies GitHub as the token issuer.audshows that the token was minted for AWS and not for some other relying party.subidentifies which workload is asking. This is the claim your trust policy should pin.
The format of sub depends on how the job runs:
- Branch push:
repo:ORG/REPO:ref:refs/heads/main. - Tag push: the ref is
refs/tags/.... - Pull request:
repo:ORG/REPO:pull_request, with no branch included. - Job with an environment: the environment replaces the ref entirely, as in
repo:ORG/REPO:environment:production.
Organizations and repositories can also customize the sub template to include other claims, such as job_workflow_ref. A customized template changes the string STS sees, so trust policies written for the default format will stop matching.
+---------------------------+ +-----------------------------+
| GitHub Actions job | (1) request| GitHub OIDC token endpoint |
| permissions: | ---------->| issuer: token.actions. |
| id-token: write | <----------| githubusercontent.com |
| aud=sts.amazonaws.com | (2) JWT | signs JWT, short expiry |
+---------------------------+ +-----------------------------+
| (3) AssumeRoleWithWebIdentity(JWT, role ARN)
v
+----------------------------------------------------------------------+
| AWS STS |
| a. iss -> matches registered IAM OIDC provider |
| b. sig -> checked against GitHub's published signing keys |
| c. aud -> must be in provider client ID list (sts.amazonaws.com) |
| d. sub -> evaluated against role trust policy conditions |
+----------------------------------------------------------------------+
| (4) access key + secret key + session token
v 1 h default, up to role max session duration
+---------------------------+
| Job deploys with |
| short-lived credentials |
+---------------------------+
+----------------------------------------------------------------------+
| sub claim formats (pinned by trust policy) |
| push branch : repo:ORG/REPO:ref:refs/heads/main |
| push tag : repo:ORG/REPO:ref:refs/tags/... |
| pull request: repo:ORG/REPO:pull_request |
| environment : repo:ORG/REPO:environment:production |
| custom : org/repo template may add other claims |
+----------------------------------------------------------------------+
A GitHub Actions job exchanges a GitHub-signed OIDC JWT for short-lived AWS credentials via AssumeRoleWithWebIdentity, with STS checking iss, signature, aud and the trigger-dependent sub claim.
How do you register GitHub as an OIDC provider and write a tight IAM trust policy?
Create the identity provider once per AWS account, in the same infrastructure-as-code stack that owns your deploy roles. In CloudFormation this is AWS::IAM::OIDCProvider, and in Terraform it is aws_iam_openid_connect_provider. Set the URL to GitHub's issuer, token.actions.githubusercontent.com with the scheme, and set the client ID (audience) tosts.amazonaws.com`. Defining the provider in code means a reviewer sees every change to the account's federation surface.
The role's trust policy has three parts:
- A
Federatedprincipal set to the provider ARN,arn:aws:iam::<account-id>:oidc-provider/token.actions.githubusercontent.com. - The action
sts:AssumeRoleWithWebIdentity. - Conditions on
token.actions.githubusercontent.com:audandtoken.actions.githubusercontent.com:sub.
| Trigger | sub value |
Operator |
|---|---|---|
| Branch | repo:acme/api:ref:refs/heads/main |
StringEquals |
| Tag | repo:acme/api:ref:refs/tags/v* |
StringLike |
| Pull request | repo:acme/api:pull_request |
StringEquals |
| Environment | repo:acme/api:environment:production |
StringEquals |
When a job declares an environment, the sub claim uses the environment form instead of the ref form. A branch condition will not match that job.
A condition on aud alone matches any GitHub Actions workflow in any repository on GitHub, because every one of them can request a token for sts.amazonaws.com. A wildcard such as repo:acme/* is narrower, but it still trusts every repository, branch and fork-triggered workflow in your organization. That is broader than a leaked static key, which at least sat in one repository's secrets. Use StringEquals by default. Use StringLike only where a pattern is intentional, such as release tags, and keep the wildcard at the end of a fixed prefix.
Resources:
GitHubOidcProvider:
Type: AWS::IAM::OIDCProvider
Properties:
Url:
ClientIdList:
- sts.amazonaws.com
ProdDeployRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: Allow
Principal:
Federated: !Ref GitHubOidcProvider # Ref returns the provider ARN
Action: sts:AssumeRoleWithWebIdentity
Condition:
StringEquals:
token.actions.githubusercontent.com:aud: sts.amazonaws.com
# Exact match only: jobs that declare environment: production.
# A branch-form sub would not match these jobs.
token.actions.githubusercontent.com:sub: repo:acme/api:environment:production
ReleaseRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: Allow
Principal:
Federated: !Ref GitHubOidcProvider
Action: sts:AssumeRoleWithWebIdentity
Condition:
StringEquals:
token.actions.githubusercontent.com:aud: sts.amazonaws.com
StringLike:
# Intentional pattern: wildcard only after a fixed tag prefix.
token.actions.githubusercontent.com:sub: repo:acme/api:ref:refs/tags/v*
A CloudFormation template that registers GitHub's OIDC issuer once, then creates one role that only an exact production-environment job can assume (StringEquals) and a release role that uses StringLike only for the v tag pattern.*
How do you update the workflow to use OIDC credentials?
Set permissions at the job level, not the workflow level. A job that deploys gets id-token: write and contents: read. Every other job keeps the default or gets nothing. When you declare any permission explicitly, every unlisted scope drops to none. That is why contents: read has to be stated, or actions/checkout fails.
To exchange the token, use aws-actions/configure-aws-credentials with role-to-assume, aws-region and a descriptive role-session-name, so CloudTrail entries identify the run. Pin the action to a full commit SHA rather than a tag. Tags are mutable, and this step handles credentials for your AWS account. If you would rather not depend on an action, you can call STS directly:
- Request a token from the runner's OIDC endpoint with the audience
sts.amazonaws.com. - Pass it to
aws sts assume-role-with-web-identity. - Export the returned credentials as environment variables.
With id-token: write, the runner exposes ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN to every step in the job, not only yours. Any third-party action in that job can request a token and assume the role. That includes linters, cache helpers and notifiers. Keep deploy jobs short and limited to steps you trust. Move everything else into separate jobs without the permission.
Once a deploy succeeds through OIDC, delete the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY repository secrets. Then retire the IAM user's keys:
- Deactivate the keys.
- Check their last-used timestamp to confirm nothing still depends on them.
- Delete the keys and the user.
name: deploy
on:
push:
branches: [main]
permissions: {}
jobs:
lint:
# Third-party tooling runs here, where no OIDC token can be requested.
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@<FULL_40_CHAR_COMMIT_SHA>
- run: make lint
deploy:
needs: lint
runs-on: ubuntu-latest
permissions:
id-token: write # lets steps in this job request an OIDC token
contents: read # must be explicit, or checkout fails
steps:
# Keep this job to steps you trust: any of them can mint a token.
- uses: actions/checkout@<FULL_40_CHAR_COMMIT_SHA>
# Pin to a full commit SHA, not a mutable tag like @v4.
- uses: aws-actions/configure-aws-credentials@<FULL_40_CHAR_COMMIT_SHA>
with:
role-to-assume: arn:aws:iam::123456789012:role/gha-deploy-prod
aws-region: us-east-1
# Shows up in CloudTrail so each session maps back to a run.
role-session-name: gha-deploy-${{ github.run_id }}-${{ github.run_attempt }}
# Confirms the assumed role; no AWS_ACCESS_KEY_ID secret is referenced.
- run: aws sts get-caller-identity
- run: ./scripts/deploy.sh
A workflow that sets permissions to none at the top level, gives only the deploy job id-token: write and contents: read, and assumes an AWS role through a SHA-pinned configure-aws-credentials step while lint tooling runs in a separate job that cannot request a token.
How should you scope roles with environments and least privilege?
When a job declares an environment, GitHub changes the token's sub claim to repo:ORG/REPO:environment:NAME and drops the branch reference. That lets you pair a GitHub environment that has required reviewers and deployment branch rules with a trust policy that matches only that environment's subject. A job targeting production then waits for approval before it can request a token that the production role will accept. A workflow on a feature branch cannot satisfy the condition, even if someone edits it to request the right role ARN.
One role per environment and target
Create a separate role for each environment, and for each deploy target where blast radius differs. For example, the static site bucket and the database migration job should not share a role. Each trust policy then names exactly one subject, and each permission policy lists only the actions and resource ARNs that deployment touches. Avoid wildcard actions on the deploy role. If a pipeline needs broad rights to create infrastructure, give those rights to the infrastructure role only, not to every application role.
Session duration
The role's maximum session duration defaults to one hour and can be raised to twelve. Set it just above your longest realistic apply. A large Terraform or CloudFormation stack that sometimes runs for 90 minutes needs about two hours. A role that only uploads artifacts can stay at the default. If credentials expire mid-apply, you can end up with partially applied state, so measure real run times before tightening this.
The real boundary
With no keys to steal, the security boundary is whoever can change workflow files, merge to protected branches, and approve environment deployments. Require code review on .github/workflows, restrict environment approvers, and treat those settings with the same care as IAM.
#!/usr/bin/env bash
set -euo pipefail
ACCOUNT_ID="111122223333"
REPO="example-org/example-app"
cat > trust-prod.json <<EOF
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": { "Federated": "arn:aws:iam::${ACCOUNT_ID}: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:${REPO}:environment:production"
} }
}]
}
EOF
aws iam create-role \
--role-name gha-example-app-prod-site \
--assume-role-policy-document file://trust-prod.json \
--max-session-duration 7200
aws iam put-role-policy \
--role-name gha-example-app-prod-site \
--policy-name deploy-static-site \
--policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":["s3:PutObject","s3:DeleteObject","s3:ListBucket"],"Resource":["arn:aws:s3:::example-app-prod-site","arn:aws:s3:::example-app-prod-site/*"]}]}'
Creates a production deploy role that trusts only the GitHub environment-scoped subject, sets a two-hour maximum session for long applies, and grants permissions limited to a single S3 bucket.
Why does 'Not authorized to perform sts:AssumeRoleWithWebIdentity' happen and how do you debug it?
STS returns the same generic error whether the token's subject, audience, or issuer fails to match, so you have to narrow the cause yourself. Work through the trust policy conditions one at a time:
| Symptom | Likely cause | Fix |
|---|---|---|
| Step fails before calling STS, complaining about a missing token request URL | Job lacks permissions: id-token: write |
Add it at job or workflow level |
| Worked on push, fails on PRs or tag builds | sub changes with trigger, e.g. :pull_request or :ref:refs/tags/... |
Add an explicit pattern for that trigger |
Fails after adding environment: to the job |
sub becomes repo:ORG/REPO:environment:NAME and no longer contains the ref |
Match the environment form |
| Wildcard pattern never matches | * used under StringEquals, where it is literal |
Use StringLike for patterns |
aud condition fails |
Audience requested is not sts.amazonaws.com |
Align the action's audience input and the policy |
| Broke with no workflow change | Org or repo customized the sub claim template |
Update the policy to the new claim format |
The last row is the most confusing case. A customized template can reorder claims or add new ones, and every existing exact match then fails at once.
Don't guess. Compare the real claims against the policy. In a debug job, request the token, decode only the payload segment, and print selected claims: sub, aud, ref, environment, event_name, and job_workflow_ref. Never echo the raw JWT. It is a bearer credential until it expires, and log masking is not a guarantee. Copy the printed sub into your policy condition as-is and check it character by character. Case and the refs/heads/ prefix are the usual mismatches.
How can it save engineering time?
The time savings come from removing recurring work that static keys create:
- No rotation cycles. Rotating a static key means creating a new key, updating the secret in every repository or organization that holds a copy, confirming deploys still work, and deleting the old key. With OIDC there is nothing to rotate. Each session's credentials expire on their own.
- Smaller leak response. When a static key shows up in a log or a fork, someone has to revoke it, issue a new one, update every consumer, and search CloudTrail to see what the key did. A leaked OIDC-issued session credential expires within the session duration. Investigation also starts from a session name that maps to a specific run.
- Faster audits and incident triage. CloudTrail records the assumed role and session name. You can trace a call to a repository and run directly, without first working out which repositories shared an IAM user.
- Less secret sprawl to manage. New repositories get a role and a trust policy reviewed in infrastructure-as-code. Nobody has to hand out keys and track where they were copied.
Illustrative estimate, with all inputs assumed rather than measured: suppose an organization has 20 repositories that deploy to AWS. It rotates keys quarterly, and each rotation takes 30 minutes per repository to update secrets and verify a deploy. Rotation alone then costs 20 × 4 × 0.5 = 40 engineer-hours per year. Now assume migration takes about 2 hours per repository to write the role, test the trust policy, and retire the key. That is a one-time cost of about 40 hours, so in this example it is recovered in roughly a year from rotation work alone. Any avoided leak response adds to the savings. Substitute your own repository count, rotation frequency and per-repository effort, because the result depends entirely on those inputs.
The new recurring cost is maintaining trust policies. You update them when you add an environment, change triggers, or customize the sub template. The debugging steps above keep that work short.
When should you avoid OIDC, what are the alternatives, and what does migration cost?
OIDC is the wrong default in a few places. Workflows triggered by pull_request_target or by forks run code that outsiders can influence. Any role those runs can reach must be read-only, and it is safer if no matching role exists. Pin trust to refs/heads/main or a protected environment so those runs never match a deploy role.
Every deploy now also depends on GitHub's token service and AWS STS being available when the job starts. A deploy that outlasts the role's maximum session duration fails partway through. Raise that limit on the role or split the job into shorter steps.
| OIDC | Static keys with rotation | Self-hosted runner with instance/task role | |
|---|---|---|---|
| Credential lifetime | One session | Until rotated | Short-lived, refreshed by AWS |
| Secret stored in GitHub | None | Yes | None |
| Per-repo isolation | Trust policy conditions | One IAM user per repo | Weak: every job on the runner gets the role |
| Ongoing work | Maintain trust policies | Rotation and leak response | Patch and scale runners |
The migration cost is mostly one-time. You create one OIDC provider per AWS account and one role per repo or environment, then write and test each trust policy. What you save keeps repeating: for each migrated repo, you stop rotating keys and stop triaging leaked keys.
Migrate one repo at a time:
- Switch the workflow to OIDC.
- In CloudTrail, confirm that
AssumeRoleWithWebIdentityevents show the expectedsub. - Confirm that the old key's last-used timestamp has stopped advancing.
- Deactivate the key, wait a full release cycle, then delete it.
Do not keep the old key as a fallback. It carries the same leak risk the migration was meant to remove.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to github actions oidc aws, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.