Vault Groups の管理: 内部グループと外部グループの使い分け

Vault の認証は auth メソッド単位ですが、認可は最終的に Identity の Entity/Group に集約されます。特に Groups はポリシーの付与点として中心的で、内部グループと外部グループの正しい使い分けが運用の安定性を左右します。

本稿は公式ドキュメントに基づき、内部グループ (type=internal) と外部グループ (type=external) の差分、group-alias を使った外部IdPグループの取り込み、評価フローと落とし穴を、資格対策の観点も交えて整理します。

Vault Identity と Groups の基本

Vault Identity は、認証メソッドごとのログイン情報を Entity (人やアプリの実体) に束ね、Aliases で結びつけます。アクセス許可は、Entity と Groups に付与されたポリシーの合算で決まります。

Groups には内部グループ (type=internal) と外部グループ (type=external) の2種があります。内部グループはVault内でメンバー管理する通常のグループ、外部グループはIdP等の外部グループをVaultに対応付ける読み取り主体のグループです。外部グループは group-alias により、外部のグループ名と auth メソッドの mount_accessor を Vault グループにマッピングします。

• Entity: ユーザー/マシンの同一性。複数の auth メソッドからのログインを統合。
• Entity Alias: auth メソッド固有の ID を Entity へ結合。
• Group: ポリシー付与の単位。入れ子可。
• Group Alias: 外部のグループ名 + mount_accessor を Vault の Group に結合。

主な API/CLI パス（抜粋）

identity/group               # グループの作成/更新/参照
identity/group/id/<id>       # グループIDでの参照
identity/group-alias         # グループエイリアスの作成
identity/group-alias/id/<id> # グループエイリアスの参照
identity/entity              # エンティティの作成/参照

内部グループと外部グループの違い（比較表）

内部と外部の最大の違いはメンバー管理の所在です。内部はVaultで直接メンバーを保持、外部はIdP等の外部情報を group-alias によって解決します。どちらのグループにもポリシーを付与でき、評価時にはポリシーの合算がトークンに反映されます。

既存のIdPグループをそのまま使いたい場合は外部グループを作成し group-alias を張る、Vault内で細かいサブセットを作りたい場合は内部グループを使って入れ子化する、というのが基本的な選び方です。

• 試験観点: 外部グループは member_entity_ids を直接操作しない。
• 試験観点: group-alias は name と mount_accessor と canonical_id（グループID）の3点で一意に解決される。

作成コマンドの最小例

# 内部グループ
vault write identity/group name=app-dev type=internal policies=kv-read

# 外部グループ（IdPの engineers を取り込む土台）
vault write identity/group name=oidc-engineers type=external policies=kv-read

作成とエイリアスの紐付け手順（CLI/API）

実務では、まずグループ本体を作成し（内部または外部）、必要なポリシーを付与します。外部グループの場合は、auth メソッドの mount_accessor を取得し、IdP側のグループ名と Vault グループID（canonical_id）を用いて group-alias を作成します。

内部グループには必要に応じて Entity や子グループを直接追加できます。外部グループはメンバーを直接持たず、ログイン時に group-alias と IdP のクレームから所属が解決されます。

• auth メソッドの mount_accessor は vault auth list -format=json で取得。
• group-alias は name（IdPグループ名）・mount_accessor・canonical_id（VaultグループID）を一致させる。
• 外部グループにも policies を付与できる（許可の付与点として有効）。
• 内部グループは入れ子で権限を合成できる（member_group_ids）。
• 更新は可能な限りグループ単位で行い、Entity へ直接ポリシー付与は最小化する。

内部/外部グループと group-alias の具体例

# 1) 内部グループを作成しポリシー付与
vault write identity/group \
  name=app-dev \
  type=internal \
  policies=kv-read,transit-sign

# 2) 既存の Entity を内部グループへ追加（例: entity_id=1111-2222-3333）
vault write identity/group/id/<GROUP_ID_OF_app-dev> \
  member_entity_ids=1111-2222-3333

# 3) 外部グループを作成（ポリシーはここに付与）
vault write identity/group \
  name=oidc-engineers \
  type=external \
  policies=kv-read

# 4) mount_accessor を取得（OIDC を例示）
vault auth list -format=json | jq -r '."oidc/".accessor'
# 出力例: auth_oidc_AbCdEf

