DEV Community

Cover image for Secure AWS Automation with GitHub Actions and OpenID Connect (OIDC)
Narendra | SRE
Narendra | SRE

Posted on Edited on Originally published at builder.aws.com

Secure AWS Automation with GitHub Actions and OpenID Connect (OIDC)

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.

GitHub Actions OIDC architecture

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

GitHub Actions OIDC trust flow

Figure 2. AWS validates the token issuer and audience, evaluates the role trust conditions, and STS issues a temporary session.

  1. A GitHub Actions job starts.
  2. The workflow is allowed to request an OIDC token by declaring id-token: write.
  3. GitHub issues a signed token describing the workflow identity.
  4. The AWS credentials action presents the token to AWS STS using AssumeRoleWithWebIdentity.
  5. AWS validates the token against the configured GitHub OIDC provider and evaluates the IAM role trust policy.
  6. If authorized, STS returns temporary credentials.
  7. 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

The format is:

repo:OWNER@OWNER-ID/REPOSITORY@REPOSITORY-ID:ref:refs/heads/BRANCH
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode
repo:octo-org@123456/octo-repo@456789:ref:refs/heads/main
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

This diagnostic step:

  1. Requests a GitHub OIDC token with the AWS STS audience.
  2. Decodes the JWT payload locally.
  3. Displays only the sub and aud claims.
  4. 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"
        }
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

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"
        }
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

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."
  }
}
Enter fullscreen mode Exit fullscreen mode

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]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Example input for a legacy repository:

github_oidc_subject = "repo:octo-org/octo-repo:ref:refs/heads/main"
Enter fullscreen mode Exit fullscreen mode

Example input for a repository using immutable claims:

github_oidc_subject = "repo:octo-org@123456/octo-repo@456789:ref:refs/heads/main"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:ListBucket on the specific bucket, constrained by the s3:prefix condition.
  • s3:GetObject on objects under reports/ 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
Enter fullscreen mode Exit fullscreen mode

The workflow configures AWS credentials using a role ARN and Region, then runs:

aws sts get-caller-identity
Enter fullscreen mode Exit fullscreen mode

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.

  1. Restrict the subject to the required repository and branch or protected environment.
  2. Protect the trusted branch with reviews and required status checks.
  3. Review workflow changes: someone who can modify a trusted workflow may change what the role does.
  4. Use least privilege for AWS actions and resources.
  5. Grant id-token: write only to jobs that need federation.
  6. Protect sensitive environments with required reviewers and deployment rules.
  7. Pin third-party actions to reviewed immutable references.
  8. Never print tokens, credentials, or sensitive deployment output.
  9. Use CloudTrail to review role-assumption and API activity.
  10. Choose a session duration that is sufficient but not unnecessarily long.
  11. Verify the repository's actual OIDC subject format before configuring the trust policy.
  12. 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
Enter fullscreen mode Exit fullscreen mode

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

Top comments (2)

Collapse
 
lycore profile image
Lycore Development •

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.

Collapse
 
narendrasre profile image
Narendra | SRE •

Thanks for reading my article. Regarding GitHub immutable OIDC, I updated the article. Please do check the article for updated content.

Thanks @lycore