STS and Role Assumption
AWS Security Token Service (STS) hands out temporary credentials in exchange for proof of identity. Every credential used in the platform comes from STS, whether the caller is a person who signed in or a pipeline running in GitHub.
What it does
STS has a few operations that matter here. AssumeRole swaps one set of credentials for a session in another role, possibly in another account. AssumeRoleWithWebIdentity does the same for a caller that presents a signed token from an external identity provider, such as GitHub. TagSession attaches tags to the session. Every session expires: a role session lasts one to twelve hours, and nothing can extend it. Because credentials are temporary, there is nothing to rotate and nothing to leak for long.
Role chaining is assuming a role from a session that was itself obtained by assuming a role. The platform uses one hop of chaining for pipelines.
How BuiltForProd uses it
Two entry points lead into the accounts. People sign in through IAM Identity Center, which creates a role session for them. Pipelines start from a GitHub Actions job:
- The job presents its OIDC token to STS. A CI role in
core-autotrusts the GitHub provider only for its own repository, for the audiencests.amazonaws.comand for the subjects its jobs present (see GitHub OIDC). The baseline apply usesacme-aws-platform-baseline-deployer, which accepts only theprodGitHub Environment; the baseline plan and drift jobs useacme-aws-platform-baseline-reader, which accepts a pull request or themainbranch; a blueprint job uses its repository's role for that stage, such asacme-aws-blueprint-webapp-infra-dev-deployer, which accepts only thedevEnvironment. - The CI role assumes a role in the target account, both created in every account by
modules/account-baselineand allowingsts:AssumeRoleandsts:TagSession.acme-terraform-deployertrusts onlycore-autoprincipals whose ARN matchesacme-*-deployer;acme-terraform-reader, which holdsReadOnlyAccessand is denied secret values, trusts onlyacme-*-readerandacme-*-planner. The baseline deployer may assumeacme-terraform-*in any account, the reader onlyacme-terraform-reader, and a blueprint stage role onlyacme-terraform-deployerin its stage's account. - State goes through a role in
core-root. The baseline apply usesacme-terraform-state-access; the baseline plan and drift jobs read state through the management account'sacme-terraform-reader, without a lock. A blueprint'sroot.hclhas the stage account's deployer assumeacme-terraform-state-<stage>, which reads and writes only that stage's state keys;acme-terraform-state-accessadmits only the baseline's CI deployer, the admin SSO roles and the management account's IAM users, and denies every principal of the stage accounts except the admin SSO roles.
root.hcl generates the provider assume_role block for every unit from org_accounts.hcl, so no unit names an account id or a role. In the baseline, the environment variable TG_CI_READ_ONLY=true, which the plan and drift workflows set, switches the target role to acme-terraform-reader, so a pull request plan never holds write rights.
Other STS callers follow the same pattern with their own roles: each stage's secrets repository jobs assume acme-secrets-syncer-<stage> in core-security, then that stage account's deployer role, to write parameters; the ACM certificate unit assumes acme-route53-cross-account in core-dns to write validation records; the private-zone units assume it in core-network. The guardrails SCP requires MFA for any principal that is not an SSO session or a tagged automation role, which is why each of these roles carries mfa-exempt = true.
Terms you will see
| Term | Meaning |
|---|---|
| Temporary credentials | An access key, secret key and session token that expire together. |
AssumeRole | The STS call that opens a session in a role. |
AssumeRoleWithWebIdentity | The STS call that opens a session from an external token, such as GitHub's. |
| Role chaining | Assuming a role from a session that came from another role. |
| Session tag | A key-value pair attached to a session with TagSession. |
Subject (sub) claim | The field in the OIDC token that names the repository and ref. |
Audience (aud) claim | The intended recipient of the token; sts.amazonaws.com here. |
Where to read more
- AWS Baseline overview for the accounts the chain reaches.
- IAM for every role named above.
- Terragrunt for how
root.hclgenerates the provider configuration.