Vault Templated Policies 実務ガイド: Identityのentity/group情報を使って最小権限を徹底する

Templated Policiesは、ポリシー内でidentity情報を変数として参照し、リクエスト時に動的にパス解決する仕組みです。ユーザーごと・チームごとに個別のシークレット空間を切る最小権限設計を、少数のポリシーで表現できます。

本稿では、entityやgroupに紐づく情報をどのようにテンプレート展開へ使うか、評価順序と落とし穴、実務的な設定手順、試験で押さえるべき要点を扱います。

Templated Policiesの基本と試験ポイント

VaultのTemplated Policiesは、ACLポリシー内に{{...}}形式のプレースホルダを記述し、リクエストを実行するトークンに結び付くIdentityコンテキスト（entityやそのaliases、metadataなど）で置換する機能です。置換はサーバー側で行われ、マッチしたパスに対して通常のcapabilities判定が行われます。

実務では、ユーザー自身の名前や所属チームなどをパスに埋め込むことで、1本のポリシーを多人数に安全に適用できます。試験の観点では、どのidentityフィールドが使用できるか、トークンにentityが無い場合の挙動、deny優先、kv v2のパス（dataとmetadataの違い）といった基本を確実に押さえることが重要です。

• よく使うプレースホルダ: identity.entity.name、identity.entity.id、identity.entity.metadata.<key>、identity.entity.aliases.<mount_accessor>.name
• 展開は要求トークンのentityに基づく（ポリシーを付与したgroup自体の名前を直接パス展開に使うのではない）
• トークンにentityがない場合は多くのテンプレートが空になるため、パスが一致せず結果的にdenyになる
• denyはallowより常に優先。広いallowと狭いdenyが重なるとdenyが勝つ
• kv v2では読み書きはkv/data/、listはkv/metadata/を使う

最小例: ユーザー自身の領域のみ許可（kv v2）

path "kv/data/users/{{identity.entity.name}}/*" {
  capabilities = ["create", "update", "read", "delete"]
}

# list用（kv v2のメタデータパス）
path "kv/metadata/users/{{identity.entity.name}}/*" {
  capabilities = ["list"]
}

静的ACL vs Templated Policies vs ポリシーエンジンの使い分け

同じ最小権限でも、単純な静的ACLを大量に作る、テンプレートで集約する、外部の高度なポリシーエンジン（例: Sentinel）で制御する、といった選択肢があります。運用規模・動的性・審査要件に応じて選びます。

Associate/Ops試験では、まずACLとTemplated Policiesの使い分けを理解していれば十分です。Sentinelの詳細は上位資格やEnterprise機能の文脈で問われます。

• 小・中規模: Templated Policiesで十分なことが多い
• 大規模・高度な条件分岐: Sentinelなどのポリシーエンジンを検討
• 変更頻度が高い属性（チーム名など）はentity.metadataで吸収してテンプレート展開に活用

評価の流れ: entity解決からパス照合、capabilities判定まで

テンプレートは、要求トークンに紐づくentityコンテキストで都度展開されます。展開後の文字列パスに対して通常のACLマッチングが行われ、最終的なcapabilitiesが決まります（deny優先）。

groupは、誰にポリシーを付けるかをコントロールする単位です。グループ名そのものをパスに差し込むのではなく、グループに所属する各entityの属性（例: entity.metadata.team）でテンプレートを解決させるのが基本です。

• entity解決は認証（login）時に作られるエンティティとエイリアスに依存
• aliases.<mount_accessor>.name で認証メソッド側のユーザー名を参照可能
• metadataが未設定だとパス不一致となり結果denyになるため、初期化や入社フローでmetadata設定を自動化する
• kv v2のlistはmetadataパス、read/writeはdataパスで評価される

テンプレート展開と評価の概念図

エイリアス（認証メソッドのユーザー名）で展開する例

# userpassのアクセサを環境変数に保持した想定
# 例: ACCESSOR=auth_userpass_12345678

path "kv/data/users/{{identity.entity.aliases.${ACCESSOR}.name}}/*" {
  capabilities = ["create", "update", "read", "delete"]
}

path "kv/metadata/users/{{identity.entity.aliases.${ACCESSOR}.name}}/*" {
  capabilities = ["list"]
}

ユースケース集: ユーザー領域、チーム領域、エイリアス名ベース

個人領域の切り出しは最もよくあるパターンです。entity.nameは自動生成名になる場合があるため、認証メソッド側のユーザー名で安定させたい場合はaliases.<mount_accessor>.nameを使います。

チーム単位の領域は、entity.metadata.teamのような属性で分岐します。チーム変更時はmetadataを更新するだけで権限が自動的に移るため、ポリシーの再配布が不要です。

