コンテンツへスキップ

GitHub Actions から AWS への OIDC: 長期間有効なキーは不要

最終更新日

AWS のアクセスキー ID(AWS_ACCESS_KEY_ID)と シークレットアクセスキー(AWS_SECRET_ACCESS_KEY)を GitHub のシークレットとして保存すると、漏えいした鍵は誰かが気づいてローテーションするまで、どこからでも使えてしまいます。OpenID Connect(OIDC)を使えば、これらの鍵は不要になります。ワークフローの実行ごとに GitHub へ署名付きトークンを要求し、AWS がそれを一時的な認証情報と交換します。その認証情報の有効期限は 1 時間以内です。このガイドでは、設定手順と、適切に制限するための方法を説明します。

仕組み

  1. ワークフローは GitHub に ID トークンを要求します。トークンには、ジョブが実行されるリポジトリ、ブランチ、環境が記載されています。
  2. ジョブは AssumeRoleWithWebIdentity を使ってこのトークンを AWS STS に提示します。
  3. 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 トークンを要求できるため、今日作成した信頼ポリシーは、ジョブの実行場所を変えても引き続き機能します。

このワークフローを compiler.dev で実行する カード登録不要 · 200 無料分

無料で試す