PTEN

AWS OIDC for GitHub Actions: assume IAM roles without access keys, with Terraform

AWS OIDC for GitHub Actions: your CI proves who it is with a signed token and assumes a temporary IAM role. No access keys, Terraform included.

Author
Will Peixoto
Published
12 Nov 2026
Reading
12 min
Language
EN

🇧🇷 Leia em português: Federação de identidade na AWS: deixe seu CI assumir IAM roles sem access key, com OIDC e Terraform

Every company has a ghost access key. Someone needed a CI job to deploy to AWS, generated a key, pasted it into the pipeline secrets, it worked, and life went on. Six months later nobody remembers it exists, it was never rotated, and it has way more permissions than it needs “because it was faster that way at the time”. We've all been there.

This post is about killing that pattern for good with OIDC identity federation. The idea is simple: your CI stops carrying any long-lived credential to talk to AWS. It proves who it is with a signed token, and AWS hands it a temporary credential on the spot.

The topic came from a piece I cut from my Claude Code on Bedrock material, because it's bigger than Claude: it applies to anything that runs on AWS from a pipeline. It also closes the loop on the post about the AWS MCP servers, where the agent uses your credentials without an access key. There was a human in the loop there. Here there isn't.

The problem OIDC solves

For anything to call AWS, it has to prove who it is, and there are two ways to do that.

The first is a long-lived access key: a key pair that works like a password that never expires. For a human that's already bad. For a robot it's worse, because the key just sits in a secret waiting to leak. If it leaks, whoever found it has access until someone notices and revokes it, which usually takes a while.

The second is a temporary credential: you authenticate somehow and AWS gives you back a credential that lasts a few hours and then dies on its own. For a developer at their machine, that's SSO (you log in through the browser and you're done). But what about when there's nobody around to log in? A CI job running at 3 a.m. doesn't open a browser or type a password.

That's where OIDC (OpenID Connect) comes in. The CI system issues a signed token that basically says “I'm the build job for repository X, on the main branch”. AWS, configured ahead of time to trust that issuer, validates the signature, checks the conditions, and hands back a temporary credential. No static key is stored anywhere waiting to leak, and nobody has to remember to rotate anything.

The disposable visitor badge

If the acronym is scary, think of it this way: OIDC is a disposable visitor badge for robots.

The security guard at the front desk is AWS. The badge is the token your CI issues. You agreed with the guard beforehand on which badge issuers are trusted (that's the OIDC provider). When the robot shows up at the lobby, the guard looks at the badge, checks who issued it, checks whether it's valid for that specific door (the trust policy condition), and lets it into that one room only (the least-privilege role). Visit over, badge expired. Nobody walked out with a master key in their pocket.

Hold on to that picture, because the Terraform further down is exactly that written in HCL: a registry of trusted issuers and a door with a specific lock.

This design has a name, for those who like the proper term: it's the Federated Identity pattern, swapping static credentials for short-lived credentials issued on demand. And it lines up with what the Security pillar of the Well-Architected Framework asks for in SEC02-BP02: workloads using temporary credentials through IAM roles instead of long-term keys. (I broke down the Reliability pillar in the post on the price of high availability; this one is about Security.)

When to use it, and when not to

Before the code, the honest filter, because OIDC doesn't fit every case.

Use OIDC when there's no human in the loop: CI/CD pipelines (GitHub Actions, GitLab CI, Bitbucket Pipelines), scheduled jobs, any automation that runs on its own and needs to talk to AWS. It also works for a workload outside AWS that already gets a token from an OIDC-compatible IdP (Okta, Microsoft Entra ID, Auth0) and needs to call AWS without an access key.

Don't use OIDC for a developer at the terminal. If a person is sitting at the machine, SSO with aws sso login is simpler and already gives you a temporary credential. Building OIDC for that case is overkill with zero payoff. And don't use OIDC as an excuse for broad permissions “because it's just CI”: the security gain of OIDC goes out the window if the role at the end of the chain can do everything.

The flow, in one diagram

This is the full path of a single run, from the job asking for the token to the call on AWS. Notice that at no point is there a stored access key.

mermaid
sequenceDiagram
    participant Job as CI job (GitHub Actions)
    participant CIP as CI OIDC issuer
    participant STS as AWS STS
    participant Role as IAM role (least-privilege)
    participant AWS as AWS service (e.g. Bedrock)

    Job->>CIP: requests an OIDC token for this run
    CIP-->>Job: signed token (repo, branch, environment)
    Job->>STS: AssumeRoleWithWebIdentity (presents the token)
    STS->>STS: validates signature + trust policy + conditions
    STS-->>Job: temporary credential (expires in ~1h)
    Job->>Role: uses the credential
    Role->>AWS: call allowed by the policy
    Note over Job,AWS: no access key was stored anywhere

Hands-on: the complete Terraform

Now the code. This template does both things from the diagram: it registers the trusted token issuer (the OIDC provider) and creates the role with a conditioned trust policy, plus the least-privilege permissions. The example allows invoking Claude models on Bedrock, but the permission policy is the piece you swap for any other service.

One thing changed recently: you no longer need to compute a thumbprint. For GitHub (and also GitLab, Google and Auth0), AWS validates the issuer's TLS certificate against its own library of trusted CAs and ignores any configured thumbprint. In the Terraform AWS provider, thumbprint_list became optional in version 5.81.0, so that data "tls_certificate" block you see in every older example can go.

hcl
# versions.tf
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.81.0" # thumbprint_list is optional from here on
    }
  }
}

