INFRASTRUCTURE LEARNINGINFRASTRUCTURE LEARNING
インフラ大全インフラ大全IT INFRASTRUCTURE / LEARNING
Infrastructure learning guide
Find a lesson or lab/

Esc to close · Search terms stay on your device

LEARNING日本語

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.

What you will learn

Relate issuer, audience and subject to role trust, then distinguish temporary credentials from API authorization.

Prerequisite

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

From an Actions job to an AWS API request
GITHUB JOB
Request an ID token

id-token: write permits requesting this token.

IDENTITY
Issuer, audience, subject

Describe the issuer, intended recipient and workflow context.

AWS TRUST
STS evaluates role trust

Evaluate the configured provider and role trust conditions.

SESSION
Temporary credentials

Make requests as the allowed assumed-role session.

AWS API
Authorize the operation

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?

Terms used when reading trust conditions
TermMeaning and check
iss / issuerToken issuer: https://token.actions.githubusercontent.com for GitHub.com OIDC.
aud / audienceIntended recipient; sts.amazonaws.com in the documented AWS credential-action integration.
sub / subjectA string identifying repository and branch, PR, environment or other workflow context.
Role trust policyConditions under which the external identity may assume the role.
Session permissionsWhich 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.

Check the job context as well as the format
ContextWhat to verify
BranchCheck the intended ref and job, not merely a name such as main.
pull_requestPR context is not automatically the same identity as a deployment branch.
EnvironmentThe subject references the environment; do not assume it also embeds the branch.
CustomizationAccount 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

Where did the request fail?
StageFirst checks
Token request failsJob id-token permission, event and organization configuration.
STS rejects assumptionProvider, audience, subject, role trust and token validity.
Target API rejects the sessionAction, resource, session permissions and applicable denies.
Delivered system behaves incorrectlyArtifact input revision, destination and consumer results; authentication success does not settle this.

Choose an option to see the result and explanation.

What does id-token: write directly enable for a GitHub job?
Read the answer and reason

Answer: Requesting an OIDC identity token. · It permits token retrieval, not AWS API access.

How should the subject condition trusted by AWS be chosen?
Read the answer and reason

Answer: Match current documentation to the target job claims and context. · Distinguish legacy and immutable formats and branch, PR or environment contexts; trust only intended identities.

STS returned temporary credentials, but PutObject was denied. What should be checked next?
Read the answer and reason

Answer: The action, resource and applicable permissions or denies. · Role assumption and later S3 operations are separate authorization decisions.

Which description of AssumeRoleWithWebIdentity is accurate?
Read the answer and reason

Answer: It requests a role using a web identity token; later API rights are evaluated separately. · This federation entry differs from AssumeRole with an AWS-authenticated caller.

Check, then explain in your own words

  1. Separate token retrieval from AWS API permission.
  2. Match the actual subject and job context to narrow role trust.
  3. 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.