GuideLast checked 16 October 2026 with AI-assisted research. Editor: Akshay Dubey.MethodologyCorrections log

To let GitHub Actions deploy to AWS without stored access keys, register GitHub's OIDC issuer as an IAM identity provider, create a role whose trust policy pins the token's sub claim to your repository and branch or environment, and give the job id-token: write. The workflow then exchanges its OIDC token for temporary AWS credentials.

In short

  • GitHub issues each workflow run a short-lived OIDC token. AWS exchanges it for temporary credentials. No long-lived secret is stored. The issued tokens and credentials are short-lived but can still be misused if stolen before they expire.
  • The sub claim condition is the entire security boundary. Get it wrong and the role becomes assumable by workflows you do not control.
  • A trust policy with only an aud condition and no sub condition would let any GitHub Actions workflow on GitHub assume your role, because the audience is a value the requesting workflow chooses. AWS IAM now rejects such a policy when a trust policy is created or updated (AWS IAM User Guide); the check does not run on roles left untouched, so review existing ones.
  • The provider thumbprint is now optional in the IAM API, and AWS verifies the issuer against its own library of trusted root certificate authorities. If your tooling still asks for a thumbprint, derive it from the issuer and do not hardcode one.

What this replaces, and why it is different from rotation

The starting position is an AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY stored as GitHub secrets. That credential does not expire, exists in at least two places from the moment it is created, and appears in whatever config stores, logs and screenshots it passes through on the way. It maps to OWASP NHI7 Long-Lived Secrets and, once it leaks, NHI2 Secret Leakage.

Rotating it on a schedule shortens the window in which a leak is useful. It does not remove the secret, the distribution problem, or the difficulty of enumerating everywhere it has been copied. Federation removes the stored credential outright: the workflow proves what it is to an issuer AWS already trusts, and receives credentials that expire in roughly an hour.

Where the risk moves to

Federation does not remove risk, it relocates it. You stop managing secret custody and start managing trust policy correctness. That is a good trade because a trust policy lives in version control, is reviewable in a pull request, and can be checked by policy-as-code, none of which is true of a secret in a settings page. But it is a trade, and an unreviewed trust policy is worse than a well-managed key.

How the exchange works

1 · Request
The workflow requests an OIDC token from GitHub’s issuer. This requires the job to hold the id-token: write permission; without it the request fails.
2 · Issue
GitHub mints a signed JWT whose claims describe the run: the repository, the ref or environment, the workflow, the actor.
3 · Exchange
The workflow calls sts:AssumeRoleWithWebIdentity, presenting the token.
4 · Validate
AWS verifies the signature against the registered provider, then evaluates the role’s trust policy conditions against the token claims. This is the only point at which your configuration decides who is allowed in.
5 · Credentials
AWS returns temporary credentials scoped to the role, valid for the session duration and then gone.

The Terraform

Two resources: the identity provider, registered once per AWS account, and the role your workflow assumes.

1. The OIDC identity provider

The IAM API no longer requires a thumbprint: ThumbprintList is optional, and AWS verifies the issuer's TLS certificate against its own library of trusted root certificate authorities, using configured thumbprints only when that is not possible (AWS API reference). Current versions of the Terraform AWS provider document thumbprint_list as optional. If your provider version still requires it, derive the value from the issuer and do not paste a literal:

# The issuer's certificate chain, read at plan time.
data "tls_certificate" "github" {
  url = "https://token.actions.githubusercontent.com/.well-known/openid-configuration"
}

resource "aws_iam_openid_connect_provider" "github" {
  url            = "https://token.actions.githubusercontent.com"
  client_id_list = ["sts.amazonaws.com"]
  thumbprint_list = [
    data.tls_certificate.github.certificates[0].sha1_fingerprint
  ]
}

One provider per account, not per repository

Registering the same issuer twice fails. In a multi-account estate, register the provider once per account and create one role per workload, not one role shared across workloads, which is OWASP NHI9 NHI Reuse and destroys your ability to attribute an action to a specific pipeline.

2. The role and its trust policy

variable "github_org" { type = string }
variable "github_repo" { type = string }

data "aws_iam_policy_document" "github_assume" {
  statement {
    effect  = "Allow"
    actions = ["sts:AssumeRoleWithWebIdentity"]

    principals {
      type        = "Federated"
      identifiers = [aws_iam_openid_connect_provider.github.arn]
    }

    # Audience: confirms the token was minted for AWS.
    condition {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:aud"
      values   = ["sts.amazonaws.com"]
    }

    # Subject: THIS is the security boundary. Enumerate exact values.
    condition {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:sub"
      values = [
        "repo:${var.github_org}/${var.github_repo}:environment:production"
      ]
    }
  }
}