# variables.tf
variable "oidc_provider_url" {
  description = "Issuer URL of your OIDC provider (e.g. https://token.actions.githubusercontent.com)"
  type        = string
}

variable "oidc_audience" {
  description = "Audience expected in the token (sts.amazonaws.com for GitHub Actions)"
  type        = string
  default     = "sts.amazonaws.com"
}

variable "github_repo" {
  description = "Authorized repo, in sub format: org/repo (older repo) or org@ORG_ID/repo@REPO_ID (repo created after 2026-07-15)"
  type        = string
}

variable "bedrock_region" {
  description = "Region the CI calls Bedrock from"
  type        = string
  default     = "us-east-1"
}

variable "bedrock_destination_regions" {
  description = "Regions the us. inference profile routes to (check the model card)"
  type        = list(string)
  default     = ["us-east-1", "us-east-2", "us-west-2"]
}

# main.tf
data "aws_caller_identity" "current" {}

locals {
  oidc_host             = replace(var.oidc_provider_url, "https://", "")
  inference_profile_arn = "arn:aws:bedrock:${var.bedrock_region}:${data.aws_caller_identity.current.account_id}:inference-profile/us.anthropic.claude-*"
}

# 1) Register the trusted token issuer.
# No thumbprint_list: for GitHub, AWS validates TLS against its own CA library.
resource "aws_iam_openid_connect_provider" "ci" {
  url            = var.oidc_provider_url
  client_id_list = [var.oidc_audience]
}

# 2) Trust policy: only callers with a valid token AND from the right repo can assume it
data "aws_iam_policy_document" "trust" {
  statement {
    effect  = "Allow"
    actions = ["sts:AssumeRoleWithWebIdentity"]

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

    # Audience must match
    condition {
      test     = "StringEquals"
      variable = "${local.oidc_host}:aud"
      values   = [var.oidc_audience]
    }

    # And the token must come from YOUR repo (otherwise any GitHub repo could assume it)
    condition {
      test     = "StringLike"
      variable = "${local.oidc_host}:sub"
      values   = ["repo:${var.github_repo}:*"]
    }
  }
}

resource "aws_iam_role" "ci_bedrock" {
  name               = "ci-bedrock-invoke"
  assume_role_policy = data.aws_iam_policy_document.trust.json
}

# 3) Least privilege: only InvokeModel, only Claude, only through the inference profile
data "aws_iam_policy_document" "bedrock_invoke" {
  statement {
    sid    = "InvokeViaInferenceProfile"
    effect = "Allow"
    actions = [
      "bedrock:InvokeModel",
      "bedrock:InvokeModelWithResponseStream"
    ]
    resources = [local.inference_profile_arn]
  }

  # The us. profile routes the call to other regions, so the foundation model
  # must be allowed in each of them, but only when the call comes through the profile
  statement {
    sid    = "FoundationModelBehindProfile"
    effect = "Allow"
    actions = [
      "bedrock:InvokeModel",
      "bedrock:InvokeModelWithResponseStream"
    ]
    resources = [
      for r in var.bedrock_destination_regions :
      "arn:aws:bedrock:${r}::foundation-model/anthropic.claude-*"
    ]

    condition {
      test     = "StringLike"
      variable = "bedrock:InferenceProfileArn"
      values   = [local.inference_profile_arn]
    }
  }
}

resource "aws_iam_role_policy" "bedrock_invoke" {
  name   = "bedrock-invoke-claude"
  role   = aws_iam_role.ci_bedrock.id
  policy = data.aws_iam_policy_document.bedrock_invoke.json
}

output "role_arn" {
  value = aws_iam_role.ci_bedrock.arn
}

Apply it the usual way, pointing to the GitHub Actions issuer and to your repo:

bash
terraform init
terraform apply \
  -var="oidc_provider_url=https://token.actions.githubusercontent.com" \
  -var="github_repo=aws-ug-sp/my-repo"

If your account already has the GitHub provider registered (someone created it in the console earlier), the apply fails, because AWS accepts only one OIDC provider per URL in an account. In that case, import the existing one into state or replace the resource with a data "aws_iam_openid_connect_provider" pointing to the same URL.

