Vault Identity 入門: Entities の管理と複数認証の統合（Associate 対応）

Vault の Identity は、異なる認証方法でログインする同一人物・同一アプリを 1 つの Entity として扱い、ポリシーやグループを一元管理する仕組みです。

Associate レベルで頻出の「mount accessor を使った alias 紐づけ」「ポリシーの合算」「グループの使い分け」を、確実に押さえます。

Entities / Aliases / Groups の基本

Vault では、実ユーザーやアプリケーションを Entity（実体）として表現し、各認証方法でのログイン名やアカウントを Alias（別名）で関連付けます。ユーザーが OIDC と GitHub の両方でログインしても、同じ Entity に結び付ければポリシーは一元化できます。

Alias は認証メソッドのパスではなく mount accessor（内部識別子）で結び付けます。これにより auth/ パス名を変更しても Alias は壊れません。Group はポリシーの付け所であり、Entity をメンバーに含めることで権限の継承を構成します（内部グループと外部グループの 2 種類）。

認可は、トークン発行時に認証メソッド由来のトークンポリシーと、Entity/Group に割り当てた Identity ポリシーが合算（ユニオン）されて決まります。すでに発行済みのトークンには、原則として後からのグループ変更は即時反映されません。

• Entity = 同一人物/アプリの中核 ID（安定した canonical_id）
• Alias = 認証メソッドごとのログイン名を Entity に結び付けるレコード（mount accessor を使用）
• Group = ポリシーの束。Entity をメンバーに入れて権限を付与（内部/外部グループ）
• 最終ポリシー = トークンポリシー ∪ Identity ポリシー（Entity と Group 由来）

設計指針: 複数認証を 1 Entity に統合する考え方

現場では、Entity 名に安定した業務識別子（例: 社内メール、従業員 ID）を採用し、Alias 側は各認証メソッドでの自然なユーザー名やクレームを使うのが実装・運用ともに扱いやすい方針です。

OIDC では sub（推奨）や email、LDAP では DN や sAMAccountName、Kubernetes では service account 名や JWT のクレームを alias name に使います。GitHub はユーザー名、userpass は Vault 内ユーザー名がそのまま alias になります。パス変更やローテーションが見込まれる場合でも、Alias は accessor を参照するため壊れません。

• Entity 名は人/アプリが変わらない限り不変にできる識別子を選定
• Alias 名は各認証メソッドの「そのままの」安定フィールドを使う
• 認証メソッドのパス変更は accessor に依存する設計で吸収
• ポリシーは Entity/Group に集約し、認証メソッド個別のポリシーは最小限に抑制

手順: 異なる認証方法のアカウントを 1 つの Entity に統合

以下は、userpass と GitHub と OIDC の 3 つの認証で同一人物を 1 つの Entity に統合する最小構成の例です。要点は「先に Entity を作る」「各認証メソッドの mount accessor を取得する」「identity/entity-alias を accessor と canonical_id（= Entity ID）で作成する」の 3 ステップです。

mount のパスを変えても accessor は不変なので Alias は壊れません。ただし mount を無効化して再作成した場合は accessor が変わるため、Alias を作り直す必要があります。

• Entity 作成 → ID（canonical_id）を控える
• vault auth list で各認証メソッドの accessor を取得
• identity/entity-alias を name + accessor + canonical_id で作成
• vault login 後に Entity 解決を確認（identity/entity/id/<id> 参照）

CLI 例: Entity と Aliases の作成

### 1) Entity を作成
vault write -format=json identity/entity name="[email protected]" metadata=team=platform \
  | jq -r '.data.id' > entity_id.txt

### 2) 各認証メソッドの mount accessor を取得
vault auth list -format=json | jq -r 'to_entries[] | "\(.key) \(.value.accessor)"'
# 例:
# userpass/ auth_userpass_abcde
# github/   auth_github_fghij
# oidc/     auth_oidc_klmno

USERPASS_ACC=$(vault auth list -format=json | jq -r '."userpass/".accessor')
GITHUB_ACC=$(vault auth list -format=json | jq -r '."github/".accessor')
OIDC_ACC=$(vault auth list -format=json | jq -r '."oidc/".accessor')
CID=$(cat entity_id.txt)

