Vault Policies (HCL): パスとCapabilityで制御

Vaultのアクセス制御は「どのパスに」「どのCapabilityを付与するか」で決まります。設計を外すと想定外の権限が広がるか、逆に動かないかのどちらかです。

本稿は、安定仕様に基づくパス設計とCapabilityの割り当て、ワイルドカードやKV v2特有の注意点を、実務とAssociate試験の両面から整理します。

ポリシーの基本と評価順序

VaultのポリシーはHCLで記述し、pathブロックごとにcapabilitiesを定義します。リクエスト時は、トークンにアタッチされた全ポリシーのうち、該当パスにマッチするものを集約して評価します。明示的にdenyが含まれる場合は常に拒否され、どのポリシーにもマッチしなければデフォルト拒否です。

Associate試験では、capabilitiesの意味、denyの優先、sys/系操作にsudoが必要になる場面、KV v2のパス差異が頻出です。具体的なエンジンやAPIのパスを念頭に置いてポリシーを書くことが重要です。

• デフォルトは拒否。明示的に許可が必要
• 一致する複数ポリシーはcapabilitiesを集合的に評価
• denyが1つでも含まれれば拒否が優先
• sudoは特権的なsys/操作で要求されることがある

ポリシー評価の流れ（概念）

パスとCapabilityの対応関係を正しく押さえる

capabilitiesは操作の種類を表します。書き込み系は現場ではcreateとupdateをまとめて付与するのが一般的です。listはエンジン側がLIST操作を提供しているパスでのみ機能します。

HTTPメソッドとの対応は実装依存の部分もありますが、Associateレベルでは下表を押さえておけば実務・試験ともに困りません。

• readは読み取り、listは一覧操作（エンジンが対応していれば）
• create/updateは書き込み系。新規と更新を分ける実装もあるため両方付けるのが安全
• deleteは削除系APIに必要。エンジンごとの具体パスに注意
• sudoは通常のシークレット操作では不要。主にsys/配下で要求される

ワイルドカードとsys/エンドポイントの注意点

pathブロックは完全一致に加え、一般的なワイルドカードで前方一致などを記述できます。広すぎるワイルドカードは権限過多の原因になるため、可能な限りプレフィックスを限定してください。

sys/配下はシステム管理用エンドポイントです。マウントやポリシー管理、ヘルスチェックなどはここにあります。多くの操作は管理トークンかsudoが必要で、業務アプリ用トークンに付与すべきではありません。

• ワイルドカードは便利だが範囲を狭めること
• アプリ用ポリシーにsys/を含めないのが原則
• 必要最小限のパスにのみcapabilitiesを付与する

複数ポリシーの合成とdeny優先の実務知識

トークンに複数のポリシーがアタッチされる場合、同一リクエストに対して複数のpathブロックがマッチします。このときcapabilitiesは集合として評価され、1つでもdenyが含まれていれば拒否されます。マッチするものが1つもなければ拒否です。

ポリシー間の『より具体的なパスが優先』といった自動的な優先度はなく、結果的に必要なcapabilityが集合に含まれているかどうかで決まります。精緻な制御が必要なら、明示的なdenyの併用やパスの粒度調整で設計してください。

• 複数の許可は和集合で評価
• denyは常に優先される
• 自動の詳細度優先はないため、設計で明確に切り分ける

KV v1/v2の違いとパス設計の実務ポイント

KVシークレットエンジンはv1とv2でAPIパスが異なります。v2ではバージョン管理のため、データは data/ 配下、一覧は metadata/ 配下に分かれています。試験・実務ともに、listを許可する際にdata/へlistを付けてしまう誤りが多発します。

以下は、アプリケーションがsecretというマウントパスのKV v2で、app/ プレフィックス配下の読み書きと一覧、削除を行える最小構成の例です。

• v2の読み書きは secret/data/... に対してread, create, update
• v2の一覧は secret/metadata/... に対してlist
• 削除系は用途に応じてdeleteを付与（論理削除）。破壊的操作の付与は慎重に

KV v2向けHCLポリシー例（パスとCapabilityの最小構成）

# app-kv2.hcl
# マウントパス: secret（KV v2）

# 読み取り・書き込み・削除：data配下
path "secret/data/app/*" {
  capabilities = ["create", "update", "read", "delete"]
}

# 一覧：metadata配下（dataではなくこちらにlistを付与）
path "secret/metadata/app/*" {
  capabilities = ["list"]
}

# 運用ヒント:
# - アプリ用ポリシーにsys/配下は含めない
# - ワイルドカードの範囲は最小化する

# 適用コマンド例
# vault policy write app app-kv2.hcl
# トークンにポリシーをアタッチして発行
# vault token create -policy=app

# 動作確認（カレントトークンでcapabilitiesを見る）
# vault token capabilities secret/data/app/foo
# vault token capabilities secret/metadata/app/

検証とトラブルシュート、Associate試験の着眼点

ポリシーは書いて終わりではありません。トークンに付与後、vault token capabilities で対象パスの権限を必ず確認します。CLIのkvサブコマンドはKV v2のパス差異を吸収してくれますが、ポリシーはRESTの実パスに対して評価される点を忘れないでください。

試験では、パスの取り違え（特にv2のmetadata/list）、writeというcapabilityは存在しない、denyが優先、sudoはsys/系でのみ使う、といった基本が問われます。選択肢に『secret/data/ にlist』が紛れていたら疑ってかかるのが鉄則です。

• vault token capabilities [TOKEN省略可] <path> で確認
• 動かない時は、パスの綴り・マウント名・v1/v2差異を再確認
• 不要なワイルドカードとsudoの付与は避ける

問題で確認

よくある質問