目次
失敗地点を二つに分ける
GitHub ActionsのOIDC認証で止まったら、最初に「GitHubからOIDC tokenを取得する段階」と「取得したtokenをCloud providerが受け入れる段階」を分けます。前者はworkflowまたはjobのpermission、token requestを行うaction、reusable workflowの呼び出し設定を確認します。後者はaudience、issuer、subjectなどtoken claimと、provider側のfederated identity / trust policyを照合します。両方を一度に変更すると、原因と権限範囲が分からなくなります。
OIDCは長期credentialをGitHub Secretsへ保存せず、workflowのidentityを短期tokenで外部providerへ示す仕組みです。ただし、OIDCを有効にしただけではcloud resourceへの権限は決まりません。GitHubがtokenを発行する条件と、providerがtokenをどのroleやresourceへ交換するかは別の設定です。まず失敗ログがtoken request前か、providerへの交換後かを見極めます。
GitHub側でtokenを要求できるか
GitHub公式Docsでは、OIDC JWTを要求するworkflowまたはjobに id-token: write permissionが必要です。このpermissionはGitHubのOIDC providerへtokenを要求して受け取るためのもので、repositoryやcloud resourceへ書き込む権限を直接付与するものではありません。OIDCを使うjobが一つなら、そのjobだけに設定できるか検討し、workflow全体へ不要な権限を広げないでください。
workflow内に permissions を書いた場合は、指定していないpermissionがnoneになる仕様も確認します。OIDCのために id-token: write だけを設定すると、checkout等に必要だった contents: read まで失われ、別stepが失敗する場合があります。追加時はtoken取得に必要なscopeと、既存jobの処理に必要なscopeを分け、write-all で回避しないでください。
Reusable workflowでは、呼び出し元と呼び出し先の関係によりpermissionの設定場所を確認します。GitHubは、別organization等で管理されるreusable workflowについて、呼び出し側workflowまたは対象jobで id-token: write を明示する方法を案内しています。エラーが再利用workflow内で出ている場合は、calleeだけでなくcaller側のworkflow、job、permissionsも照合します。
エラー文から確認箇所を絞る
症状：token request自体が拒否される｜確認：対象jobにpermissionがあるか、permissions の階層と綴り、token取得actionがそのjobで実行されるか｜次の判断：requestを行うjobに必要最小のpermissionを付け、再実行でrequest段階が変わったか確認する。
症状：tokenは取得できたがproviderのlogin / assume roleが拒否される｜確認：issuer、audience、subject/branch/environment claim、provider側のtrust policy｜次の判断：実runのclaimとprovider条件を比較する。GitHub側permissionを広げても、provider trustの不一致は直りません。
症状：workflow permissionを指定後、checkoutや別Actionも失敗する｜確認：明示指定でnoneになったpermission、各actionが必要とする権限｜次の判断：必要なread/write scopeだけを対象jobへ戻し、OIDC目的でworkflow全体の権限を広げない。
症状：main branchでは動くがenvironmentを使うjobだけ拒否される｜確認：jobのenvironment、environment protection、token subjectに含まれる条件｜次の判断：provider側trust policyが実際のenvironment claimを許可しているか確認する。回避のためbranch条件を広げず、意図したscopeへ絞ります。
症状：以前動いていた交換が失敗する｜確認：workflow trigger、branch/environment、reusable workflow、audience変更、provider trust policyの更新｜次の判断：成功時と失敗時の設定差を比べます。OIDC debuggerを使う場合もtoken全体を公開せず、必要なclaimだけを権限ある環境で確認してください。
token claimとprovider trustを照合する
GitHubのOIDC tokenにはissuer、audience、subjectのほか、repository、ref、environment、workflowなどのclaimが含まれる場合があります。実際のclaimとsubjectの形は、workflow trigger、environment、organization設定、subject customization等で変わります。記事中の例を全repositoryへコピーせず、対象runが発行する値とprovider policyが比較する値を一つずつ照合してください。
audienceはtokenを受け取る相手を識別します。tokenを要求するactionやtoolが指定するaudienceと、provider側が期待する値は一致しなければなりません。既定値や推奨値はproviderごとに異なるため、AWS、Azure、Google Cloud等の値を相互に流用せず、実際の利用先の公式手順で確認します。
subjectは、どのrepository・branch・tag・environmentのworkflow identityを信頼するかを絞る材料です。GitHubはcloud側に少なくとも一つtrust conditionを設け、信頼していないrepositoryがcloud resourceへtoken交換できないようにすることを案内しています。失敗を直すためにsubject条件を広げず、必要なrepository・ref・environmentだけを許可してください。
JWTをデコード・確認するときも、token全体を公開サイト、issue、チャット、共有ログへ貼ってはいけません。短命であっても認証情報です。必要な診断では、credentialを露出させない手段を使い、audienceやsubject等の最小情報だけを安全な環境で確認します。
安全な診断手順
-
失敗runのworkflow、job、step、branch/tag、environment、時刻を記録します。tokenやsecret自体はコピーしません。
-
ログから、OIDC token request前に止まったか、GitHubからtokenを得た後のprovider loginで止まったかを判断します。区別できなければ、action stepとprovider responseの位置を確認し、原因を断定しません。
-
request前の失敗ならworkflow/jobの
permissions、reusable workflowのcaller設定、token取得actionが実行されるjobを確認します。permissionsを宣言すると省略permissionがnoneになる点を見て、必要な別scopeも確認します。 -
provider拒否なら、該当providerの公式OIDC手順と、runのaudience・issuer・subjectを照合します。Cloud roleが要求する条件、許可するrepository/ref/environment、actionへ渡したaudienceを別々に記録し、provider固有設定を他社の例から推測しないでください。
-
変更は原因となったscopeだけに限定します。token request permissionなら対象jobへ追加し、trust conditionなら意図したrepositoryやbranch/environmentに絞ります。認証方式を長期secretへ戻す前に、移行理由と残るリスクをreviewerへ渡します。
-
再実行ではtoken request、provider交換、必要最小操作の成功を段階別に確認します。デプロイworkflowの場合はProduction変更を伴わない検証方法があるかownerへ確認し、権限gateを迂回しません。
permissionを広げる前の早見表
request前で失敗：id-token: write がtoken要求jobにあるか、callerからreusable workflowへpermissionが届くかを見る。
checkoutも失敗：明示したpermissionで contents: read 等の必要scopeが落ちていないか見る。
provider login後に失敗：GitHub側permissionではなくaudience、issuer、subject/trust条件を見る。
環境やbranch限定で失敗：runのref・environmentとproviderのclaim条件を並べ、該当条件のみ修正する。
原因が曖昧：write-all や広いtrust wildcardを設定せず、step境界とclaim確認で再現範囲を絞る。
よくある誤解
id-token: write はcloud resourceへのwrite permissionではありません。GitHub DocsはOIDC tokenを取得する権限であり、それ自体はresourceへの書き込みを許可しないと説明しています。cloud側で実際に何ができるかは、token交換後にproviderが割り当てるrole等で決まります。
GitHubがtokenを発行したからといって、providerも必ず受け入れるわけではありません。発行とtrust policy判定は別段階です。
token取得を通すためworkflow permissionやtrust conditionを広げると、意図しないjobやbranchに認証経路を与えるおそれがあります。原因scopeに限定した修正と再実行で確認します。
全providerに同じaudienceやsubject形式が使えるわけではありません。共通claimを理解したうえで、連携先providerの現行公式資料に沿って設定します。
引き継ぎ時に残す情報
repository、workflow、job、caller/callee関係、branch/tag、environment、失敗step、token requestの有無、audience、issuer/subject条件を記録します。claimの実値が必要な場合も、tokenを含めず安全なアクセス範囲に限定し、repository secretや短期credentialは貼りません。
修正依頼は「OIDCが失敗する」だけでなく、「このjobでtoken requestが拒否された」「requestは成功しproviderがsubject条件を拒否した」のように段階を示します。次に見るworkflow設定またはtrust policy、再実行するbranch/environmentを指定します。
完了条件と次の行動
Reader Jobの完了条件は、token requestとprovider trustのどちらで失敗したかを判定し、次の担当者が最小のpermissionまたはtrust条件を特定できることです。GitHub側不足ならOIDCを使うjobと必要scopeを記録し、provider側拒否ならaudience・issuer・subjectと実runのclaimを照合します。
実際のrepository、cloud provider、role、workflow fileは提示されていないため、特定providerの設定値や修正YAMLは断定しません。Production credentialsを使うworkflowはowner reviewと実行権限確認後に変更します。原因が確定しない時はtokenを共有せず、エラー段階・workflow/job・environment・trust条件を添えて管理者へ渡してください。
この記事は特定repositoryやcloud accountで認証を実行した体験談ではありません。GitHub公式Docsに基づき、GitHubがtokenを発行する条件と外部providerが信頼する条件を分ける診断手順です。
Sources
GitHub Docs, Configuring OpenID Connect in cloud providers: https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-cloud-providers（新しいタブで開く）
GitHub Docs, OpenID Connect reference: https://docs.github.com/en/actions/reference/security/oidc（新しいタブで開く）
GitHub Docs, Workflow syntax for GitHub Actions: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax（新しいタブで開く）
確認日：2026-10-15。id-token: writeの意味、permissions省略時の扱い、OIDC claims、provider trust conditionsをGitHub公式資料で確認。具体的なCloud provider設定は利用先の現行公式資料との照合が必要。