Vault Identity System: Designing and Operating Entities and Aliases

Authentication in Vault is the act of obtaining a token, but the long-term unit for permission management and auditing is the Identity (Entity). Entities tie the same person or application across multiple auth methods together, and Entity Aliases are the bridges that make that mapping work.

This article covers the definitions and flow most likely to appear on the exam, plus the operational gotchas that trip people up — alias scope, accessor handling, group design, and merging duplicate Entities — with concrete commands.

Identity, Entity, and Alias Basics

Vault's Identity store consolidates tokens issued by each auth method into a single canonical principal — the Entity. An Entity has a unique ID within Vault and serves as the anchor for auditing and policy application.

An Entity Alias defines how a local identifier as seen by a specific auth method (e.g., the username for userpass, the sub claim for OIDC) maps to a given Entity. Aliases are scoped per auth method mount, and each alias is uniquely identified by the combination of mount accessor and name.

• An Entity holds an immutable ID (the canonical entity ID) within Vault. Even when the login method changes, the same principal is consolidated into the same Entity.
• An Entity Alias maps to an Entity using the auth method's mount accessor and name as the key.
• When the same person uses multiple auth methods, the standard design is to attach multiple Aliases to the same Entity.
• Final permissions are the merge of token-bound policies and Identity-bound policies (primarily groups, and the Entity itself when needed).

Basic creation and read commands

## 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

From Authentication to Policy Evaluation

A client logs in via any auth method and receives a token. Vault then looks up the Entity Alias using that token's auth method and local ID (such as username or sub) to find the corresponding Entity. If none is found, some methods will auto-create an alias on first login (for example, depending on OIDC/JWT role configuration).

Final permissions are the union of policies attached directly to the token and policies attached on the Identity side (the Entity itself and the Groups it belongs to). Vault policies are allow-only, so there is no explicit-deny conflict to worry about. When the same capability is granted via multiple paths, the grants simply merge.

• Each auth method has a distinct mount accessor, so every Alias must specify an accessor.
• For OIDC/JWT the alias name defaults to sub. Setting the role's user_claim lets you use a different claim as the alias name.
• Policy resolution sums token-bound policies and Identity-bound policies (primarily from Groups).

From authentication, to Entity binding, to policy resolution

Inspecting the Entity behind a token

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

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

Alias Design Patterns (Multi-Method and External IdP)

It's common for the same user to use both userpass and OIDC, or for an application to alternate between AppRole and Kubernetes auth. The key is to know exactly what local ID (alias name) each method exposes, and to bind it to the existing Entity using the right mount accessor.

As a rule of thumb: userpass/ldap uses the username; OIDC/JWT defaults to sub (you can override via the role's user_claim); AppRole uses the role_id as the alias name. If you change the method's path (by re-enabling it or moving the mount), the accessor also changes — so you must recreate the alias.

• Separate people from services. Tie people to external IdPs like OIDC/LDAP, use AppRole/Kubernetes for services, and keep them as distinct Entities.
• On first setup, explicitly create the Entity and then create the per-method Aliases — this avoids accidental mis-binding.
• If you set the OIDC role's user_claim to email, the Alias name must match the email exactly.

Example: consolidating multiple methods into a single 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"

Policy Resolution and Group Design

In practice, the most maintainable design is to consolidate policies on groups and treat Entities as group members. Map groups coming from external IdPs (OIDC/LDAP and the like) using Vault Group Aliases, and combine them with internal groups as needed.

Final permissions are the union of (1) policies attached when the token was issued, (2) policies attached directly to the Entity (when used), and (3) policies attached to the groups the Entity belongs to. The exam frequently tests this additive model and the group-centric design — keep them in mind.

• Groups come in two flavors — internal (Vault-managed) and external (mapped to external groups via Group Alias) — and you can combine them.
• For role-based design, modeling business roles as groups and per-environment/per-app slicing as subgroups scales well.
• Keep individual exceptions on direct-Entity policies to a minimum, and review the accumulation periodically.

Example: configuring a group and a group alias

## 内部グループ作成 + ポリシー付与
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"

Consolidating Existing Users and Migration (Resolving Duplicate Entities)

Adding new auth methods, changing paths, or early operational mistakes can leave a single person with multiple Entities. The safe resolution is to pick a canonical Entity and re-point every auth method's alias at it. Disable the duplicate Entity afterwards — that preserves the audit log while blocking new bindings.

The pitfalls are accessor handling and the accuracy of the alias name (local ID). If the OIDC user_claim has been changed, the alias name can end up being a value you didn't expect. During migration, always cross-check the role configuration against the actual user's claims.

• Pick one canonical Entity and write down its ID.
• Get each method's accessor and recreate the alias with the correct name.
• Set the duplicate Entity to disabled=true to prevent accidental rebinding.

A safe example of consolidation (rebinding aliases)

## 付け替え先（正）の 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

Troubleshooting and Verification Commands

Start by asking two questions: which Entity is the token bound to, and which policies are attached to that Entity and its Groups? The typical culprits are a wrong alias accessor or a mismatch between the assumed OIDC user_claim and reality.

Duplicate alias names within the same mount are not allowed. When changing an auth method's path changes the accessor, the old aliases are not invalidated — you have to delete and recreate them explicitly.

• An empty entity_id means the Alias hasn't been created or resolved. Check the role configuration and whether auto-alias creation is enabled.
• When capabilities differ from expectations, audit both token-bound and Identity-bound policies.
• For LDAP/OIDC, also verify the attribute values on the external side (look at the actual user's claim values).

Verification commands you'll use most often

## トークンの 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>

Check Your Understanding

Frequently Asked Questions