--- title: "configure-aws-credentialsの使い方：OIDC設定とv6の変更点、sub不一致エラーの直し方" url: "https://www.issoh.co.jp/tech/details/17939/" published: 2026-09-29 updated: 2026-10-04 categories: ["GitHub"] publisher: "株式会社一創" --- # configure-aws-credentialsの使い方：OIDC設定とv6の変更点、sub不一致エラーの直し方 `aws-actions/configure-aws-credentials`は、GitHub ActionsのジョブからAWSへ入るための公式アクションです。この記事では、IAMにGitHubのOIDCプロバイダを登録し、信頼ポリシーを書き、ワークフローから`aws sts get-caller-identity`が通るまでをコマンドとYAMLで確認できる構成です。そのうえで、2026年9月時点の6.3系で変わった点、2026年7月15日以降に作ったリポジトリで形式が変わるsubクレーム、`Not authorized to perform sts:AssumeRoleWithWebIdentity`などのエラーの原因を、公式ドキュメントに基づいて整理します。Terraformまで含めたパイプライン全体の組み方は、[GitHub ActionsとTerraformでAWSのCI/CDを構築する手順の記事](https://www.issoh.co.jp/tech/details/2715/)で扱っています。 ## まとめ：configure-aws-credentialsをOIDCで動かす設定の要点 認証はOIDCの一択です。アクセスキーをGitHubのSecretsに置く方式も動きますが、公式READMEは一時認証情報を得られるOIDCを推奨しています。必要なのは、IAMのOIDCプロバイダ、subとaudで絞った信頼ポリシーを持つIAMロール、ワークフローの`id-token: write`、アクションへの`role-to-assume`と`aws-region`の4つだけです。 いま詰まりやすいのはsubクレームの形式です。2026年7月15日以降に作ったリポジトリでは、subに組織IDとリポジトリIDが付きます。古い記事の信頼ポリシーをそのまま写すと認可エラーで止まるため、形式の確認が必要です。版は`@v6.3.0`のように完全な版番号で固定し、`allowed-account-ids`で意図しないアカウントへの接続を止めておきます。 ## configure-aws-credentialsの役割と5つの認証方式・v6系の変更点 最初に、このアクションが何をしていて、どの入力でどの認証方式になるかを押さえます。ここが曖昧なままだと、エラーが出たときに原因の切り分けができません。 ### STSで得た一時認証情報を環境変数へ書き出すアクションの仕組み [公式リポジトリのREADME](https://github.com/aws-actions/configure-aws-credentials)によると、このアクションはAWSの認証情報とリージョンを環境変数に設定し、後続ステップのAWS CLIやSDKがそれを拾う仕組みです。書き出す変数は`AWS_ACCESS_KEY_ID`・`AWS_SECRET_ACCESS_KEY`・`AWS_SESSION_TOKEN`・`AWS_REGION`などです。 OIDCでは、GitHubが発行するジョブ単位のIDトークン（JWT）をSTSの`AssumeRoleWithWebIdentity`に渡してIAMロールの一時認証情報と交換し、ジョブの終了時に後処理のステップが認証情報を消します。IDトークンの署名検証やクレームの意味は、[OIDCの仕組みとIDトークンの検証手順を解説した記事](https://www.issoh.co.jp/tech/details/6532/)で確認できます。 ### 入力の組み合わせで決まる5つの認証方式とOIDCを選ぶ判断基準 READMEは5つの認証方式を挙げ、どれになるかは指定した入力の組み合わせで決まると説明しています。`aws-region`はどの方式でも必須です。 | 認証方式 | 指定する入力 | 使う場面 | | --------------- | ----------------- | -------------- | | GitHub OIDC（推奨） | ロール | GitHubホストのランナー | | IAMユーザーのキー | キー | OIDCへ移すまでの暫定 | | 静的キーでAssumeRole | キー＋ロール | キーの権限を絞る暫定 | | Webトークンファイル | トークンファイル＋ロール | EKSなど | | 既存の認証情報で引き受け | ロール＋role-chaining | 2段目のロール | 表の「ロール」は`role-to-assume`、「キー」は`aws-access-key-id`と`aws-secret-access-key`、「トークンファイル」は`web-identity-token-file`を指します。2行目と3行目は、長期のアクセスキーをSecretsに置く方式です。キーの漏えい経路と棚卸しの手順は、[GitHub ActionsのSecrets管理とOIDC移行の判断を解説した記事](https://www.issoh.co.jp/tech/details/16939/)にまとめています。新しく組むなら1行目から始め、2行目と3行目は使いません。 ### v5.0.0のタグ体系変更とv6.0.0のnode24移行で変わった版の固定 [公式のCHANGELOG](https://github.com/aws-actions/configure-aws-credentials/blob/main/CHANGELOG.md)で破壊的変更とされているのは、2025年9月3日の5.0.0と2026年2月4日の6.0.0です。5.0.0では真偽値の入力に不正な値を渡したときの扱いが変わりました。同じ版で`allowed-account-ids`と`force-skip-oidc`が入っています。6.0.0では実行環境がnode24に上がりました。セルフホストランナーでnode24が動かない場合は、6系に上げた時点でアクションが起動しなくなります。 6系の中では、6.1.0（2026年4月6日）で名前付きプロファイルへの書き出し、6.2.0（同年6月1日）で追加のセッションタグと`role-session-name`の形式検証、6.3.0で`translate-env-variables`が入りました。[リリース一覧](https://github.com/aws-actions/configure-aws-credentials/releases)では6.3.0の公開日は2026年9月15日です。 5.0.0からは`v6.3.0`のような版番号のタグが[GitHubの不変リリース](https://docs.github.com/en/code-security/concepts/supply-chain-security/immutable-releases)として公開され、後から中身を差し替えられなくなりました。一方の`@v6`は最新の6系へ動く移動タグです。本番のデプロイでは完全な版番号で固定し、更新はDependabotなどのプルリクエストで確かめてから取り込みます。 ## IAMのOIDCプロバイダとロールを作りワークフローからAWSへ接続する手順 ここからは、東京リージョンのアカウントに、`main`ブランチのワークフローだけが入れるロールを作る手順です。アカウントIDやリポジトリ名は自分の環境に置き換えてください。 ### AWS CLIでGitHubのOIDCプロバイダを登録するコマンドと指紋の扱い OIDCプロバイダはアカウントに1つあれば足ります。プロバイダURLは`https://token.actions.githubusercontent.com`、オーディエンスは`sts.amazonaws.com`です。 ``` # アカウントに1回だけ実行する。既にある場合は EntityAlreadyExists で失敗する aws iam create-open-id-connect-provider \ --url https://token.actions.githubusercontent.com \ --client-id-list sts.amazonaws.com # 登録済みのプロバイダを確かめる aws iam list-open-id-connect-providers ``` READMEには、以前のドキュメントでは証明書の指紋（thumbprint）の指定を案内していたが、現在は不要で、指定しても無視されると書かれています。古い手順書にある`--thumbprint-list`は付けなくてかまいません。コンソールから作る手順は[IAMでOIDCプロバイダを作成する公式ページ](https://docs.aws.amazon.com/IAM/latest/UserGuide/id%5Froles%5Fproviders%5Fcreate%5Foidc.html)にあります。 ### subとaudの条件で対象リポジトリとブランチを絞る信頼ポリシー 信頼ポリシーで必ず絞るのは`aud`と`sub`の2つです。READMEは、条件を書かないと他のGitHubユーザーやリポジトリからもロールを引き受けられるおそれがあると警告しています。 ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com", "token.actions.githubusercontent.com:sub": "repo:example-org@123456/web-app@789012:ref:refs/heads/main" } } } ] } ``` ``` # 上のJSONを trust-policy.json に保存してロールを作る aws iam create-role --role-name gha-deploy-web-app \ --assume-role-policy-document file://trust-policy.json # 権限はデプロイに要る分だけ付ける（例は読み取り専用） aws iam attach-role-policy --role-name gha-deploy-web-app \ --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess ``` [GitHubのAWS向けOIDC設定ガイド](https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws)では、`aud`は`StringEquals`で固定し、`sub`はブランチを1つに絞るなら`StringEquals`、`repo:octo-org/octo-repo:*`のように広げるなら`StringLike`を使うと説明しています。READMEは`ForAllValues:`を`Allow`に使わないよう警告しています。クレームが無いときや綴りを誤ったときにも真と評価されるためです。ロール名を`GitHubActions`にすると動かないという報告（Issue #953）もあるので、別の名前にします。 ### id-token: writeを付けたワークフローで接続を確かめるYAML ワークフロー側では`permissions`に`id-token: write`を付けます。これが無いとIDトークンを要求できません。 ``` name: deploy on: push: branches: [main] permissions: id-token: write # OIDCのIDトークンを要求するために必須 contents: read jobs: deploy: runs-on: ubuntu-latest steps: - name: AWSの一時認証情報を取得する uses: aws-actions/configure-aws-credentials@v6.3.0 with: role-to-assume: arn:aws:iam::123456789012:role/gha-deploy-web-app aws-region: ap-northeast-1 role-session-name: gha-${{ github.run_id }} allowed-account-ids: "123456789012" - name: 接続できたアカウントとロールを確かめる run: aws sts get-caller-identity ``` `get-caller-identity`の出力の`Arn`に`assumed-role/gha-deploy-web-app/gha-`と実行IDが並べば成功です。`permissions`をジョブ単位で書くと、ワークフロー単位の指定はそのジョブでは使われません。ジョブごとに書く場合は、各ジョブに`id-token: write`を入れます。なお、OIDCのトークン発行はGitHub側の機能なので、[ローカル実行ツールactの再現範囲を解説した記事](https://www.issoh.co.jp/tech/details/16947/)のとおり、手元のactでは確かめられません。 ## 2026年7月15日以降のリポジトリで変わるsubクレームと信頼ポリシー このアクションの設定例として出回っている記事の多くは、subを組織名とリポジトリ名だけで書いています。2026年7月15日からは、この形式のままでは通らないリポジトリが出てきました。 ### 組織IDとリポジトリIDが付く不変subクレームの形式と対象の範囲 [GitHubの2026年4月23日の告知](https://github.blog/changelog/2026-04-23-immutable-subject-claims-for-github-actions-oidc-tokens/)によると、subクレームに組織とリポジトリの数値IDを`@`区切りで付ける変更が入りました。組織名やリポジトリ名が手放されて別の持ち主に再利用されると、古い信頼ポリシーに合うトークンを第三者が発行できてしまうためです。 ``` # 旧形式（名前だけ） repo:example-org/web-app:ref:refs/heads/main # 新形式（不変subクレーム。組織IDとリポジトリIDが付く） repo:example-org@123456/web-app@789012:ref:refs/heads/main ``` | リポジトリの状態 | subの形式 | | ---------------- | ------ | | 2026年7月15日以降に作成 | 新形式 | | 同日以降に改名・移転 | 新形式 | | それ以前からあり、オプトイン済み | 新形式 | | それ以前からあり、未設定 | 旧形式 | [GitHubのOIDCリファレンス](https://docs.github.com/en/actions/reference/security/oidc)では、既存リポジトリのオプトインは組織またはリポジトリの設定画面のActionsにあるOIDC設定から行うと説明されています。READMEは、旧形式の信頼ポリシーのまま新形式のトークンが来ると`Not authorized to perform sts:AssumeRoleWithWebIdentity`で失敗すると明記しています。 ### トークンのsubとaudを表示して信頼ポリシーの条件を合わせる手順 自分のリポジトリがどちらの形式で発行しているかは、トークンを取って中身を見るのが確実です。READMEが案内していた`actions-oidc-debugger`は2026年9月時点でアーカイブされているため、GitHubのOIDCリファレンスにある手動取得の方法を使います。 ``` - name: OIDCトークンのsubとaudだけを表示する（検証用・privateリポジトリで実行） run: | TOKEN=$(curl -s -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \ "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=sts.amazonaws.com" | jq -r .value) echo "$TOKEN" | cut -d. -f2 | python3 -c ' import sys, base64, json p = sys.stdin.read().strip() p += "=" * (-len(p) % 4) c = json.loads(base64.urlsafe_b64decode(p)) print("sub:", c["sub"]); print("aud:", c["aud"])' ``` トークン本体はログに出さず、デコードしたクレームの2項目だけを表示しています。表示された`sub`をそのまま信頼ポリシーの条件に写せば、形式の食い違いをなくすことが可能です。既存リポジトリをオプトインする場合は、切り替えの間だけ`sub`の条件を旧形式と新形式の2つの値の配列にしておき、切り替えが終わったら旧形式を消します。旧形式を残し続けると、名前の再利用を防ぐという変更の目的が失われます。 ## セッション時間・ロールチェーン・接続先制限による監査と誤デプロイ防止の設定例 基本の4入力で動いたら、次は監査と誤デプロイ防止のための入力を足します。入力の一覧と既定値は[action.yml](https://github.com/aws-actions/configure-aws-credentials/blob/main/action.yml)で確かめられます。 ### セッションの有効時間と監査用のrole-session-nameを決める基準 `role-duration-seconds`の既定は3,600秒（1時間）で、900秒から43,200秒（12時間）まで指定できます。ただし指定できる上限は、ロール側で設定した最大セッション時間の範囲内です。ロールの既定の上限は1時間なので、長いビルドのために2時間を指定するなら、先に[ロールの最大セッション時間](https://docs.aws.amazon.com/IAM/latest/UserGuide/id%5Froles%5Fupdate-role-settings.html)を延ばします。 `role-session-name`の既定値は`GitHubActions`で、どの実行の操作かをCloudTrailで区別できません。READMEの助言どおり`${{ github.run_id }}`を含めると、CloudTrailのイベントからワークフローの実行ページへたどれます。 ### 2段目のロールへ入るrole-chainingとsts:TagSessionの許可 共通アカウントのロールにOIDCで入り、そこから本番アカウントのロールを引き受ける構成では、2回目の呼び出しに`role-chaining: true`を付けます。 ``` - uses: aws-actions/configure-aws-credentials@v6.3.0 with: role-to-assume: arn:aws:iam::111111111111:role/gha-entry aws-region: ap-northeast-1 - uses: aws-actions/configure-aws-credentials@v6.3.0 with: role-to-assume: arn:aws:iam::222222222222:role/deploy-prod aws-region: ap-northeast-1 role-chaining: true role-skip-session-tagging: true allowed-account-ids: "222222222222" ``` READMEによると、2段目のロールの信頼ポリシーは1段目のロールに`sts:AssumeRole`と`sts:TagSession`を許可する必要があります。`role-skip-session-tagging: true`を付ければ`sts:TagSession`は不要です。OIDCの1段目ではアクションはセッションタグを付けません。タグの仕組みは[AWS STSのセッションタグの公式ページ](https://docs.aws.amazon.com/IAM/latest/UserGuide/id%5Fsession-tags.html)にあります。 もう1つの制約がセッション時間です。[IAMロールの用語解説](https://docs.aws.amazon.com/IAM/latest/UserGuide/id%5Froles.html)には、ロールチェーンのセッションはロールの設定にかかわらず最大1時間で、1時間を超える値を指定すると失敗すると書かれています。2段目で`role-duration-seconds`を延ばしても効きません。 ### 許可するアカウントIDの指定とログのマスクによる誤デプロイ・公開への対策 `allowed-account-ids`には、接続してよいアカウントIDをカンマ区切りで渡します。取得した認証情報が別のアカウントのものなら、アクションはその時点で失敗する仕組みです。ロールARNの貼り間違いで検証用の成果物を本番へ流す事故を、AWSの操作が始まる前に止められます。引き受けたロール名まで照合したい場合は、[aws sts get-caller-identityでArnを検証するステップ](https://www.issoh.co.jp/tech/details/18084/)を後続に足します。 アカウントIDは既定ではログでマスクされないため、公開リポジトリでは`mask-aws-account-id: true`を付けます。 ## AssumeRoleWithWebIdentityの認可エラーなど詰まりやすい原因と対処 エラーの多くは、トークンを取れていないか、取れたトークンが信頼ポリシーに合っていないかのどちらかです。出たメッセージから次の表で当たりを付けます。 | 症状 | 主な原因 | 対処 | | --------------------- | --------------------- | ------------------- | | (1) 認証情報を読み込めない | id-token: writeが無い | permissionsに追加 | | (2) WebIdentityの認可エラー | subの形式や値が不一致 | subを表示して条件を直す | | (3) 同上・PRの実行だけ | subが:pull\_requestになる | PR用のロールを用意 | | (4) 同上・environmentだけ | subが:environment:名前 | environment形式を追加 | | (5) SDKの認証情報が不一致 | 既存の認証情報と衝突 | role-chaining: true | | (6) セッション時間の超過 | ロールの上限より長い | 上限を延ばすか値を下げる | 実際のメッセージは、(1)が`Could not load credentials from any providers`、(2)〜(4)が`Not authorized to perform sts:AssumeRoleWithWebIdentity`、(5)が`Credentials loaded by the SDK do not match`、(6)が`The requested DurationSeconds exceeds the MaxSessionDuration set for this role`です。 認可エラーで最も見落とされるのは、プルリクエストとenvironmentの形式です。GitHubのOIDCリファレンスによると、プルリクエストで動くワークフローのsubは`repo:組織/リポジトリ:pull_request`、environmentを指定したジョブは`repo:組織/リポジトリ:environment:Production`になり、どちらにもブランチ名が入りません。`ref:refs/heads/main`だけを許可したロールでは、プルリクエストの検証ジョブは必ず失敗します。 プルリクエストには、読み取り専用の別ロールを用意します。本番用のロールに`:pull_request`を足すと、レビュー前のコードが本番の権限で動いてしまいます。 ## configure-aws-credentialsのOIDC採用条件と見送りの判断 結論から言うと、GitHubホストのランナーからAWSへ入るなら、OIDCとこのアクションの組み合わせを選び、他の方法を比べる必要はありません。判断が分かれるのは、周辺の構成が特殊な場合です。 ### アクセスキー方式を当面残してよい条件と、すぐOIDCへ移す構成 アクセスキー方式を残してよいのは、社内ネットワークに閉じたGitHub Enterprise Serverのように、AWSからOIDCの発行元へ到達できない環境と、OIDCトークンを発行できないCIからこのアクションを使っている環境に限られます。その場合も、表の3行目のように静的キーでAssumeRoleし、キー自体の権限は`sts:AssumeRole`だけにします。 逆に、GitHubホストのランナーでアクセスキーを使い続けている構成は、すぐ移します。移行の作業は、この記事の手順でロールを作り、ワークフローの2入力を`role-to-assume`に置き換え、Secretsのキーを無効化する、という3段の手順です。手元の開発者端末の認証は別の話で、[aws loginとsso loginの使い分けを解説した記事](https://www.issoh.co.jp/tech/details/17567/)の方式で分けて考えます。 ### 複数アカウントと複数環境の権限設計を外部に任せる構成と規模の目安 1アカウント・1リポジトリなら、このアクションの設定はこの記事の3つのコードで終わります。時間がかかるのは、その手前の権限設計です。本番・検証・開発のアカウントが分かれている、リポジトリが10本を超える、environmentごとに承認者を分けたい、のどれかに当てはまると、ロールの切り方と信頼ポリシーの条件の組み合わせが一気に増えます。 この段階で設計を誤ると、広すぎる`StringLike`の条件が全リポジトリに残ります。アカウント構成・リポジトリ数・デプロイ先の3点が決まっているなら、[DevOps・CI/CD導入支援のサービス](https://www.issoh.co.jp/service/system/devops/)に相談すると、ロール設計から既存ワークフローの移行までの見積もりの前提がそろいます。 ## よくある質問 configure-aws-credentialsの設定で出やすい疑問を、公式READMEとGitHub・AWSのドキュメントに基づいて整理します。 ### configure-aws-credentialsの最新バージョンはいくつですか？ 2026年9月時点の最新は6.3系で、公式のリリース一覧では6.3.0が2026年9月15日に公開されています。6系は2026年2月の6.0.0で実行環境がnode24に上がった系統で、セルフホストランナーではnode24が動くことの事前確認が必要です。本番では`@v6.3.0`のように完全な版番号で固定します。 ### OIDCプロバイダのthumbprintは指定する必要がありますか？ 必要ありません。公式READMEには、指紋の指定は現在は不要で、指定しても無視されると書かれています。古い手順書やTerraformのコードに`thumbprint_list`が残っていても動作には影響しません。プロバイダはアカウントに1つあれば、複数のロールから共有できます。 ### Not authorized to perform sts:AssumeRoleWithWebIdentityはどう直しますか？ トークンのsubが信頼ポリシーの条件と合っていないのが主な原因です。新しいリポジトリの不変subクレーム、プルリクエストとenvironmentの形式の3つを疑い、トークンのsubを表示してその値を条件に写すのが最短の直し方です。audを`sts.amazonaws.com`以外にしている場合は、OIDCプロバイダ側のオーディエンスとも照合します。 ### アクセスキーをSecretsに置く方式から移行するには何をしますか？ IAMにGitHubのOIDCプロバイダとロールを作り、ワークフローに`id-token: write`を足して、アクションの`aws-access-key-id`と`aws-secret-access-key`を`role-to-assume`へ置き換えます。デプロイが通ったらアクセスキーを無効化し、CloudTrailで利用が無いことを確かめてから、キーとSecretsを削除します。 ### 1つのジョブで複数のAWSアカウントに接続できますか？ できます。1つは2段目の呼び出しに`role-chaining: true`を付けて、1段目のロールから別アカウントのロールを引き受ける方法です。この場合、2段目のセッションは最大1時間に制限されます。もう1つは6.1.0で入った`aws-profile`を使い、アカウントごとに名前付きプロファイルへ書き出す方法です。後続のコマンドで`--profile`を切り替えます。 ## 関連記事 - [GitHub ActionsとTerraformでAWSのCI/CDを構築する手順（OIDC・S3ネイティブロック対応）](https://www.issoh.co.jp/tech/details/2715/)：このアクションを組み込んだパイプライン全体を、Terraformの状態管理まで含めて構築する手順の記事 - [GitHub ActionsのSecrets管理｜置き場所の選定と漏えい経路・OIDC移行の判断](https://www.issoh.co.jp/tech/details/16939/)：Secretsに残る長期キーを棚卸しし、OIDCへ移す優先順位を決める記事 - [OIDC（OpenID Connect）とは？IDトークンの検証手順とOAuth 2.0との違いを解説](https://www.issoh.co.jp/tech/details/6532/)：subやaudなど、信頼ポリシーで絞るクレームの意味を仕様から確認できる記事 - [CI/CDとは：仕組み・パイプライン構成・GitHub Actionsの設定例と導入判断の基準を解説](https://www.issoh.co.jp/column/details/13002/)：デプロイの自動化をどこまで進めるかを、パイプラインの全体像から判断する記事 - [GitHub Actionsをローカル実行するact｜導入とイメージ選択・再現できる範囲](https://www.issoh.co.jp/tech/details/16947/)：OIDCを含め、手元で再現できない機能と検証範囲の分け方を扱った記事 --- 出典: [configure-aws-credentialsの使い方：OIDC設定とv6の変更点、sub不一致エラーの直し方]()（株式会社一創）