Two details separate a secure setup from a leaky one. The first is the sub condition. Without it, the trust policy would accept a token from any GitHub repository, and AWS itself blocks that: IAM refuses to create or update a trust policy with the GitHub provider if the token.actions.githubusercontent.com:sub condition is missing or is just a wildcard. With repo:org/repo:*, only your repo gets in. You can tighten it further by locking it to a branch (repo:org/repo:ref:refs/heads/main) or to an environment (repo:org/repo:environment:production). Watch out for one catch: when the job references an environment, the sub switches to the environment format, and a branch-locked condition stops matching.

Then there's the most recent change. Repositories created on GitHub after July 15, 2026 (and repos renamed or transferred after that date) get the sub in an immutable format, with the owner and repo IDs: repo:my-org@123456/my-repo@456789:ref:refs/heads/main. Older repos keep the name-based format until someone opts in. If your repo is new, pass github_repo in the org@ORG_ID/repo@REPO_ID format, otherwise the condition won't match and AssumeRoleWithWebIdentity comes back denied. GitHub's OIDC docs show both formats.

The second detail is the permission policy. It's locked to bedrock:InvokeModel on anthropic.claude-* models, called through the us. inference profile, and nothing else. The foundation model statement exists because Claude Sonnet 4.6 doesn't accept calls with the bare model ID in us-east-1, only through the profile, and the profile can route to us-east-1, us-east-2 or us-west-2. If you allow the foundation model only in your own region, the call can fail depending on where Bedrock sent the request. The role doesn't create anything and doesn't read S3. Think of the pipeline as a place that runs code you don't fully control (third-party actions, build dependencies), the same distrust logic I used in the post on Lambda MicroVMs for untrusted code. Real least-privilege, not that "Resource": "*" we all swear we'll fix later.

Wiring it into GitHub Actions

On the pipeline side, the job is to request the token and exchange it for the credential. The official AWS action does the exchange; you only need to grant id-token: write so the job can request the OIDC token. That permission only controls the token request; repo access still follows whatever you declare in the other lines.

yaml
# .github/workflows/example.yml
permissions:
  id-token: write   # lets the job request the OIDC token
  contents: read

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/ci-bedrock-invoke
          aws-region: us-east-1
          # no aws-access-key-id or aws-secret-access-key here. That's the whole point.

      - name: Call Bedrock
        run: aws bedrock-runtime invoke-model --model-id us.anthropic.claude-sonnet-4-6 ...

There's no access key anywhere in that YAML. configure-aws-credentials takes the OIDC token GitHub issued for this run, calls AssumeRoleWithWebIdentity against the role you created in Terraform, and injects the temporary credential into the rest of the steps (by default it lasts 1 hour). When the job ends, the credential dies.

If you're still on @v4, v6 is the current major. The breaking change is the Node 24 runtime, which requires runner version 2.327.1 or newer. On GitHub-hosted runners that's already taken care of; on self-hosted runners, check before bumping the version.

Checking that it worked

After one run, you can confirm in CloudTrail that the role was assumed via web identity:

bash
aws cloudtrail lookup-events \
  --region us-east-1 \
  --lookup-attributes AttributeKey=EventName,AttributeValue=AssumeRoleWithWebIdentity \
  --query "Events[].{Time:EventTime,Role:Resources[0].ResourceName}" \
  --output table

See the event with your role? Then you're done. If it's not there, check the region: CloudTrail records the call in the region of the STS endpoint that served the request, so use the same one as aws-region in the workflow.

What you take away

OIDC swaps “a long-lived key left in a secret” for “a disposable badge validated on the spot”. You register the token issuer once, create a role with a well-conditioned trust policy (audience plus repo at the very least, in the sub format your repo uses) and least-privilege permissions, and your CI starts assuming that role without carrying any secret. It works for Bedrock, for deploys, for any AWS call from a pipeline.

And that ghost access key from the beginning? Once the pipeline runs through OIDC, deactivate it in IAM, wait one deploy cycle to make sure nothing broke, and delete it. Better safe than sorry.

How are you locking your trust policies today, by branch or by environment? And did the immutable sub bite you on a new repo yet? Tell me in the comments. And if you're ever in São Paulo, come say hi at an AWS User Group São Paulo meetup.

If this post helped, drop a like and share it around. Thanks a lot!

BUILD. SCALE. REPEAT. =D

Will Peixoto

Will Peixoto is a Staff Engineer at Serverless Guru and writes about serverless, AWS architecture and AI agents: what he'd pick, why, and what it costs.

Keep reading

New posts, straight to your inbox

One serverless, architecture or AI agents topic on AWS per issue: what I'd pick, why, and what it costs. No spam.

Opens the subscription page in a new tab.