INFRASTRUCTURE LEARNINGインフラ学習
インフラ大全インフラ大全IT INFRASTRUCTURE / LEARNING
インフラ学習ガイド
教材・演習を探す/

Escで閉じる · 検索語は送信しません

LEARNINGEN

GITHUB ACTIONS / AWS · 入門

GitHub ActionsとAWSのOIDC連携:信頼条件・STS・権限

OIDC連携では、GitHubが発行するID tokenを使ってAWSへjobの身元を伝えます。 AWSが信頼条件を満たすと判断すれば、STSからロールの一時認証情報を受け取れます。tokenの取得、ロール引受、S3等の操作許可は、それぞれ別に確認します。

この教材で学ぶこと

発行元・aud・subとロールの信頼条件を対応させ、短期認証情報と個別APIの権限を区別できる。

先に知っておくこと

jobはrunnerで動く処理、IAMロールはAWSの権限を引き受けるための仕組みです。OIDCはOpenID Connect。実tokenや資格情報の入力・取得、AWS操作はありません。

身元の信頼と、操作の許可を分ける

GitHubのjobから、AWS APIの要求まで
GITHUB JOB
ID tokenを要求

id-token: writeは、このtoken取得の許可。

IDENTITY
発行元・aud・sub

誰が発行し、誰向けで、どのjob文脈かを表す。

AWS TRUST
STSが信頼条件を評価

設定されたIdPとロールの条件に合うかを評価。

SESSION
一時認証情報

引受が許可されたロールのsessionとして要求する。

AWS API
対象操作を認可

action・resourceと、適用される許可や拒否を評価。

区画の順に要求を追います。実測した認証成功や操作成功を示すものではありません。ロールを引き受けられても、対象APIが許可されるとは限りません。

OIDCは、長期のAWSアクセスキーをGitHub secretへ配布する方式を避ける選択肢です。ただし短期になっても、過大なロール権限や悪意あるworkflowの影響は残ります。鍵の寿命、信頼するjobの範囲、引受後にできる操作を合わせて設計します。

iss・aud・subは何を表す?

信頼条件を読むときの用語
用語意味と確認点
iss / issuerID tokenの発行元。GitHub.comのOIDCではhttps://token.actions.githubusercontent.com。
aud / audiencetokenが想定する受信者。公式AWS連携actionの例ではsts.amazonaws.com。
sub / subjectどのrepositoryやbranch・PR・environment等の文脈のjobかを表す文字列。
IAMロールのtrust policyその外部IDを受け入れ、ロールを引き受けさせる条件。
引受後のpermissionAWS APIで何を、どのresourceへ行えるか。trustとは別に評価。

OIDCのID tokenは、GITHUB_TOKENやAWSのアクセスキーと同じものではありません。GitHubのjobがid-token: writeを持つとID tokenを要求できますが、その設定だけでS3の書込み権限が付くわけではありません。AWS側のIdP・ロールの信頼条件と、対象操作の認可が必要です。

古いsubの例を、そのまま信頼しない

2026-10-24確認のGitHub公式資料では、2026-07-15より後に作成されたrepositoryは、所有者とrepositoryのIDを含むimmutable形式のsubを使います。以前のrepositoryは旧形式を維持しますが、opt-inや同日以後の改名・移管で変わります。この変更はGitHub Enterprise Serverへは適用されていません。

形式だけでなく、jobの文脈も確かめる
文脈確認点
branch意図したrefを使うjobか。mainという名前だけで許可を決めない。
pull_requestPR文脈のsubject。配信するbranch文脈と同じだと思わない。
environmentenvironment名を含む文脈。branch部分と同時に現れるとは限らない。
customizationsubのカスタム化やID入り形式を、実際の構成へ対応させる。

trustでは、意図した発行元・aud・実際のsubへ条件を絞ります。repository名の後を広い*で許可すると、意図しないPRやenvironmentまで含む可能性があります。環境の保護ルールも必要なら併用しますが、利用可否はプラン・公開範囲次第です。AWSで任意の独自claimを自由に条件へ使えるとは考えません。

STSで資格情報を得ることと、S3へ書くこと

AssumeRoleWithWebIdentityは、外部のWeb ID tokenでロールの引受を要求するSTS APIです。その要求に、既存のAWS認証情報を必須とはしません。AWSの認証済みcallerから要求するAssumeRoleとは入口が違います。どちらの場合も、発行された一時認証情報で行う後続のAPIは別に認可されます。

架空の成果物report-sql-bundle@Mを、限定したステージング領域へ置くと考えます。必要な書込み操作と宛先へ権限を絞り、未審査のPR検査jobへ配信権限を渡しません。STSの成功、PutObjectの成功、読み手の動作が正常という判断は別です。実ロールやS3の設定はこのページで作りません。

失敗した場所を分けて調べる

どの段階で拒否されたか
段階先に確認すること
tokenを要求できないjobのid-token権限、イベントや組織の設定等。
STSの引受が拒否IdP、aud・sub、ロールのtrust、tokenの有効性等。
引受後の対象APIが拒否action・resource、ロールの許可と適用される拒否。
配信後に期待する動作にならない成果物の入力revision・配信先・利用者側の結果。認証成功だけで原因を決めない。

選択すると、正誤と理由が表示されます。

GitHubのjobにid-token: writeを与えました。直接できるのは?
答えと理由を読む

正解:OIDCのID tokenを要求すること。 · tokenの取得許可であり、AWS APIの許可ではありません。

AWSへ渡すsubの条件は、何から決める?
答えと理由を読む

正解:現在の公式仕様と対象jobの実際のclaims・文脈を照合する。 · 旧形式とID入り形式、branch・PR・environmentを区別し、必要な主体だけを信頼します。

STSから一時認証情報を得ましたがPutObjectが拒否されました。次の確認は?
答えと理由を読む

正解:対象action・resourceと、適用される許可・拒否。 · ロールの引受と、引受後のS3操作は別に評価されます。

AssumeRoleWithWebIdentityの説明として適切なのは?
答えと理由を読む

正解:Web ID tokenを使ってロールを要求し、その後の操作権限は別に評価。 · AWS認証済みcallerを用いるAssumeRoleと入口を分けます。

確認して、自分の言葉で説明する

  1. ID tokenを要求する権限と、AWSの操作権限を分ける。
  2. 実際のsub形式とjob文脈を、ロールの狭い信頼条件へ対応させる。
  3. 失敗した段階を特定してから、必要な設定を調べる。
理解を確かめる: OIDCに変えれば、ロールの権限が広くても安全?

いいえ。信頼するjobと、引受後の操作範囲も絞る必要があります。

短期認証情報であっても、その有効期間中はロールの権限が影響するからです。

出典と確認した条件

説明に用いた公式資料を、確認した内容・条件と本文の参照箇所に分けてまとめています。専門家による監修・実際のAWSとの比較検証は行っていません。