resource "aws_iam_role" "deploy" {
  name                 = "gha-${var.github_repo}-deploy"
  assume_role_policy   = data.aws_iam_policy_document.github_assume.json
  max_session_duration = 3600

  tags = {
    # Ownership is a control, not metadata. See NHI1 / ISO 27001 A 5.16.
    Owner      = "REPLACE: named accountable person"
    OwningTeam = "REPLACE: team email or group"
    ConsumedBy = "REPLACE: the workload this serves"
    ReviewBy   = "REPLACE: YYYY-MM-DD"
  }
}

Note StringEquals rather than StringLike on the subject. Use StringEquals with an enumerated list wherever the set of allowed subjects is finite, which it usually is. Reach for StringLike only when you genuinely cannot enumerate, and then constrain everything you can.

Check which subject format your repository issues. GitHub announced on 23 April 2026 that repositories created, renamed or transferred after 15 July 2026 use an immutable default subject that includes the owner and repository IDs, for example repo:octocat@123456/my-repo@456789:ref:refs/heads/main. Existing repositories keep the name-only format used on this page unless they opt in (GitHub changelog). A StringEquals condition written in one format does not match tokens issued in the other, so write the condition for the format your repository actually uses.

3. The workflow

name: Deploy
on:
  push:
    branches: [main]

permissions:
  id-token: write   # Required. Without it, no OIDC token is issued.
  contents: read    # Setting any permission resets the rest to none;
                    # declare every permission the job needs.

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production   # Must match the :environment: in the sub condition
    steps:
      - uses: actions/checkout@v5

      - name: Configure AWS credentials via OIDC
        uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::ACCOUNT_ID:role/gha-REPO-deploy
          aws-region: eu-west-1

      - name: Confirm identity
        run: aws sts get-caller-identity

The permissions block resets everything

Declaring any entry under permissions sets every undeclared permission to none. This is the correct default, but it means a job that previously worked can start failing on an unrelated step. Declare each permission the job needs rather than adding id-token: write and assuming the rest carried over.

Four ways the subject condition goes wrong

The first is catastrophic, and AWS IAM now blocks it when a trust policy is created or updated; the rest are degrees of too-broad.

