Skip to main content

GitHub OIDC

GitHub OIDC is the arrangement where a GitHub Actions job proves who it is to AWS with a signed token instead of an access key. AWS trusts GitHub's OpenID Connect provider, checks which repository the token came from, and issues short-lived credentials for one role. The platform's pipelines hold no AWS keys at all.

What it does​

GitHub mints a JSON Web Token for each job that asks for one, with claims such as the repository and branch in sub. An IAM OIDC identity provider in the AWS account trusts GitHub's issuer, and an IAM role's trust policy allows sts:AssumeRoleWithWebIdentity when the claims match. The aws-actions/configure-aws-credentials step does the exchange and exports temporary credentials to the job.

How BuiltForProd uses it​

The github-oidc unit in the automation account creates the identity provider for token.actions.githubusercontent.com and four kinds of CI role. A trust policy names both the repository and the part of the sub claim after it, in the classic and the id-suffixed claim formats GitHub issues, and each role accepts exactly the subjects its jobs present:

RoleAccepted subjectThe jobs that present it
acme-aws-platform-baseline-deployerenvironment:prodThe baseline apply job, which waits for the prod reviewers
acme-aws-platform-baseline-readerpull_request, ref:refs/heads/mainThe baseline plan on pull requests and the scheduled drift check
acme-<repository>-<stage>-deployer, such as acme-aws-blueprint-webapp-infra-dev-deployerenvironment:<stage> of that repositoryThe blueprint plan, apply and deploy jobs of that stage
acme-aws-blueprint-webapp-code-build, acme-aws-blueprint-etl-code-buildref:refs/heads/mainThe image build job of a code repository

A workflow on any other branch, or a job under another stage's Environment, is refused. For the jobs that declare an Environment, branch control lives in that Environment's deployment branch policy rather than in the trust policy, which is also where reviewer approval is required.

Each role's permissions express its blast radius:

RoleMay assumeOther rights
acme-aws-platform-baseline-deployeracme-terraform-* in any accountRead and write the state bucket
acme-aws-platform-baseline-readeracme-terraform-reader in any accountNone
acme-<repository>-<stage>-deployeracme-terraform-deployer in that stage's account onlyCode repositories: the staging role may add a tag to an image, the webapp prod role may describe images
acme-<repository>-buildNothingPush to that repository's ECR repository only

From there a workflow chains into a role in the target account, which the account-baseline unit creates in every account. acme-terraform-deployer trusts only acme-*-deployer roles from the automation account, and acme-terraform-reader, which holds ReadOnlyAccess and is denied Secrets Manager values and SecureString decryption, trusts only acme-*-reader and acme-*-planner roles. The baseline plan and drift jobs therefore never hold write rights, and a blueprint stage role cannot reach another stage's account. The infrastructure workflows do this chain with an explicit sts assume-role step per stage; the code workflows use the credentials action's role-chaining option. A blueprint's state goes through acme-terraform-state-<stage> in the management account, which, of all CI roles, only that stage account's acme-terraform-deployer may assume and which reads and writes only that stage's state keys.

The role ARNs are GitHub variables, not secrets: AWS_ROLE_ARN on each GitHub Environment holds that stage's role, AWS_READER_ROLE_ARN and AWS_BUILD_ROLE_ARN are repository variables.

The secrets repository is deliberately separate. The iam-oidc-secrets-syncer unit in the security account creates its own provider and one role per stage, acme-secrets-syncer-<stage> for sandbox, dev, staging and prod. Each accepts only environment:<stage> of the secrets repository, decrypts only that stage's SOPS key, writes Parameter Store paths under /acme/ in that stage's platform account and assumes only that account's deployer role, which in turn trusts only that stage's syncer. Every job in both secrets workflows declares the GitHub Environment of its stage. All CI roles carry the mfa-exempt tag so the organization's MFA policy does not block them.

Terms you will see​

TermMeaning
Identity providerThe IAM object that trusts GitHub's token issuer.
sub claimThe token field naming the repository and the ref, pull request or environment.
GitHub EnvironmentThe named deployment target whose branch policy and reviewers gate a job.
Stage roleThe per-repository, per-stage role in the automation account a job assumes first.
Reader roleThe read-only role the baseline plan and drift jobs assume instead of a deployer.
Role chainingUsing one role's credentials to assume a second role in another account.
Web identityAn external identity, such as a GitHub token, exchanged for AWS credentials.

Where to read more​