コンテンツへスキップ

GitHub Actions における OIDC とは?

最終更新

GitHub ActionsにおけるOIDC(OpenID Connect)は、ワークフローがクラウドプロバイダーに対して自身のIDを証明し、短期間有効な認証情報を受け取る仕組みです。これにより、長期間有効なアクセスキーをリポジトリのシークレットとして保存する必要がなくなります。

仕組み

各ジョブは、GitHubに署名付きのJSON Web Token(JWT)を要求できます。このトークンには、リポジトリ、ブランチやタグ、環境、ワークフローなど、実行に関するクレームが含まれます。クラウド(AWS、Google Cloud、Azureなど)では、GitHubのトークン発行者を信頼するよう設定し、クレームが設定したルール(例:「リポジトリがacme/apiで、ブランチがmain」)に一致する場合にのみトークンを受け入れるようにします。

実行時に、ジョブはこのトークンを一時的な認証情報と交換します。通常の有効期間は1時間以内です。認証情報は自動的に期限切れになるため、ログに誤って出力された場合でも、永続的なキーが漏えいする場合に比べてリスクははるかに低くなります。

ジョブにはトークンを要求する権限が必要です。そのため、OIDCを使用するワークフローではid-token: writeを設定します。

例

permissions:
  id-token: write   # allow requesting the OIDC token
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/gha-deploy
          aws-region: us-east-1
      - run: aws sts get-caller-identity

ロールのトラストポリシーによって、どのリポジトリやブランチがそのロールを引き受けられるかが決まります。手順に沿った設定方法はAWSでのGitHub Actions OIDCをご覧ください。

利用するメリット

  • ローテーションや漏えい対策が必要なシークレットがありません。
  • 認証情報は1回の実行に限定されます。
  • アクセスルールを、ブランチ、タグ、環境に紐付けられます。
  • クラウドの監査ログで、どのワークフローがどのロールを引き受けたかを確認できます。

よくある間違い

  • 「id-token: write」の設定漏れ。この設定がないと、トークンの要求が権限エラーで失敗します。
  • トラストポリシーの範囲が広すぎる。repo:acme/*に一致するルールでは、組織内のすべてのリポジトリがロールを引き受けられてしまいます。リポジトリを指定し、可能であればブランチや環境も指定してください。
  • トップレベルでpermissionsを設定し、contents: readを省略する。いずれかの権限を指定すると、指定されていない権限はデフォルトで「なし」になります。
  • フォークからのプルリクエストでも使えると想定する。フォークからのワークフローには、デフォルトでは書き込み権限のあるトークンやシークレットは渡されません。
  • トークンをシークレットの保管場所として扱う。トークンが証明するのはIDのみです。認可は引き続きクラウド側のポリシーで管理されます。

OIDCは、トークンがマシンではなくGitHubから発行されるため、セルフホステッドランナーを含むすべてのランナーで動作します。さらなるセキュリティ強化のヒントはGitHub Actionsのセキュリティ対策をご覧ください。

よくある質問

OIDCですべてのシークレットを置き換えられますか?

いいえ。OIDCで置き換えられるのはクラウドのアクセスキーのみです。OIDCに対応していないサードパーティサービスのAPIトークンには、引き続きシークレットが必要です。

GitHubのOIDCに対応しているクラウドはどれですか?

AWS、Google Cloud、Azureが公式ドキュメントで対応を案内しているほか、HashiCorp Vaultなど多くのツールも対応しています。具体的な設定方法は各プロバイダーのドキュメントをご確認ください。

プルリクエストで使っても安全ですか?

特定のブランチや環境に限定するようトラストポリシーを制限すると、プルリクエストのコードがデプロイ用ロールを引き受けることを防げます。