Secure AWS Automation with GitHub Actions and OpenID Connect (OIDC)
Level: Intermediate
Focus: AWS IAM, temporary credentials, OpenID Connect, GitHub Actions, least privilege.
Example code: aws-community-builders repository
Implementation status:
Created the GitHub Actions OIDC identity provider in AWS IAM.
Created a dedicated S3 test bucket.
Configured an IAM role with an exact GitHub OIDC subject condition.
Configured short-lived AWS credentials using GitHub Actions.
Successfully assumed the IAM role through OIDC.
Successfully accessed the permitted reports/ prefix.
Verified that access to private/ was denied.
Captured Terraform, IAM, CloudTrail and GitHub Actions evidence.
Introduction
CI/CD pipelines often need access to cloud resources: publishing an artifact, deploying an application, or updating infrastructure. A common shortcut is to create an IAM user's access key and store it as a CI/CD secret. These credentials are reusable until rotated or revoked. If exposed through a compromised runner, workflow, or accidental logging, they may be used outside the pipeline.
AWS supports a different pattern: a workload proves its identity using OpenID Connect (OIDC), then requests temporary AWS credentials for an IAM role. This article explains that pattern using GitHub Actions and AWS Security Token Service (AWS STS).
The objective is not just to remove access keys. It is to establish a narrowly scoped trust relationship between a specific repository and workflow context and one AWS role, then grant that role only the permissions the workflow needs.
Figure 1. GitHub Actions obtains a short-lived role session through OIDC instead of using a stored long-lived AWS access key.
1. Why long-lived access keys are risky
Static IAM user access keys can remain valid for a long time. They may be copied into workflows, developer machines, or secret stores. Rotation becomes an operational task, and every copy must be updated safely.
Common risks include accidental commits, credentials printed by workflows, compromised runners, keys remaining active after a project ends, and broad permissions increasing the impact of exposure.
Secret storage is important for credentials that must exist, but it does not change the fact that a static access key is reusable. Where workload federation is supported, short-lived credentials are usually a better fit.
2. The building blocks
| Component | Responsibility |
|---|---|
| GitHub Actions | Runs the automation workflow. |
| GitHub OIDC issuer | Issues a signed identity token for the workflow context. |
| AWS IAM OIDC provider | Establishes trust in the token issuer and audience. |
| IAM role trust policy | Defines which federated identities may assume the role. |
| AWS STS | Validates the token and issues temporary credentials. |
| IAM permissions policy | Defines what the assumed role can do in AWS. |
Two policy types must be understood separately:
- Trust policy: Who can assume this role?
- Permissions policy: What can the role do after it is assumed?
A restrictive trust policy does not compensate for an overly broad permissions policy, and vice versa.
3. How the OIDC flow works
Figure 2. AWS validates the token issuer and audience, evaluates the role trust conditions, and STS issues a temporary session.
- A GitHub Actions job starts.
- The workflow is allowed to request an OIDC token by declaring
id-token: write. - GitHub issues a signed token describing the workflow identity.
- The AWS credentials action presents the token to AWS STS using
AssumeRoleWithWebIdentity. - AWS validates the token against the configured GitHub OIDC provider and evaluates the IAM role trust policy.
- If authorized, STS returns temporary credentials.
- The workflow uses those credentials to call permitted AWS APIs. The session expires according to the role session duration.
id-token: write permits the job to request an OIDC token; it does not itself grant AWS permissions. AWS authorization still depends on the role trust policy and attached permissions.
4. Configure the GitHub OIDC provider in AWS
An IAM OIDC identity provider must exist in the AWS account before a role can trust it.
-
Provider URL:
https://token.actions.githubusercontent.com -
Client ID (audience):
sts.amazonaws.com
Create the provider in IAM using the AWS Console or your approved infrastructure-as-code process. Confirm current AWS and GitHub documentation for provider setup and certificate/thumbprint handling rather than copying an old thumbprint from an example.
The Terraform example in this project accepts the ARN of an already-created GitHub OIDC provider as an input. This keeps provider lifecycle management separate from the example role.
Do not create duplicate providers for the same issuer in one account; reuse an existing provider where appropriate.
5. Understand GitHub's OIDC subject (sub) claim
One of the most important parts of configuring GitHub Actions OIDC is understanding the sub (subject) claim.
AWS uses this claim to determine which GitHub repository and workflow context are permitted to assume an IAM role.
Historically, the default subject format for a workflow running from the main branch was:
repo:OWNER/REPOSITORY:ref:refs/heads/main
However, GitHub introduced immutable OIDC subject claims to strengthen the security of federated identity.
5.1 Legacy subject format
Repositories created before July 15, 2026 generally use the original name-based subject format unless they explicitly opt in to immutable subject claims.
Example:
repo:octo-org/octo-repo:ref:refs/heads/main
This format identifies the repository using its owner and repository names.
5.2 New immutable subject format
Repositories created after July 15, 2026 automatically use an immutable subject format by default.
Example:
repo:octo-org@123456/octo-repo@456789:ref:refs/heads/main
The format is:
repo:OWNER@OWNER-ID/REPOSITORY@REPOSITORY-ID:ref:refs/heads/BRANCH
The new format includes:
- The repository owner's name and immutable ID.
- The repository name and immutable ID.
- The branch context.
The purpose is to prevent identity ambiguity if a repository or organization is renamed, transferred, deleted, or recreated under a previously used name.
5.3 Which repositories use which format?
| Repository situation | Default subject format |
|---|---|
| Created before July 15, 2026 | Legacy format, unless opted in |
| Created after July 15, 2026 | Immutable format |
| Renamed after July 15, 2026 | Immutable format |
| Transferred after July 15, 2026 | Immutable format |
| Existing repository explicitly opted in | Immutable format |
This distinction is important because a trust policy that expects the legacy format will not match a token containing the new immutable format.
For example, the following two values are different:
repo:octo-org/octo-repo:ref:refs/heads/main
repo:octo-org@123456/octo-repo@456789:ref:refs/heads/main
AWS IAM evaluates an exact StringEquals condition against the actual claim. If the values do not match, role assumption fails.
Important: Do not assume which format your repository uses based only on its name or your workflow YAML. Verify the actual token subject before configuring the trust policy.
6. Verify the actual OIDC subject claim
Before creating the IAM trust policy, inspect the sub claim issued by your GitHub Actions workflow.
This is particularly important for repositories created after July 15, 2026, or repositories that have opted in to immutable subject claims.
Add a temporary diagnostic step to a GitHub Actions workflow:
- name: Inspect GitHub OIDC subject
shell: bash
env:
ACTIONS_ID_TOKEN_REQUEST_URL: ${{ env.ACTIONS_ID_TOKEN_REQUEST_URL }}
ACTIONS_ID_TOKEN_REQUEST_TOKEN: ${{ env.ACTIONS_ID_TOKEN_REQUEST_TOKEN }}
run: |
set -euo pipefail
TOKEN_RESPONSE=$(curl -sS \
-H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=sts.amazonaws.com")
TOKEN=$(echo "$TOKEN_RESPONSE" | jq -r '.value')
if [ -z "$TOKEN" ] || [ "$TOKEN" = "null" ]; then
echo "Unable to retrieve OIDC token"
exit 1
fi
python3 -c '
import base64
import json
import sys
token = sys.argv[1]
payload = token.split(".")[1]
payload += "=" * (-len(payload) % 4)
claims = json.loads(
base64.urlsafe_b64decode(payload)
)
print("OIDC subject:", claims.get("sub"))
print("OIDC audience:", claims.get("aud"))
' "$TOKEN"
unset TOKEN TOKEN_RESPONSE
This diagnostic step:
- Requests a GitHub OIDC token with the AWS STS audience.
- Decodes the JWT payload locally.
- Displays only the
subandaudclaims. - Does not print the complete token.
The token is a temporary credential. Never publish it, save it in build artifacts, or print it in workflow logs.
After identifying the subject, use the exact value when configuring the AWS IAM trust policy. Remove the diagnostic step when it is no longer required.
7. Restrict the role trust policy
For a workflow running from the main branch, the trust policy must match the subject format actually issued by GitHub.
Example A: Legacy subject format
For a repository using the legacy format:
{
"Version": "2012-10-17",
"Statement": [
{
"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:octo-org/octo-repo:ref:refs/heads/main"
}
}
}
]
}
Example B: Immutable subject format
For a repository using the new immutable format:
{
"Version": "2012-10-17",
"Statement": [
{
"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:octo-org@123456/octo-repo@456789:ref:refs/heads/main"
}
}
}
]
}
The account ID, owner name, owner ID, repository name, and repository ID above are illustrative values. Replace them with your actual values.
Use only the trust policy that matches your repository's actual subject claim. These are alternatives, not two policies that should automatically be combined.
Terraform implementation
If you manage the IAM role using Terraform, make the complete expected subject an input rather than assuming every repository uses the old format.
For example:
variable "github_oidc_subject" {
description = "Exact GitHub OIDC sub claim for the trusted workflow"
type = string
validation {
condition = length(trimspace(var.github_oidc_subject)) > 0
error_message = "The GitHub OIDC subject must not be empty."
}
}
Use that input in the role trust policy:
data "aws_iam_policy_document" "github_actions_trust" {
statement {
effect = "Allow"
actions = ["sts:AssumeRoleWithWebIdentity"]
principals {
type = "Federated"
identifiers = [var.github_oidc_provider_arn]
}
condition {
test = "StringEquals"
variable = "token.actions.githubusercontent.com:aud"
values = ["sts.amazonaws.com"]
}
condition {
test = "StringEquals"
variable = "token.actions.githubusercontent.com:sub"
values = [var.github_oidc_subject]
}
}
}
Example input for a legacy repository:
github_oidc_subject = "repo:octo-org/octo-repo:ref:refs/heads/main"
Example input for a repository using immutable claims:
github_oidc_subject = "repo:octo-org@123456/octo-repo@456789:ref:refs/heads/main"
This approach makes the trust relationship explicit and avoids silently assuming an outdated subject format.
Branches and GitHub Environments
The subject format also depends on the workflow context.
For example, a workflow using a GitHub Environment may have a subject similar to:
repo:octo-org/octo-repo:environment:production
For repositories using immutable subjects, the owner and repository IDs are also included.
When using environments, inspect the actual sub claim and update the trust policy accordingly. Configure environment protection rules, such as required reviewers and deployment restrictions.
Do not copy a branch-based trust policy unchanged into an environment-based workflow.
Avoid broad conditions such as repo:OWNER/* unless every repository in that scope is intentionally trusted. A wildcard can allow an unintended repository to assume the role.
8. Grant only the permissions the workflow needs
The example role has a deliberately small read-only S3 policy for one bucket and the reports/ prefix:
-
s3:ListBucketon the specific bucket, constrained by thes3:prefixcondition. -
s3:GetObjecton objects underreports/in that bucket.
It does not grant bucket creation, object writes, deletion, IAM administration, or access to every S3 bucket.
For a real pipeline, start with the exact API operations required. Scope resource ARNs wherever the service supports resource-level permissions.
Some actions require "Resource": "*"; document why and consider applicable condition keys.
Do not attach AdministratorAccess just to make a workflow succeed.
9. Configure the GitHub Actions workflow
The sample workflow is in .github/workflows/oidc-demo.yml. It runs on pushes to main and can also be started manually.
Its important permissions are:
permissions:
contents: read
id-token: write
The workflow configures AWS credentials using a role ARN and Region, then runs:
aws sts get-caller-identity
This confirms which AWS identity the job is using. It then lists the approved S3 prefix as a permissions demonstration.
Store the role ARN and bucket name as GitHub Actions repository variables. The role ARN is an identifier, not a secret. The workflow must not contain an AWS access key ID or secret access key.
For production, pin third-party GitHub Actions to a reviewed full commit SHA rather than relying only on a mutable major-version tag. Review action updates through your normal dependency-management process.
10. Security considerations
OIDC reduces the need for long-lived credentials, but it does not make a pipeline automatically secure.
- Restrict the subject to the required repository and branch or protected environment.
- Protect the trusted branch with reviews and required status checks.
- Review workflow changes: someone who can modify a trusted workflow may change what the role does.
- Use least privilege for AWS actions and resources.
- Grant
id-token: writeonly to jobs that need federation. - Protect sensitive environments with required reviewers and deployment rules.
- Pin third-party actions to reviewed immutable references.
- Never print tokens, credentials, or sensitive deployment output.
- Use CloudTrail to review role-assumption and API activity.
- Choose a session duration that is sufficient but not unnecessarily long.
- Verify the repository's actual OIDC subject format before configuring the trust policy.
- Revisit the trust policy if the repository is renamed, transferred, or changes its OIDC subject configuration.
A compromised workflow running in a trusted repository and branch may still obtain the role. OIDC establishes workload identity; repository governance and workflow security remain essential.
11. Troubleshooting
| Symptom | Possible cause | What to check |
|---|---|---|
Not authorized to perform sts:AssumeRoleWithWebIdentity |
Trust policy does not match token claims | Provider ARN, audience, exact sub condition. |
No OpenIDConnect provider found |
Provider missing or ARN/issuer incorrect | Confirm provider exists in the same AWS account. |
| Audience mismatch | Trust policy expects another audience | Confirm sts.amazonaws.com is configured. |
| Subject mismatch | Legacy and immutable subject formats differ | Inspect the actual token's sub claim and update the trust policy. |
| Branch mismatch | Workflow runs from a different branch | Verify the actual branch context. |
| Environment mismatch | Workflow uses a GitHub Environment | Check the environment-based subject and trust condition. |
S3 AccessDenied
|
Role assumed, but permissions are insufficient | Check attached policy, bucket policy, prefix, and organization controls. |
| Workflow cannot request OIDC token |
id-token: write missing or overridden |
Check workflow/job permissions. |
Run:
aws sts get-caller-identity
after configuring credentials.
If it succeeds, role assumption worked. An access-denied error on a later S3 command is a separate permissions issue.
12. Cost considerations
OIDC federation does not require a continuously running compute service. However, AWS API usage and the resources your workflow operates can incur charges. GitHub Actions usage is subject to GitHub's plan and runner limits.
Check current pricing and usage policies before scaling automation.
13. Validation checklist
This project has been deployed or tested. In a dedicated non-production account:
| Validation | Result |
|---|---|
| GitHub OIDC authentication | PASS |
| IAM role assumption | PASS |
| Approved S3 prefix access | PASS |
| Unauthorized prefix access | PASS — AccessDenied |
| CloudTrail verification | COMPLETED |
| Resource cleanup | COMPLETED |
14. When should you use this pattern?
Use OIDC federation when an external workload such as GitHub Actions needs AWS access and supports issuing a trusted identity token.
Examples include:
- CI pipelines that publish artifacts.
- Application deployment workflows.
- Infrastructure automation running Terraform against AWS.
- Automated testing that needs temporary access to AWS resources.
The trust conditions and permissions should differ by workload. A build job that uploads an artifact should not automatically receive the same role as a production deployment job.
Conclusion
Long-lived access keys are not the only way for automation to authenticate to AWS. With OIDC federation, GitHub Actions can present a signed workload identity to AWS STS and receive temporary credentials for a narrowly scoped IAM role.
The strongest design combines a precise trust policy, least-privilege permissions, protected source branches, reviewed workflow changes, and CloudTrail visibility.
GitHub's introduction of immutable OIDC subject claims makes it especially important to verify the actual subject before configuring AWS IAM. A trust policy must match the identity GitHub really issues, not simply a format copied from an older example.
OIDC reduces credential-management risk, but it does not replace secure CI/CD practices.
The central lesson is to treat the pipeline as an identity with a defined trust boundary: decide exactly which workload may assume the role, what it may do, and how its activity will be reviewed.
References
- AWS IAM: Creating an OIDC identity provider
- AWS IAM: Creating a role for OIDC federation
- AWS STS AssumeRoleWithWebIdentity
- GitHub Actions: Configuring OIDC in AWS
- GitHub Actions: OpenID Connect reference — including immutable subject claims
- GitHub Changelog: Immutable subject claims for GitHub Actions OIDC tokens
- GitHub Actions workflow permissions
- AWS IAM best practices


Top comments (2)
Good to see the focus on narrowing the trust relationship and not only removing static keys. The part we'd double-check in the trust policy is the sub condition: matching repo:org/repo:ref:refs/heads/main or an environment name is much safer than a wildcard like repo:org/*, which lets any branch or pull request workflow in that org assume the role. Pairing it with the aud condition set to sts.amazonaws.com closes the other common gap. For pull request workflows, we'd give them a separate read-only role so they never share the deploy role's trust policy.
Thanks for reading my article. Regarding GitHub immutable OIDC, I updated the article. Please do check the article for updated content.
Thanks @lycore