### 3) Alias を作成（name は各メソッドのユーザー識別子）
# userpass のユーザー taro に対応
vault write identity/entity-alias name="taro" canonical_id="$CID" mount_accessor="$USERPASS_ACC"
# GitHub のユーザー名 taro-gh に対応
vault write identity/entity-alias name="taro-gh" canonical_id="$CID" mount_accessor="$GITHUB_ACC"
# OIDC の sub（例）に対応
vault write identity/entity-alias name="00u123abcXYZ" canonical_id="$CID" mount_accessor="$OIDC_ACC"

### 4) 確認
vault read identity/entity/id/$CID
# aliases[].mount_accessor と aliases[].name が作成できていることを確認

ポリシー統合とグループ設計

Entity に直接ポリシーを紐づける方法と、Group にポリシーを付与して Entity をメンバーに含める方法があります。スケールする運用では、Group 中心にポリシーを管理し、オンボーディング/チーム異動/権限変更は Group メンバー編集で吸収します。

認可時は、認証メソッド由来のトークンポリシーと Identity 側（Entity/Group）ポリシーが合算されます。グループ変更の反映は新規に発行されるトークンから有効になる運用が一般的です。

• 内部グループ: Vault 内で定義する静的グループ。チームや職務ロールに対応
• 外部グループ: OIDC/LDAP のグループ名を group-alias で取り込む。IdP 側の変更を連動させやすい
• 最終権限はユニオン。deny は Sentinel/名前空間設計など別機構で扱う
• 既発行トークンは基本的にポリシー固定。変更は再ログイン/再発行で反映

複数認証 → Entity → Group → ポリシーの流れ

運用: パス変更・重複統合・退職時の扱い

認証メソッドのパス変更（例: auth/oidc → auth/idp）は accessor 非依存のため Alias は維持されます。無効化して再作成した場合は accessor が変わるため、Alias の作り直しが必要です。

人事異動やアカウント重複時は、意図せず 2 つの Entity ができることがあります。identity/entity/merge API で統合し、古い Entity の Alias を集約します。退職・離任時は、まず認証メソッド側の資格情報を無効化し、対応する Alias を削除、最後に Entity を削除する順序が安全です。

• パス変更: sys/auth でパスを調整しても Alias は accessor 基準で存続
• 再構築: mount 再作成で accessor 変更→ Alias を再作成
• 重複統合: identity/entity/merge を使用（ポリシー/グループは統合先に集約）
• 退職対応: 認証資格の停止 → Alias 削除 → Entity 削除の順で実施
• 監査: audit デバイスで entity_id を記録。トレーサビリティを担保

CLI 例: Entity の重複を統合する

# 既存の 2 つの Entity（source_id, target_id）を統合
vault write identity/entity/merge \
  from_entity_id="11111111-1111-1111-1111-111111111111" \
  to_entity_id="22222222-2222-2222-2222-222222222222"
# 統合後、from 側の aliases は to 側に移り、from は無効化される想定（ドライランは不可のため事前にバックアップ推奨）

Associate 試験対策: よく聞かれるポイント

Identity の基本語彙（Entity/Alias/Group）と、Alias が mount accessor で紐づく点は頻出です。パス名ではないこと、ポリシーはユニオンで決まること、グループは内部/外部があることを短時間で説明できるようにしましょう。

CLI/HTTP の最低限の作法（identity/entity, identity/entity-alias, identity/group, identity/group-alias）と、auth list で accessor を取得する流れを押さえれば、実務でも試験でも役立ちます。

• Alias 作成に必要なのは canonical_id（= Entity ID）と mount_accessor と name
• mount のパス変更は Alias に影響しない。再作成で accessor が変わる点は注意
• 最終ポリシーはユニオン。既存トークンは基本的に後追い反映されない
• Group はポリシーの付け所。外部グループは IdP 名称を group-alias で取り込む
• API パス: identity/entity, identity/entity-alias, identity/group, identity/group-alias

問題で確認

よくある質問