Vault Identity システム: Entity と Alias を正しく設計・運用する

Vault の認証は「トークンを得る」行為ですが、長期的な権限管理や監査の単位は Identity (Entity) です。複数の認証メソッドを横断して同一人物/同一アプリをひも付けるのが Entity と、その橋渡しをするのが Entity Alias です。

本稿では、試験で問われやすい定義や流れをおさえつつ、運用でつまずきやすいポイント（エイリアスのスコープ、アクセッサの扱い、グループ設計、重複 Entity の統合）を具体的なコマンドとともに解説します。

Identity と Entity/Alias の基本

Vault の Identity ストアは、認証メソッドごとに発行されるトークンを、単一の「正規の主体 (Entity)」へ集約します。Entity は Vault 内で一意に識別される ID を持ち、監査やポリシー適用の基準点になります。

Entity Alias は、特定の認証メソッドから見える「ローカルな識別子（例: userpass の username、OIDC の sub など）」を、どの Entity に対応付けるかを定義します。エイリアスは認証メソッド単位（mount）でスコープが分かれており、各エイリアスは mount accessor と name の組み合わせで一意です。

• Entity は Vault 内で不変の ID（canonical entity ID）を持つ。ログイン手段が変わっても同一主体であれば同一 Entity に集約する。
• Entity Alias は認証メソッドの mount accessor と name をキーにして Entity にマッピングする。
• 同一人物が複数の認証メソッドを使う場合は、同じ Entity に複数の Alias をぶら下げるのが基本設計。
• ポリシーはトークン由来のものと Identity（主にグループ、必要に応じて Entity 自体）由来のものがマージされ、最終的な権限になる。

基本の作成・参照コマンド

## Entity 作成
ENTITY_ID=$(vault write -format=json identity/entity name="alice" | jq -r .data.id)
echo $ENTITY_ID

## 認証メソッドの accessor を取得（例: userpass）
UP_ACCESSOR=$(vault auth list -format=json | jq -r '."userpass/".accessor')
echo $UP_ACCESSOR

## Entity Alias 作成（userpass の alice を Entity に結びつけ）
vault write identity/entity-alias \
  name="alice" \
  canonical_entity_id="$ENTITY_ID" \
  mount_accessor="$UP_ACCESSOR"

## Entity の参照
vault read identity/entity/id/$ENTITY_ID

認証からポリシー適用までの流れ

クライアントは任意の認証メソッドでログインし、トークンを取得します。Vault はそのトークンが属する認証メソッドとローカル ID（例: username, sub 等）を基に Entity Alias を検索し、対応する Entity を特定します。見つからない場合は初回ログインで alias を自動作成するメソッドもあります（例: OIDC/JWT のロール設定次第）。

最終的な権限は、トークンに直接付与されたポリシーと、Identity 側（Entity 自体や所属 Group）に付与されたポリシーの和集合です。Vault のポリシーは許可型であり、明示的な deny の競合は発生しません。複数経路で同一能力が与えられた場合は単純に統合されます。

• 認証メソッドごとに mount accessor が異なるため、Alias は accessor を必須にする。
• OIDC/JWT のエイリアス名はデフォルトで sub。ロールの user_claim を設定すると別 claim をエイリアス名にできる。
• ポリシー解決は「トークン由来」+「Identity 由来（主に Group）」の合算。

認証から Entity ひも付け、ポリシー解決まで

トークンから Entity を確認する

## 現在のトークンにひもづく Entity ID を確認
vault token lookup | grep entity_id

## JSON で確認
vault token lookup -format=json | jq -r .data.entity_id

エイリアス設計パターン（複数認証・外部IdP対応）

同一ユーザーが userpass と OIDC を併用する、あるいはアプリケーションが AppRole と Kubernetes を切り替える、といった状況は珍しくありません。鍵は「各メソッドで現れるローカル ID（エイリアス名）が何か」を正しく理解し、適切な mount accessor と組み合わせて既存の Entity に結びつけることです。

代表的なルールとして、userpass/ldap は username、OIDC/JWT はデフォルト sub（ロールで user_claim を変更可）、AppRole は role_id がエイリアス名になります。メソッドのパスを変更（再有効化や mount 先変更）すると accessor も変わるため、エイリアス再作成が必要です。

• 人とサービスを分ける。人は OIDC/LDAP など外部IdPと紐付け、サービスは AppRole/Kubernetes を使い、別の Entity にする。
• 初回は明示的に Entity を作ってから各メソッドの Alias を作ると、誤紐付けを防げる。
• OIDC ロールの user_claim を email にするなら、Alias の name は email と一致させる必要がある。

複数メソッドを同一 Entity に集約する例

## 既存 Entity（alice）に OIDC のエイリアスを追加する
ENTITY_ID=...  # 既知の Entity ID
OIDC_ACCESSOR=$(vault auth list -format=json | jq -r '."oidc/".accessor')

## OIDC ロールの user_claim が "email" なら、name はユーザーの email にする
vault write identity/entity-alias \
  name="[email protected]" \
  canonical_entity_id="$ENTITY_ID" \
  mount_accessor="$OIDC_ACCESSOR"