# 5) group-alias を作成（IdP 側のグループ名 engineers を Vault グループへ結合）
vault write identity/group-alias \
  name=engineers \
  mount_accessor=auth_oidc_AbCdEf \
  canonical_id=<GROUP_ID_OF_oidc-engineers>

# 6) HTTP API での alias 作成例（同等の操作）
curl -sS --header "X-Vault-Token: $VAULT_TOKEN" \
  --request POST \
  --data '{"name":"engineers","mount_accessor":"auth_oidc_AbCdEf","canonical_id":"<GROUP_ID>"}' \
  $VAULT_ADDR/v1/identity/group-alias

ログイン時の評価とポリシー継承（フロー図）

ユーザーが OIDC/LDAP/GitHub などでログインすると、Vault は Entity を解決し、関連する Entity のポリシーと、所属するグループ（内部・外部・入れ子を含む）に付与されたポリシーを合算してトークンに反映します。

外部グループの所属は group-alias と auth メソッドのクレーム（例: OIDC の groups クレーム）により決まり、ログイン毎に最新の所属が解決されます。内部グループは Vault 内設定に基づき常時有効です。

• グループのポリシーは合算（deny は ACL で優先される点に留意）。
• 入れ子（member_group_ids）は再帰的に展開される。
• トークン再発行・再ログインで外部グループの最新所属が反映される。

有効ポリシーの確認

# 現在のトークンに付与されたポリシー
vault token lookup | jq -r .data.policies[]

# Entity とグループの突き合わせ（Entity ID が分かっている場合）
vault read identity/entity/id/<ENTITY_ID> | sed -n '1,200p'

# 自身のパスに対する権限確認
vault write sys/capabilities-self path=secret/data/app

運用ベストプラクティスと落とし穴

外部グループはメンバーを直接編集しないのが鉄則です。所属はIdP側のグループ管理で行い、Vault では group-alias とポリシー付与に専念します。入れ子構成が必要なら、親は内部グループにして外部グループを子として取り込みます。

auth メソッドの再有効化やマウント変更で mount_accessor が変わると、既存の group-alias が一致しなくなります。移行時は新 accessor を参照する alias を追加・切替する計画を立ててください。

• ポリシーは可能な限りグループに付与し、Entity 直付けは例外に限定する。
• 外部グループ名変更は alias 側 name を更新（または新規作成）して追随する。
• OIDC の groups_claim、LDAP のグループ検索設定を明示的に確認し、期待するグループ名がクレームに出ているかを検証する。
• 入れ子はシンプルに。深いネストはトラブルシュートを難しくする。
• 変更はステージング環境で token lookup と capabilities-self で検証してから本番適用する。

メンテ系コマンド例

# 既存グループの一覧/参照
vault list identity/group/id
vault read identity/group/id/<GROUP_ID>

# グループのポリシー更新
vault write identity/group/id/<GROUP_ID> policies=kv-read,sys-audit

# グループエイリアスの一覧/参照
vault list identity/group-alias/id
vault read identity/group-alias/id/<ALIAS_ID>

トラブルシューティングと移行の注意

ログインしても外部グループ由来の権限が付与されない場合、まず group-alias の name と mount_accessor が正しいか、IdP 側のクレームに期待するグループ名が含まれているかを確認します。OIDC なら role の groups_claim 設定が鍵です。

auth メソッドの再作成・パス変更で accessor が変わると、既存の group-alias は一致しなくなります。新 accessor で alias を再作成するか更新してください。移行期間中は一時的に旧新両方の alias を並行させることで影響軽減が可能です。

LDAP ではサーバ設定や検索フィルタにより、取得できるグループ名やネスト解決が異なります。まず ldap/ 配下の設定と実際のクエリ結果を突き合わせ、Vault に届いているグループ名が alias の name と一致しているかを検証します。

• チェック順序: auth 設定 → mount_accessor → IdP クレーム → group-alias → グループの policies。
• 問題の切り分けには capabilities-self と token lookup を併用する。
• パス変更やロール名変更は影響範囲が広い。事前にエクスポートとロールバック手順を用意する。

確認チェックコマンド

# auth メソッドと accessor の確認
vault auth list
vault auth list -format=json | jq

# group-alias の詳細（name, mount_accessor, canonical_id を確認）
vault read identity/group-alias/id/<ALIAS_ID>

# OIDC ロールのグループクレーム設定の確認
vault read auth/oidc/role/<ROLE_NAME>

問題で確認

よくある質問