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など多くのツールも対応しています。具体的な設定方法は各プロバイダーのドキュメントをご確認ください。
プルリクエストで使っても安全ですか?
特定のブランチや環境に限定するようトラストポリシーを制限すると、プルリクエストのコードがデプロイ用ロールを引き受けることを防げます。
関連記事
- GitHub Actions から AWS への OIDC: 長期間有効なキーは不要GitHub Actions と AWS の間で OpenID Connect を設定する方法を解説します。対象は、IDプロバイダー、権限を絞った IAM 信頼ポリシー、ワークフロー YAML、よくあるエラーです。
- CI分とは? GitHub Actionsの料金の仕組みCI分とは、パイプラインが使用する課金対象のコンピュート時間です。GitHub Actionsでの分の数え方、切り上げと乗数、そして使用量を減らす方法を説明します。
- GitHub Actionsのキャッシュキーとは?キャッシュキーとは、GitHub Actionsで保存されたキャッシュを識別する文字列です。キーとrestore-keysの仕組みを理解し、古いキャッシュを避ける方法を学びましょう。
- GitHub Actionsの同時実行グループとは?concurrency group は、キーごとに GitHub Actions のワークフローまたはジョブを一度に 1 つだけ実行させ、古い実行をキャンセルできるようにします。YAML の例と、よくある間違いを参照してください。