Insecure subject condition patterns and their consequences
PatternWho can assume the roleWhy it happens
No sub condition at all
aud only
Any GitHub Actions workflow on GitHub The audience is a value the requesting workflow chooses (the default is the repository owner's URL, and the AWS credentials action requests sts.amazonaws.com), so it identifies nothing about you. AWS IAM now returns an error when a GitHub trust policy without a sub condition, or with one that is only a wildcard, is created or updated. The check runs only at create or update, so review roles that predate it.
StringLike with repo:org/* Every repository in the org Written during rollout to avoid a per-repository role, then never narrowed. Any repository a contributor can push to becomes a path to the role.
repo:org/repo:* Any ref, PR or environment in that repo Includes the pull_request subject, so any workflow triggered by a pull request can reach the role. Fork pull requests normally have write permissions reduced to read-only and so cannot request an OIDC token, but pull_request_target workflows and repositories configured to send write tokens to fork pull requests are exceptions. Narrow to the specific ref or environment.
ref:refs/heads/* Any branch A production role assumable from any branch means anyone who can create a branch can deploy. Pin to refs/heads/main, or better, use a GitHub environment with required reviewers.

Guard it in the pipeline

Trust policy correctness is exactly the kind of thing that degrades silently, so check it mechanically rather than at review. A minimal check that fails the build on an unconstrained subject:

# Fail if any GitHub OIDC trust policy lacks a sub condition,
# or uses a wildcard in one. Run in CI on the saved Terraform plan.
set -euo pipefail

terraform plan -input=false -out=tfplan
terraform show -json tfplan > plan.json

# A policy shown as "known after apply" (for example, when the OIDC provider
# is created in the same run) cannot be checked here; re-run after apply.
jq -r '.resource_changes[]?
  | select(.type == "aws_iam_role" and .change.after_unknown.assume_role_policy? == true)
  | "WARN: \(.address) trust policy unknown at plan time"' plan.json >&2

jq -e '
    [ .resource_changes[]?
      | select(.type == "aws_iam_role")
      | .change.after.assume_role_policy? | strings
      | fromjson | .Statement[]?
      | select(.Principal.Federated? // "" | tostring | test("token.actions.githubusercontent.com"))
      | .Condition
    ]
    | map(
        (.StringEquals["token.actions.githubusercontent.com:sub"] // null) as $eq
        | (.StringLike["token.actions.githubusercontent.com:sub"]  // null) as $like
        | if ($eq == null and $like == null) then "missing sub condition"
          elif ($like | tostring | test("\\*")) then "wildcard in sub condition"
          else empty end
      )
    | length == 0
  ' plan.json > /dev/null \
  || { echo "FAIL: insecure GitHub OIDC trust policy"; exit 1; }

This maps to OWASP NHI6 Insecure Cloud Deployment Configurations, and, on our reading, the retained check output can serve as evidence for ISO/IEC 27001:2022 Annex A 8.9 (Configuration management). See the Annex A mapping.

Migrating without an outage

  1. Add the role and provider first. Both can exist alongside the current key with no effect.
  2. Switch one non-production workflow and confirm aws sts get-caller-identity returns the assumed role rather than the old user.
  3. Switch remaining workflows one at a time. Per-workflow roles mean a failure is contained to one pipeline.
  4. Deactivate the access key, do not delete it. AWS reports a last-used timestamp per key; deactivate, wait a full business cycle, confirm no use, then delete.
  5. Search for copies. The key was in GitHub secrets. It was probably also in a developer’s ~/.aws/credentials, a terminal history, and a ticket. Deactivating the key covers all of them at once, which is why step 4 comes before any search.
  6. Record the removal. The deactivation and deletion timestamps are evidence you can use for decommissioning and, on our reading, for SOC 2 criterion CC6.3.

Frequently asked questions

How do I use GitHub Actions with AWS without storing access keys?

Register GitHub's OIDC issuer as an IAM identity provider, create a role whose trust policy accepts tokens from that issuer subject to audience and subject conditions, and give the job id-token: write. The workflow calls sts:AssumeRoleWithWebIdentity and receives short-lived credentials.

What is the sub claim in a GitHub Actions OIDC token?

It identifies the workflow requesting the token, in a format that depends on the trigger context, repo:ORG/REPO:ref:refs/heads/BRANCH for a branch push, repo:ORG/REPO:environment:NAME for an environment-targeted job, repo:ORG/REPO:pull_request for PR events. Repositories created, renamed or transferred after 15 July 2026 use a format that adds the owner and repository IDs, such as repo:ORG@ORG_ID/REPO@REPO_ID:ref:refs/heads/BRANCH. It is the security boundary of the arrangement.

What happens if the sub condition is a wildcard?

The role becomes assumable by workflows you do not control. repo:my-org/* allows any repository in your organisation. A trust policy with only the audience check and no sub condition would allow any GitHub Actions workflow anywhere to assume the role, because the audience is chosen by the requesting workflow. AWS IAM now rejects a GitHub trust policy that lacks a sub condition, or whose sub value is only a wildcard, when it is created or updated.

Is OIDC federation better than rotating access keys?

Structurally, yes. Rotation shortens the window a leaked key is useful; the key still exists and still has to be distributed. Federation removes the stored credential entirely. The residual risk moves from secret custody to trust policy correctness, which is reviewable as code.

Sources

  • GitHub Docs, OpenID Connect in GitHub Actions, docs.github.com
  • OWASP Non-Human Identities Top 10 (2025), owasp.org
  • OWASP NHI Top 10 (2025), full risk list, owasp.org
  • NIST SP 800-53 Rev. 5, Security and Privacy Controls for Information Systems and Organizations (AC-2, AC-6, IA-5), csrc.nist.gov
  • ISO/IEC 27001:2022 Annex A (controls 5.15-5.18, 8.2, 8.5, 8.15, 8.16) paywalled standard; cited by clause, not linked
  • SPIFFE, concepts and SVID overview, spiffe.io

Where a primary URL is not shown, we have not confirmed the figure against the publisher’s own document and say so on the page rather than linking a secondary source that paraphrases it. Paywalled standards (ISO/IEC, AICPA) are cited by clause and not linked. Corrections welcome: report an error.

Disclosure. This reference is free. No vendor pays for coverage, placement, or favourable treatment. HumanAudit Inc., which publishes this site, sells ISO/IEC 42001 documentation and plans NHI governance documentation packs, including an RFP kit that does not name, rank or recommend any vendor; it builds and sells no NHI scanner and no NHI discovery, monitoring or security tool (see About). Links to its offers appear in the header, in the site footer and in one marked box on guide pages; company profiles carry none. See our methodology, sourcing standards and corrections policy.

From the publisher

HumanAudit, which publishes this site, is preparing the NHI Governance pack: an NHI policy, ownership register, lifecycle procedures and one control set mapped, as our interpretation, to PCI DSS v4.0.1, ISO/IEC 27001:2022, NIS2 and DORA. Planned for March 2027; not yet on sale, and no price has been published.

Page history
Migrated from nhimanagement.com on 7 October 2026. Content last reviewed 6 August 2026; it is being re-verified under this site's methodology. Errors: corrections log.
Monthly change log

Know when the NHI landscape changes.

One email a month from this reference: new deals, standards status changes and corrections. No sponsored content. Unsubscribe from any email.

We first email you a link to confirm. Privacy policy.