Vault の GitHub 認証を実務で使い切る：組織・チームベース認可の設計と実装

Vault の GitHub 認証は、GitHub の個人アクセストークンを用いて組織メンバーであることを検証し、所属チームに応じて Vault ポリシーを付与するシンプルで強力な方法です。

試験では「どこに何を設定するか」「チームとユーザーのマッピング差」「複数組織の扱い」など基本設計の理解が問われやすいため、実務の手順と併せて整理します。

GitHub 認証の全体像

Vault の GitHub 認証は、ログイン時に提示された GitHub 個人アクセストークンを GitHub API で検証し、指定の組織メンバーであるかを確認します。ユーザーが所属するチーム名（スラッグ）と Vault 側のチームマッピングを照合し、対応するポリシー集合をトークンに付与します。

基本構成は「GitHub 組織の指定」「チーム→ポリシーのマッピング」「ユーザー固有マッピング（必要に応じて）」の三点です。1 つの認証マウントで扱える組織は 1 つが原則で、複数組織を扱う場合は認証マウントを複数用意します。

• ログインコマンド: vault login -method=github token=<GitHub_PAT>
• 前提: GitHub トークンは通常 read:org スコープが必要（組織/チーム情報の参照用）
• チーム名は GitHub のチームスラッグを使用（表示名ではなく、例: platform-team）
• 付与ポリシーは、該当する全チームとユーザーマッピングの和集合

GitHub 認証のリクエストフロー

Developer                 Vault (auth/github)                 GitHub API
    |  vault login -method=github token=ghp_xxx  |                       |
    |------------------------------------------->|  verify token/org      |
    |                                            |----------------------->|
    |                                            |  team membership       |
    |                                            |<-----------------------|
    |<--------------------------- Vault token (policies from team maps)   |

組織・チームベース認可の設計指針

最小権限を実現するため、原則はチーム単位でポリシーを割り当てます。ユーザー個別のマッピングは例外対応（緊急時や一時的な昇格）に限定し、恒常運用は避けます。これにより GitHub 側のチーム管理がそのまま権限管理となり、監査容易性が高まります。

同一ユーザーが複数チームに所属する場合、付与されるポリシーは和集合になります。無関係な広範ポリシーを持つチームに安易に所属させない運用が重要です。複数組織を扱う必要がある場合は、認証マウントを分けて organization をそれぞれ設定します。

• チームスラッグは GitHub 側で一意。Vault マッピング時もスラッグを用いる
• ポリシーは「読み取り」「書き込み」「管理」を明確に分離した命名にする（例: kv-read, kv-write）
• 複数組織対応はマウント分割で行い、パスとポリシー名衝突に注意
• デフォルトポリシーは最小限（できれば無し）とし、チームマッピングのみで権限を付与

セットアップ手順（OSS GitHub / GitHub Enterprise Server）

前提として、Vault 管理者権限と GitHub の個人アクセストークン（通常は read:org スコープ）が必要です。GitHub Enterprise Server を使う場合は API の base_url を指定します。

手順は「認証マウント有効化」「organization 設定」「チームマッピング」「ログイン検証」の順です。チーム名はスラッグで指定します。

• Vault で auth/github を有効化
• organization と TTL/Max TTL を設定
• auth/github/map/teams/<team-slug> にポリシーを割り当て
• GitHub Enterprise Server は base_url=https://<ghes>/api/v3 を指定

実行例（CLI）

# 1) GitHub 認証マウントを有効化
vault auth enable github

# 2) 組織とトークン TTL を設定（OSS GitHub）
vault write auth/github/config \
  organization="acme" \
  ttl="1h" \
  max_ttl="4h"

# 3) 参照専用ポリシーを用意（例）
vault policy write kv-read - <<'HCL'
path "secret/data/app/*" {
  capabilities = ["read", "list"]
}
HCL

# 4) チームスラッグにポリシーをマッピング（複数可、カンマ区切り）
# 注意: GitHub のチーム「Platform Team」のスラッグが platform-team である想定
vault write auth/github/map/teams/platform-team value="kv-read,default"

# 5) ログイン検証（GitHub PAT は read:org を付与し、対象組織で SSO 認可が必要な場合は事前に承認）
export GITHUB_TOKEN="ghp_xxx..."
vault login -method=github token="$GITHUB_TOKEN"

# 6) GitHub Enterprise Server を使う場合の設定例
vault write auth/github/config \
  organization="acme" \
  base_url="https://github.company.com/api/v3" \
  ttl="1h" \
  max_ttl="4h"

トークン運用：TTL、更新、失効の考え方

GitHub 認証で発行される Vault トークンは、設定した TTL と Max TTL に従って有効期限が管理されます。チーム離脱の即時反映はトークンに対して自動では行われないため、短めの TTL 設計と計画的な更新（または再ログイン）を運用基準にします。

オフボーディングやインシデント対応では、アクセサ単位の失効を活用します。監査要件がある環境では、更新・失効操作を含めて監査ログを必ず有効化します。

• 短めの TTL（例: 1h）と Max TTL（例: 4h）でリスクを低減
• 再ログインでチーム変更を確実に反映させる
• 問題発生時は accessor で迅速に失効（ユーザーのすべての子トークンを対象にできる）

よく使う運用コマンド

# 現在のトークン情報確認
vault token lookup

# 可能であればトークンを更新（TTL 延長）
vault token renew

# アクセサを用いた失効（事前に accessor を把握しておく）
vault token revoke -accessor <ACCESSOR_ID>

監査とトラブルシュート

Vault の監査デバイスを有効化しておけば、GitHub 認証のリクエスト・レスポンス（機密はハッシュ化）が追跡できます。失敗理由の特定や、誰にどのポリシーが付与されたかの検証に有用です。

よくある失敗は、チームスラッグの誤り、read:org スコープ不足、SAML/SSO 組織でトークンが組織で承認されていない、GitHub Enterprise の base_url 未設定、対象チームへの未所属などです。

• 監査有効化: vault audit enable file file_path=/var/log/vault_audit.log
• エラー時に確認: organization 設定、team マッピング、ポリシー名の誤記、トークンスコープ
• SSO 保護された組織では、トークンを組織に対して承認する必要がある

監査の最小設定例

sudo mkdir -p /var/log && sudo chown vault:vault /var/log
vault audit enable file file_path=/var/log/vault_audit.log

資格対策の要点（Associate）

試験では、設定の所在と原則が問われます。特に organization は auth/github/config に書く、チーム→ポリシーは auth/github/map/teams/<team-slug> に書く、ユーザーマッピングは例外対応という基本を外さないことが重要です。

また、1 つの GitHub 認証マウントは 1 組織に紐づく設計であり、複数組織はマウント分割で対処する点、GitHub Enterprise では base_url を API エンドポイント（/api/v3）まで含めて指定する点も頻出です。

• チーム所属が複数の場合、付与ポリシーは和集合
• read:org スコープがないとチーム検証に失敗し得る
• デフォルトポリシーは最小に、チームマッピング中心で最小権限を実現
• SSO 組織ではトークンの組織承認が必要になる場合がある

問題で確認

よくある質問