GitHub Actions から AWS への OIDC: 長期間有効なキーは不要
最終更新日
AWS のアクセスキー ID(AWS_ACCESS_KEY_ID)と シークレットアクセスキー(AWS_SECRET_ACCESS_KEY)を GitHub のシークレットとして保存すると、漏えいした鍵は誰かが気づいてローテーションするまで、どこからでも使えてしまいます。OpenID Connect(OIDC)を使えば、これらの鍵は不要になります。ワークフローの実行ごとに GitHub へ署名付きトークンを要求し、AWS がそれを一時的な認証情報と交換します。その認証情報の有効期限は 1 時間以内です。このガイドでは、設定手順と、適切に制限するための方法を説明します。
仕組み
- ワークフローは GitHub に ID トークンを要求します。トークンには、ジョブが実行されるリポジトリ、ブランチ、環境が記載されています。
- ジョブは
AssumeRoleWithWebIdentityを使ってこのトークンを AWS STS に提示します。 - AWS は、登録済みの ID プロバイダーに対して署名を検証し、ロールの信頼ポリシーをトークンのクレームに照らして評価したうえで、一時的な認証情報を返します。
GitHub 側にシークレットは存在しません。セキュリティは信頼ポリシーの条件によって担保されるため、その条件を慎重に記述することが設定の要点になります。
手順 1:ID プロバイダーを作成する
IAM で、次の設定を使って OpenID Connect プロバイダーを追加します。
- プロバイダー URL:
https://token.actions.githubusercontent.com - 対象者(Audience):
sts.amazonaws.com
AWS は独自の信頼されたルート CA のライブラリを使って GitHub トークンの署名を検証するため、このプロバイダーについてサムプリントを管理する必要はありません。コンソールでは数クリックで設定できます。CLI を使う場合は次のとおりです。
aws iam create-open-id-connect-provider \
--url https://token.actions.githubusercontent.com \
--client-id-list sts.amazonaws.com
プロバイダーはアカウントごとに 1 つで足り、すべてのロールで共有できます。
手順 2:信頼ポリシーを厳格にしたロールを作成する
sub(サブジェクト)クレームは、ワークフローの実行コンテキストを識別します。主な形式は次のとおりです。
- ブランチ:
repo:ORG/REPO:ref:refs/heads/main - 環境:
repo:ORG/REPO:environment:production - プルリクエスト:
repo:ORG/REPO:pull_request - タグ:
repo:ORG/REPO:ref:refs/tags/v1.0.0
1 つのリポジトリの production 環境からのデプロイを許可する信頼ポリシーの例です。
{
"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:my-org/my-repo:environment:production"
}
}
}
]
}
Use StringEquals with an exact sub where you can. If you need several branches, use StringLike with a narrow pattern such as repo:my-org/my-repo:ref:refs/heads/release/. Never use a trust policy that checks only aud, and never repo:my-org/:*: that lets any repository in the organization, including ones with weak review, assume the role.
ジョブに必要な権限だけを含むアクセス許可ポリシーをアタッチします。例としては、1 つのバケットに対する s3:PutObject や、1 つのリポジトリへの ECR プッシュ権限などがあります。ビルド、ステージングへのデプロイ、本番へのデプロイでロールを分けると影響範囲を小さくできます。また、環境ベースのサブジェクトを使うと、本番環境には手動承認を必須にできます。
手順 3:ワークフローで利用する
ジョブには、トークンを要求するための権限が必要です。
permissions:
id-token: write
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v4
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/gha-deploy-production
aws-region: us-east-1
role-session-name: gha-${{ github.run_id }}
- run: aws sts get-caller-identity
- run: aws s3 sync ./dist s3://my-bucket --delete
id-token: write はリポジトリへの書き込み権限を与えるものではありません。OIDC トークンの要求を許可するだけです。この設定を行うと、列挙していないデフォルトの権限は削除されるため、contents: read も併せて指定しています。GitHub Actions のセキュリティ強化で説明しているとおり、aws-actions/configure-aws-credentials は SHA に固定してください。
aws sts get-caller-identity を実行すると、ロールが引き受けられたこと、そしてアカウントとロール ARN が想定どおりであることを素早く確認できます。
サブジェクトクレームのカスタマイズ
既定では sub は上記の形式になります。組織やリポジトリの所有者は、OIDC 設定 API を使って sub に含めるクレームをカスタマイズできます。たとえば repository_id や job_workflow_ref を含めることができます。job_workflow_ref を含めると、特定の再利用可能ワークフローだけにロールの引き受けを許可できます。
"StringLike": {
"token.actions.githubusercontent.com:job_workflow_ref": "my-org/platform-workflows/.github/workflows/deploy.yml@refs/heads/main"
}
AWS がこのプロバイダーの IAM 条件キーで扱えるクレームキーは限られています。依存する前に、aud、sub、job_workflow_ref などの対応キーの一覧を AWS IAM のドキュメントで確認してください。
よくあるエラー
| エラー | 原因 | 対処 |
|---|---|---|
sts:AssumeRoleWithWebIdentity を実行する権限がありません | sub が信頼ポリシーと一致しません | トークンのクレームを出力するか、ブランチ、環境、リポジトリ名を大文字と小文字も含めて正確に比べてください |
認証情報を読み込めませんでした | id-token: write が不足しています | ジョブまたはワークフローのレベルで権限を追加してください |
OpenIDConnect プロバイダーが見つかりません | このアカウントにプロバイダーがないか、URL が誤っています | 上記の URL でプロバイダーを作成してください |
mainでは動作するが、PRでは失敗する | PR の実行では sub が異なります | pull_request 用に読み取り専用の別ロールを追加するか、PR には AWS へのアクセスを許可しないようにしてください |
| environment が原因で失敗 | ジョブに environment: がないため、sub が ref 形式になります | ジョブに environment: を設定してください |
| ジョブの途中でセッションが期限切れ | デフォルトの有効期間は 1 時間です | role-duration-seconds をロールの最大値まで設定するか、ジョブを分割してください |
プルリクエストとフォーク
フォークからの PR は、リポジトリの ID に対する OIDC トークンを要求できません。これは望ましい動作です。同じリポジトリからの PR については、AWS への書き込み権限を与えないようにしてください。PR はワークフローファイルを編集できるため、PR が引き受けられるロールは、リポジトリへの書き込み権限を持つ誰が使っても安全でなければなりません。PR 用のロールには読み取り専用の権限を与えるか、インフラのチェックにのみ plan 権限を使用してください。
AWS 以外での利用
同じ仕組みは、GCP のワークロードアイデンティティ連携、Azure のフェデレーション資格情報、HashiCorp Vault、そして信頼された発行(trusted publishing)に対応しているパッケージレジストリ(PyPI、npm、RubyGems)でも使えます。これらすべてを OIDC に移行すると、長期間有効なシークレットが不要になります。
よくある質問
ローテーションが必要なものはありますか?
ローテーションが必要なアクセスキーはありません。信頼ポリシーがアクセス制御そのものになるため、引き続き定期的に確認してください。
セルフホステッドランナーで OIDC を使えますか?
はい。トークンは、ジョブの実行場所に関係なく GitHub がジョブ用に発行します。ランナーから AWS STS へのネットワークアクセスは引き続き必要です。サードパーティのランナーを使う場合は、OIDC に対応しているかを確認してください。
トークンには何が含まれますか?
iss、aud、sub、repository、ref、environment、workflow、run_id などのクレームが含まれます。すべての一覧は GitHub のドキュメントに記載されています。
ロールの ARN をワークフローに記述しても安全ですか?
はい。ARN は識別子であり、シークレットではありません。誰がそのロールを使えるかは信頼ポリシーで決まります。
関連記事
ワークフローの全般的な強化については、GitHub Actions のセキュリティ確保をご覧ください。デプロイのコストは EC2 コスト計算ツールと S3 コスト計算ツールで見積もれます。compiler.dev のランナーも、他のランナーと同様に GitHub の OIDC トークンを要求できるため、今日作成した信頼ポリシーは、ジョブの実行場所を変えても引き続き機能します。
関連記事
- GitHub Actions における OIDC とは?OIDC を使うと、GitHub Actions のワークフローはシークレットを保存せずに、短期間有効なクラウドの認証情報を取得できます。仕組み、YAML の例、よくある間違いをご覧ください。
- GitHub ActionsでTypeScriptモノレポを高速化するGitHub Actionsで TypeScriptモノレポの型チェックとリンターを高速化する: インクリメンタルtsc、プロジェクト参照、Lintキャッシュ、並列ジョブ
- GitHub ActionsでモノレポのPlaywrightを高速化するGitHub Actions で Node モノレポの Playwright E2E テストを高速化: アプリを一度だけビルドし、Web アプリに変更がないときは E2E をスキップし、シャーディングとレポートのマージを行います。
- READMEにCIの速度バッジを追加するREADME のバッジで CI の速さを表示しましょう。リポジトリの GitHub Actions 実行時間の中央値が自動で更新されます。公開リポジトリは無料です。