GITHUB ACTIONS / AWS · FOUNDATIONS
GitHub Actions OIDC for AWS: trust conditions, STS and permissions
OIDC federation lets an Actions job present a GitHub-issued identity token to AWS. If the configured trust conditions match, AWS STS can return temporary role credentials. Token retrieval, role assumption and permission for an S3 or other API operation are separate decisions.
Relate issuer, audience and subject to role trust, then distinguish temporary credentials from API authorization.
A job runs on a runner; an IAM role can supply AWS permissions to an assumed session. OIDC stands for OpenID Connect. No real tokens, credentials or AWS operations are involved.
Separate identity trust from operation permission
id-token: write permits requesting this token.
Describe the issuer, intended recipient and workflow context.
Evaluate the configured provider and role trust conditions.
Make requests as the allowed assumed-role session.
Evaluate the action, resource and applicable permissions or denies.
Read the request across these stages. This is not an authentication or execution record. Successful role assumption does not guarantee permission for the target API.
OIDC can avoid distributing long-lived AWS access keys as GitHub secrets. Short lifetime does not neutralize excessive role privileges or malicious workflows. Design credential lifetime, trusted job scope and session permissions together.
What do iss, aud and sub identify?
| Term | Meaning and check |
|---|---|
| iss / issuer | Token issuer: https://token.actions.githubusercontent.com for GitHub.com OIDC. |
| aud / audience | Intended recipient; sts.amazonaws.com in the documented AWS credential-action integration. |
| sub / subject | A string identifying repository and branch, PR, environment or other workflow context. |
| Role trust policy | Conditions under which the external identity may assume the role. |
| Session permissions | Which AWS operation on which resource is allowed; evaluated separately from trust. |
An OIDC identity token is distinct from GITHUB_TOKEN and an AWS access key. id-token: write lets a job request it, but does not itself grant S3 write access. The AWS provider configuration, role trust and operation authorization must still permit the request.
Do not assume one historical subject format
GitHub documentation checked on October 24, 2026 describes immutable subjects containing owner and repository IDs for repositories created after July 15, 2026. Older repositories retain the previous format unless opted in or affected by a later rename or transfer. This rollout excludes GitHub Enterprise Server.
| Context | What to verify |
|---|---|
| Branch | Check the intended ref and job, not merely a name such as main. |
| pull_request | PR context is not automatically the same identity as a deployment branch. |
| Environment | The subject references the environment; do not assume it also embeds the branch. |
| Customization | Account for customized subjects and immutable IDs in the actual configuration. |
Constrain trust to the intended issuer, audience and actual subject. A broad repository wildcard may include unwanted PR or environment contexts. Environment protections can add controls when supported by the plan and visibility. Do not assume AWS trust policies can match arbitrary custom claims.
Getting credentials differs from writing to S3
AssumeRoleWithWebIdentity requests temporary role credentials using a web identity token, without requiring pre-existing AWS credentials for that request. This entry differs from AssumeRole using an AWS-authenticated caller. In either case, subsequent API requests are authorized separately.
Suppose the fictional report-sql-bundle@M should reach a restricted staging area. Limit permissions to the intended write and destination, and keep deployment rights away from unreviewed PR checks. STS success, PutObject success and correct consumer behavior are distinct outcomes. No real role or S3 configuration is created here.
Locate the failure before changing permissions
| Stage | First checks |
|---|---|
| Token request fails | Job id-token permission, event and organization configuration. |
| STS rejects assumption | Provider, audience, subject, role trust and token validity. |
| Target API rejects the session | Action, resource, session permissions and applicable denies. |
| Delivered system behaves incorrectly | Artifact input revision, destination and consumer results; authentication success does not settle this. |
Choose an option to see the result and explanation.
Check, then explain in your own words
- Separate token retrieval from AWS API permission.
- Match the actual subject and job context to narrow role trust.
- Identify the failed stage before investigating settings.
Check your understanding: Does switching to OIDC make a broadly privileged role safe?
No. Also restrict trusted jobs and the operations available to the session.
Temporary credentials still carry the role’s privileges during their lifetime.
Sources and conditions checked
The official references used in this lesson are collected here with their scope, conditions and corresponding sections. Independent expert review and live AWS comparison have not been performed.
Scope and conditionsAudience and subject in the documented AWS integration; arbitrary custom claims are not assumed supported. Documentation review, not live-environment validation.
Used in this lessonSeparate identity trust from operation permission What do iss, aud and sub identify? Do not assume one historical subject format Locate the failure before changing permissions
Scope and conditionsWeb identity token exchange for temporary credentials without pre-existing AWS credentials for the request. Documentation review, not live-environment validation.
Used in this lessonSeparate identity trust from operation permission Getting credentials differs from writing to S3 Locate the failure before changing permissions
Scope and conditionsProvider, role trust, subsequent permissions and GitHub subject restrictions. Documentation review, not live-environment validation.
Used in this lessonSeparate identity trust from operation permission What do iss, aud and sub identify? Getting credentials differs from writing to S3
Scope and conditionsUntrusted code and privileged contexts, secrets, third-party actions and persistent self-hosted state. Documentation review, not live-environment validation.
Used in this lessonSeparate identity trust from operation permission Getting credentials differs from writing to S3
Scope and conditionsIssuer, audience, subject contexts and immutable formats introduced after July 15, 2026; GHES differs. Documentation review, not live-environment validation.
Used in this lessonWhat do iss, aud and sub identify? Do not assume one historical subject format Locate the failure before changing permissions
- GitHub Actions: GITHUB_TOKENChecked:
Scope and conditionsPer-job repository-scoped token, distinct from AWS credentials. Documentation review, not live-environment validation.
Used in this lessonWhat do iss, aud and sub identify?
Scope and conditionsEnvironment protection availability depends on plan and visibility. Documentation review, not live-environment validation.
Used in this lessonDo not assume one historical subject format