Vault Identity Guide: Managing Entities and Unifying Multiple Auth Methods

Vault Identity is the mechanism that treats the same person or application logging in via different auth methods as a single Entity, centralizing policy and group management.

We cover the topics that frequently appear at the Associate level: binding aliases via the mount accessor, how policies are unioned, and when to use which type of group.

Entities, Aliases, and Groups: The Basics

In Vault, real users and applications are represented as Entities, while their login names or accounts on each auth method are linked through Aliases. Even if a user signs in via both OIDC and GitHub, you can keep their policies unified by binding both logins to the same Entity.

Aliases are bound by the mount accessor (an internal identifier), not by the auth method's path, so renaming the auth/ path does not break them. Groups are where you attach policies — by including Entities as members, you can compose permission inheritance. There are two kinds: internal and external groups.

Authorization is determined at token issuance by taking the union of the token policies coming from the auth method and the Identity policies assigned to the Entity and its Groups. Subsequent group changes generally do not propagate to tokens that have already been issued.

• Entity = the core identity of a single person or application (a stable canonical_id)
• Alias = a record that ties a per-auth-method login name to an Entity (via the mount accessor)
• Group = a bundle of policies. Add Entities as members to grant permissions (internal or external groups)
• Effective policy = token policies ∪ Identity policies (from the Entity and its Groups)

Design Principles: Unifying Multiple Auth Methods Under One Entity

In practice, the easiest approach to both implement and operate is to use a stable business identifier (such as a corporate email address or employee ID) as the Entity name, and the natural username or claim from each auth method as the Alias name.

For OIDC, use sub (recommended) or email; for LDAP, the DN or sAMAccountName; for Kubernetes, the service account name or a JWT claim. For GitHub the alias is simply the username, and for userpass it is the Vault username itself. Even when path changes or rotations are expected, Aliases reference the accessor and remain intact.

• Choose an Entity name that can stay immutable for as long as the person or application exists
• Use the auth method's native stable field as-is for the Alias name
• Design around the accessor so that auth method path changes are absorbed transparently
• Concentrate policies on Entities and Groups; keep per-auth-method policies to an absolute minimum

Step-by-Step: Unifying Accounts from Different Auth Methods Into a Single Entity

Below is a minimal example that unifies the same person logging in via three auth methods — userpass, GitHub, and OIDC — under a single Entity. The flow boils down to three steps: create the Entity first, fetch the mount accessor for each auth method, then create identity/entity-alias entries using the accessor and the canonical_id (the Entity ID).

Changing the mount's path leaves the accessor untouched, so Aliases keep working. If you disable and recreate the mount, however, the accessor changes and the Aliases must be recreated.

• Create the Entity → save its ID (canonical_id)
• Run vault auth list to get each auth method's accessor
• Create identity/entity-alias with name + accessor + canonical_id
• After vault login, confirm Entity resolution (read identity/entity/id/<id>)

CLI example: creating the Entity and its 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 が作成できていることを確認

Policy Consolidation and Group Design

You can attach policies directly to an Entity, or attach them to a Group and add the Entity as a member. For operations that need to scale, manage policies primarily at the Group level and handle onboarding, team transfers, and permission changes by editing Group membership.

At authorization time, token policies from the auth method and Identity-side policies (from the Entity and its Groups) are unioned. As a rule of thumb, group changes take effect only for newly issued tokens.

• Internal groups: static groups defined inside Vault, mapped to teams or job roles
• External groups: pull in OIDC/LDAP group names via group-alias so changes on the IdP side flow through automatically
• Effective permissions are a union. Use Sentinel or namespace design — not policies — for deny semantics
• Already-issued tokens generally have fixed policies; changes only take effect on re-login or re-issuance

Flow: multiple auth methods → Entity → Group → policies

Operations: Path Changes, Merging Duplicates, and Offboarding

Renaming an auth method's path (for example auth/oidc → auth/idp) is independent of the accessor, so Aliases are preserved. If you disable and recreate the method, the accessor changes and you have to recreate the Aliases.

During org changes or account duplication, you may unintentionally end up with two Entities for the same person. Use the identity/entity/merge API to consolidate them and pull the older Entity's Aliases into the new one. For offboarding, the safe order is: revoke the credentials on the auth method side first, delete the corresponding Aliases, then finally delete the Entity.

• Path change: even if you adjust the path through sys/auth, Aliases persist because they are keyed by accessor
• Rebuild: recreating the mount changes the accessor → recreate the Aliases
• Merge duplicates: use identity/entity/merge (policies and groups consolidate into the target Entity)
• Offboarding: stop the auth credentials → delete Aliases → delete the Entity, in that order
• Auditing: have audit devices record the entity_id to guarantee traceability

CLI example: merging duplicate Entities

# 既存の 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 Exam Prep: Frequently Tested Points

The core Identity vocabulary (Entity, Alias, Group) and the fact that Aliases are bound by the mount accessor come up constantly. Be able to explain quickly that the link is not the path name, that effective policy is determined by union, and that groups come in internal and external flavors.

Knowing the minimum CLI/HTTP surface (identity/entity, identity/entity-alias, identity/group, identity/group-alias) plus the workflow of fetching the accessor with auth list will serve you both in real work and on the exam.

• Creating an Alias requires canonical_id (the Entity ID), mount_accessor, and name
• Renaming a mount's path does not affect Aliases; watch out for accessor changes when the mount is recreated
• Effective policy is a union. Existing tokens generally do not see later changes
• Groups are where policies attach. External groups pull in IdP group names via group-alias
• API paths: identity/entity, identity/entity-alias, identity/group, identity/group-alias

Check With a Question

Frequently Asked Questions