Skip to main content

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:

  1. The job presents its OIDC token to STS. A CI role in core-auto trusts the GitHub provider only for its own repository, for the audience sts.amazonaws.com and for the subjects its jobs present (see GitHub OIDC). The baseline apply uses acme-aws-platform-baseline-deployer, which accepts only the prod GitHub Environment; the baseline plan and drift jobs use acme-aws-platform-baseline-reader, which accepts a pull request or the main branch; a blueprint job uses its repository's role for that stage, such as acme-aws-blueprint-webapp-infra-dev-deployer, which accepts only the dev Environment.
  2. The CI role assumes a role in the target account, both created in every account by modules/account-baseline and allowing sts:AssumeRole and sts:TagSession. acme-terraform-deployer trusts only core-auto principals whose ARN matches acme-*-deployer; acme-terraform-reader, which holds ReadOnlyAccess and is denied secret values, trusts only acme-*-reader and acme-*-planner. The baseline deployer may assume acme-terraform-* in any account, the reader only acme-terraform-reader, and a blueprint stage role only acme-terraform-deployer in its stage's account.
  3. State goes through a role in core-root. The baseline apply uses acme-terraform-state-access; the baseline plan and drift jobs read state through the management account's acme-terraform-reader, without a lock. A blueprint's root.hcl has the stage account's deployer assume acme-terraform-state-<stage>, which reads and writes only that stage's state keys; acme-terraform-state-access admits 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​

TermMeaning
Temporary credentialsAn access key, secret key and session token that expire together.
AssumeRoleThe STS call that opens a session in a role.
AssumeRoleWithWebIdentityThe STS call that opens a session from an external token, such as GitHub's.
Role chainingAssuming a role from a session that came from another role.
Session tagA key-value pair attached to a session with TagSession.
Subject (sub) claimThe field in the OIDC token that names the repository and ref.
Audience (aud) claimThe intended recipient of the token; sts.amazonaws.com here.

Where to read more​