• 個人領域: kv/data/users/{{identity.entity.aliases.<accessor>.name}}/*
• チーム領域: kv/data/teams/{{identity.entity.metadata.team}}/*
• 読み取り専用やlist専用の補助スタンザを忘れない（kv v2はlist=metadata）

HCL例: 個人領域とチーム領域を1本で表現

# 個人領域（ユーザー名）
path "kv/data/users/{{identity.entity.aliases.${ACCESSOR}.name}}/*" {
  capabilities = ["create", "update", "read", "delete"]
}
path "kv/metadata/users/{{identity.entity.aliases.${ACCESSOR}.name}}/*" {
  capabilities = ["list"]
}

# チーム領域（entity.metadata.team）。teamが未設定なら一致せずdeny
path "kv/data/teams/{{identity.entity.metadata.team}}/*" {
  capabilities = ["read", "list"]
}
path "kv/metadata/teams/{{identity.entity.metadata.team}}/*" {
  capabilities = ["list"]
}

構成手順: kv v2 + userpass + groupでの実装

以下は、userpassを使ってログインしたユーザーに対し、ユーザー名ベースで個人領域を許可する最小構成例です。aliases.<mount_accessor>.nameを使うため、userpassのマウントアクセサを取得してテンプレートに固定します。

本番運用では、entityのmetadata初期化、groupへのポリシー付与、ユーザー加入・離脱フローの自動化を併せて設計します。

• アクセサはauth list -detailedで取得し、ポリシーファイル内にベタ書きまたは変数展開で埋め込む
• groupにポリシーを付与すれば、メンバー全員に同じテンプレートロジックが適用される
• list権限の抜け漏れでCLIの一覧が失敗しやすい点に注意

CLI一連コマンド例

# 1) kv v2を有効化
vault secrets enable -path=kv kv-v2

# 2) userpassを有効化し、ユーザー作成
auth_path=userpass
vault auth enable ${auth_path}
vault write auth/${auth_path}/users/alice password="S3cret!"

# 3) userpassのマウントアクセサ取得
ACCESSOR=$(vault auth list -format=json | jq -r '."'${auth_path}'/".accessor')
echo "ACCESSOR=${ACCESSOR}"

# 4) テンプレート化ポリシーを作成
cat > user-scoped.hcl <<EOF
path "kv/data/users/{{identity.entity.aliases.${ACCESSOR}.name}}/*" {
  capabilities = ["create", "update", "read", "delete"]
}
path "kv/metadata/users/{{identity.entity.aliases.${ACCESSOR}.name}}/*" {
  capabilities = ["list"]
}
EOF
vault policy write user-scoped user-scoped.hcl

# 5) Identity groupを作成し、ポリシー付与
gid=$(vault write -field=id identity/group name="ops" policies="user-scoped")
echo "GROUP_ID=${gid}"

# 6) aliceで一度ログインしてentityを自動作成
VAULT_TOKEN=$(vault login -method=${auth_path} -format=json username=alice password="S3cret!" | jq -r .auth.client_token)
ENTITY_ID=$(VAULT_TOKEN=$VAULT_TOKEN vault token lookup -format=json | jq -r .data.entity_id)
echo "ENTITY_ID=${ENTITY_ID}"

# 7) グループにaliceのentityを追加
vault write identity/group/id/${gid} member_entity_ids=${ENTITY_ID}

# 8) シークレット作成（管理者トークンで代入例）
vault kv put kv/users/alice/api key=abc123

# 9) aliceトークンでアクセス検証
VAULT_TOKEN=$VAULT_TOKEN vault kv get kv/users/alice/api   # 成功
VAULT_TOKEN=$VAULT_TOKEN vault kv get kv/users/bob/api     # 失敗（パス不一致）

運用の落とし穴とAssociate/Ops試験の押さえどころ

テンプレート展開は便利ですが、属性不足やパス種別の取り違えで意図せずdenyになることがあります。監査・メンテナンス観点も含めてチェックリスト化しておくと安全です。

試験では、deny優先、テンプレートに使えるidentityフィールド、listでのkv/metadataの必要性、エンティティが存在しない場合の挙動が頻出です。

• metadata未設定時はパス不一致になるため初期化フロー必須
• kv v2はlist=metadata、read/write=data。取り違えるとlistが失敗
• 認証メソッドを無効化・再作成するとaccessorが変わるため、aliases.<accessor>.nameを使うポリシーは要更新
• deny優先。広すぎるallowを作らない
• 監査ログでrequest.pathと最終capabilitiesを確認し、展開結果を間接的に検証する

監査ログでの確認例（抜粋イメージ）

# file auditデバイスを有効化している前提
# request.path が展開後の実パスにマッチしているかを確認
{
  "type": "request",
  "auth": {"entity_id": "...", "policies": ["user-scoped"]},
  "request": {"path": "kv/data/users/alice/api", "operation": "read"},
  "response": {"policy_results": {"allowed": true}}
}

問題で確認

よくある質問