ポリシー解決とグループ設計

実務ではポリシーはグループに集約し、Entity はグループのメンバーとして扱うのが管理しやすい設計です。外部IdP（OIDC/LDAP 等）から来るグループを Vault の Group Alias で対応付け、必要に応じて内部グループと組み合わせます。

最終的な権限は、(1) トークン発行時に付与されたポリシー、(2) Entity に直接付与されたポリシー（必要な場合）、(3) 所属グループに付与されたポリシーの和集合です。試験では、この合算モデルとグループ中心設計が問われやすい点に注意してください。

• グループは内部（Vault 管理）と外部（Group Alias で外部グループに対応）の二系統を組み合わせられる。
• ロールベース設計では、業務ロール = グループ、環境/アプリ単位の細分化 = サブグループで表現するとスケールしやすい。
• 個別例外は Entity 直付けのポリシーで最小限にする（積み上がりは定期棚卸し）。

グループとグループエイリアスの設定例

## 内部グループ作成 + ポリシー付与
GROUP_ID=$(vault write -format=json identity/group name="devs" policies="dev-read,kv-common" | jq -r .data.id)

## 既存 Entity をメンバーに追加
vault write identity/group/id/$GROUP_ID member_entity_ids="$ENTITY_ID"

## OIDC の groups クレーム "devs" をこのグループに結びつける
OIDC_ACCESSOR=$(vault auth list -format=json | jq -r '."oidc/".accessor')
vault write identity/group-alias \
  name="devs" \
  canonical_group_id="$GROUP_ID" \
  mount_accessor="$OIDC_ACCESSOR"

既存ユーザー統合と移行の手順（重複 Entity の解消）

認証メソッドの追加やパス変更、初期運用の誤りで同一人物に複数の Entity ができてしまうことがあります。安全な解消手順は「正とする Entity を決め、各認証メソッドのエイリアスをその Entity に付け替える」ことです。重複側の Entity は無効化しておけば、監査ログを保持しつつ新規ひも付けを防げます。

注意点は accessor の取り扱いと、エイリアス名（ローカル ID）の正確性です。OIDC で user_claim を変更している場合、想定と異なる値がエイリアス名になることがあります。移行時は必ずロール設定と実ユーザーのクレームを突き合わせて確認します。

• 正とする Entity を 1 つ決める（ID を控える）。
• 各メソッドの accessor を取得し、正しい name でエイリアスを再作成する。
• 重複側の Entity は disabled=true にし、誤紐付けを防止する。

安全な統合（付け替え）の一例

## 付け替え先（正）の Entity ID
PRIMARY_ENTITY_ID=...

## 認証メソッドの accessor を確認
vault auth list -detailed

## 既存の Entity Alias を列挙して確認
vault list identity/entity-alias/id | sed '1d' | while read ID; do
  vault read -format=json identity/entity-alias/id/$ID | jq '{id:.data.id, name:.data.name, mount_accessor:.data.mount_accessor, entity_id:.data.canonical_entity_id}';
done

## 誤った Entity に向いている Alias を削除して作り直す
BAD_ALIAS_ID=...
vault delete identity/entity-alias/id/$BAD_ALIAS_ID

## 正しい Entity に向けて再作成（例: userpass の alice）
UP_ACCESSOR=$(vault auth list -format=json | jq -r '."userpass/".accessor')
vault write identity/entity-alias \
  name="alice" \
  canonical_entity_id="$PRIMARY_ENTITY_ID" \
  mount_accessor="$UP_ACCESSOR"

## 重複 Entity を無効化
DUP_ENTITY_ID=...
vault write identity/entity/id/$DUP_ENTITY_ID disabled=true

トラブルシュートと検証コマンド

最初に確認すべきは「トークンがどの Entity に結びついているか」「その Entity/Group にどのポリシーがあるか」です。エイリアスの accessor ミスや、OIDC の user_claim 想定違いが典型的な原因です。

エイリアス名の重複は同一 mount 内で許されません。認証メソッドのパス変更で accessor が変わった場合、古いエイリアスは無効にならないため、明示的な削除/再作成が必要です。

• entity_id が空の場合は Alias 未作成/未解決。ロール設定や自動エイリアス作成の可否を確認。
• capabilities の差異はトークン由来ポリシーと Identity 由来ポリシーの両面を洗う。
• LDAP/OIDC は外部側の属性値も併せて検証する（実ユーザーのクレーム値を確認）。

よく使う検証コマンド

## トークンの Entity と有効ポリシー
vault token lookup | egrep 'entity_id|policies'

## パスに対する権限確認（現在のトークン）
vault token capabilities secret/data/app/*

## 認証メソッドと accessor 一覧
vault auth list -detailed

## Entity 一覧と個別詳細
vault list identity/entity/id
vault read identity/entity/id/<ENTITY_ID>

## エイリアスの検索（ID は list で取得）
vault list identity/entity-alias/id
vault read identity/entity-alias/id/<ALIAS_ID>

問題で確認

よくある質問