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操作はありません。
身元の信頼と、操作の許可を分ける
id-token: writeは、このtoken取得の許可。
誰が発行し、誰向けで、どのjob文脈かを表す。
設定されたIdPとロールの条件に合うかを評価。
引受が許可されたロールのsessionとして要求する。
action・resourceと、適用される許可や拒否を評価。
区画の順に要求を追います。実測した認証成功や操作成功を示すものではありません。ロールを引き受けられても、対象APIが許可されるとは限りません。
OIDCは、長期のAWSアクセスキーをGitHub secretへ配布する方式を避ける選択肢です。ただし短期になっても、過大なロール権限や悪意あるworkflowの影響は残ります。鍵の寿命、信頼するjobの範囲、引受後にできる操作を合わせて設計します。
iss・aud・subは何を表す?
| 用語 | 意味と確認点 |
|---|---|
| iss / issuer | ID tokenの発行元。GitHub.comのOIDCではhttps://token.actions.githubusercontent.com。 |
| aud / audience | tokenが想定する受信者。公式AWS連携actionの例ではsts.amazonaws.com。 |
| sub / subject | どのrepositoryやbranch・PR・environment等の文脈のjobかを表す文字列。 |
| IAMロールのtrust policy | その外部IDを受け入れ、ロールを引き受けさせる条件。 |
| 引受後のpermission | AWS 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へは適用されていません。
| 文脈 | 確認点 |
|---|---|
| branch | 意図したrefを使うjobか。mainという名前だけで許可を決めない。 |
| pull_request | PR文脈のsubject。配信するbranch文脈と同じだと思わない。 |
| environment | environment名を含む文脈。branch部分と同時に現れるとは限らない。 |
| customization | subのカスタム化や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・配信先・利用者側の結果。認証成功だけで原因を決めない。 |
選択すると、正誤と理由が表示されます。
確認して、自分の言葉で説明する
- ID tokenを要求する権限と、AWSの操作権限を分ける。
- 実際のsub形式とjob文脈を、ロールの狭い信頼条件へ対応させる。
- 失敗した段階を特定してから、必要な設定を調べる。
理解を確かめる: OIDCに変えれば、ロールの権限が広くても安全?
いいえ。信頼するjobと、引受後の操作範囲も絞る必要があります。
短期認証情報であっても、その有効期間中はロールの権限が影響するからです。
出典と確認した条件
説明に用いた公式資料を、確認した内容・条件と本文の参照箇所に分けてまとめています。専門家による監修・実際のAWSとの比較検証は行っていません。
確認した内容・条件公式AWS連携例のaudとsub条件。任意custom claimをAWSで使えるとはしない。 公式資料の確認であり、実環境の検証ではありません。
参照した本文身元の信頼と、操作の許可を分ける iss・aud・subは何を表す? 古いsubの例を、そのまま信頼しない 失敗した場所を分けて調べる
確認した内容・条件Web identity tokenによる一時認証情報。既存AWSキーはこの要求の必要条件ではない。 公式資料の確認であり、実環境の検証ではありません。
確認した内容・条件IdP・ロールの信頼条件・引受後の権限とGitHub subject制約。 公式資料の確認であり、実環境の検証ではありません。
参照した本文身元の信頼と、操作の許可を分ける iss・aud・subは何を表す? STSで資格情報を得ることと、S3へ書くこと
確認した内容・条件非信頼コードと特権処理、secret、第三者action、self-hosted runnerの残存状態。 公式資料の確認であり、実環境の検証ではありません。
確認した内容・条件発行元・aud・sub、文脈によるsubject、2026-07-15以後のID入り形式とGHESの適用差。 公式資料の確認であり、実環境の検証ではありません。
確認した内容・条件job用の一時tokenと対象repositoryの権限。AWSのtokenとは区別。 公式資料の確認であり、実環境の検証ではありません。
参照した本文iss・aud・subは何を表す?
確認した内容・条件environmentと保護機能のプラン・公開範囲による条件差。 公式資料の確認であり、実環境の検証ではありません。
参照した本文古いsubの例を、そのまま信頼しない