Who may become this role?
CareFlow bound trust to the intended repository and branch through the verified subject claim, with the audience restricted for AWS STS.
01 · The missing secret
I wanted the pipeline to deploy without owning a permanent AWS key.
The familiar setup was easy to picture: create an access key, paste it into repository secrets, and remember to rotate it forever. Instead, I used OpenID Connect so a particular workflow could present a signed identity to AWS and receive temporary credentials for one role.
No long-lived AWS access key lived in GitHub. That removed a valuable credential from the list of things that could be copied, forgotten, or leaked.
02 · The exchange
The workflow was trusted because its claims matched—not because it came from GitHub.
GITHUB WORKFLOWRequests an OIDC token
→
VERIFIED CLAIMSIssuer · audience · subject
→
AWS STSIssues a temporary role session
The trust policy checked who issued the token, its audience, and the subject identifying the repository and Git reference. If those claims matched, AWS Security Token Service allowed AssumeRoleWithWebIdentity. If they did not, the exchange stopped.
03 · Two boundaries
Who may assume the role is not the same as what the role may do.
What may the assumed role do?
The role received only the AWS actions required by that pipeline stage—not general administrator access.
A narrow permissions policy does not rescue an overly broad trust policy. A narrow trust policy does not excuse broad AWS permissions. Both questions need independent answers.
04 · Failure one
The first red check proved the quality gate was real.
terraform fmtFailed on the first pipeline run.
This was not an identity failure. The check found a real formatting issue, and I fixed the code instead of weakening the gate.
A pipeline is not valuable because every run is green. It is valuable because the same expectations run before a change moves forward.
05 · Failure two
Machine identity made one character of difference matter.
The second failure reached AWS and returned Not authorized to perform sts:AssumeRoleWithWebIdentity. The repository and branch looked correct, but GitHub emitted the canonical lowercase organization name while the AWS exact-match condition used different casing.
repo:canonical-lowercase/name:ref:…≠
repo:Different-Case/name:ref:…The safe fix was to inspect the actual subject and correct the exact condition—not introduce a wildcard until the error disappeared.
06 · The moving format
A correct trust-policy example can still expire.
GitHub introduced immutable identifiers in the default OIDC subject for repositories created after July 15, 2026, and for repositories renamed or transferred after that date. Existing repositories retain the earlier format unless they opt in.
The newer default appends immutable owner and repository IDs to the familiar names. That makes recycled names less dangerous, but it also makes some older tutorials an unreliable source of a literal subject string.
07 · Decision ledger
The pipeline removed a key without removing responsibility.
| Decision | Why | Still required |
|---|---|---|
| OIDC federation | Avoid stored long-lived AWS keys | Token permission and exact trust |
| Repository + branch subject | Narrow which workflow identity is trusted | Verify the emitted claim format |
| Minimal role actions | Limit impact after assumption | Review as pipeline capability grows |
| Keep failing checks | Make controls enforce expectations | Fix the cause rather than the gate |
Trust the verified identity.
A machine identity is useful because its claims are exact, scoped, and testable.
Let credentials expire.
Short-lived role sessions remove the lifecycle of a permanent deployment key.
Inspect before broadening.
A claim mismatch calls for evidence, not a more permissive wildcard.
A red check can be success.
The first formatting failure showed the pipeline was enforcing its contract.
Field check
Before a workflow may assume an AWS role.
- Are issuer and audience conditions explicit?
- Was the actual subject claim previewed or inspected?
- Is trust limited to the smallest useful repository, branch, or environment identity?
- Are role permissions reviewed separately and kept least-privilege?
- Are actions, protected branches, environments, and audit logs part of the delivery boundary?
Primary sources
Documentation behind the implementation.
- GitHub: Configuring OIDC in AWS
- GitHub: OpenID Connect reference
- GitHub changelog: Immutable subject claims
- AWS IAM: Creating a role for OIDC federation
This entry is educational, not security, compliance, or operational advice. It describes a dated CareFlow implementation; verify current claim formats and provider guidance.
Visual edition
The deployment credential we never stored.
A narrated explanation of GitHub-to-AWS federation, the two policy boundaries, and the debugging evidence behind CareFlow's first keyless pipeline.