Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท Policies and Tokens

Vault Identity: Entities, Aliases, Groups and Templated Policies

Learn the Vault identity system: entities, aliases per auth method, internal and external groups, policy inheritance through groups and templated policies using identity data.

People and machines often authenticate in several ways: a developer logs in with OIDC on Monday and with LDAP on Tuesday. Without extra structure, Vault would see two unrelated users. The identity system links those logins into one entity, lets you gather entities into groups, and lets policies use that information. This lesson shows the model and a stand-in you can run.

Vault is not available on this site. Commands show real syntax; the JavaScript examples are stand-ins that model the relationships.

Entities and aliases

An entity is Vault's record of one user or application. Each login method creates an alias: a pair of (auth mount, identifier). When someone logs in, Vault finds or creates the entity for that alias and attaches the entity to the token.

Terminal
vault write identity/entity name="alice" policies="base"
vault write identity/entity-alias name="[email protected]" \
    canonical_id=<entity-id> mount_accessor=<oidc-accessor>
vault read identity/entity/name/alice

Entities can hold policies and metadata. Those policies are added to every token issued for the entity, even from different auth methods, on top of the policies the auth method role assigns.

Groups

Groups hold entities (and other groups) and attach policies to all members.

  • Internal groups are managed by hand or automation: vault write identity/group name=engineering policies=eng-read member_entity_ids=....
  • External groups map to a group in an outside system (LDAP, OIDC claims). Create the group, then an alias with the external group name; membership follows the provider at each login.

Groups can be nested: a child group's members inherit policies from parent groups.

flowchart LR
    A["OIDC login: alice@corp"] --> E["Entity: alice"]
    B["LDAP login: alice"] --> E
    E --> G1["Group: engineering"]
    G1 --> G2["Group: all-staff"]
    G1 -.-> P1["policy: eng-read"]
    G2 -.-> P2["policy: base"]

Two aliases, one entity, policies from two nested groups.

JS Stand-in: effective policies of an entity

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Templated policies

Policies can embed identity values so one rule fits everyone:

HCL
path "secret/data/teams/{{identity.groups.names.engineering.id}}/*" {
  capabilities = ["read"]
}
path "kv/data/{{identity.entity.aliases.auth_oidc_1a2b3c.name}}/*" {
  capabilities = ["create", "read", "update", "delete"]
}

Common template values: identity.entity.id, identity.entity.name, identity.entity.metadata.<key>, and identity.entity.aliases.<mount_accessor>.name. Prefer the entity ID or name for private per-user spaces, because it is stable across auth methods. See also policy basics.

OIDC provider and lookup

Vault can also act as an OIDC identity provider and issue identity tokens through identity/oidc/..., letting other applications trust Vault's view of who someone is. Use vault read identity/lookup/entity alias_name=... alias_mount_accessor=... to find an entity from an alias when debugging.

JS Stand-in: per-user path from a template

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Good practice

  • Merge aliases deliberately (identity/entity/merge) when duplicates appear.
  • Attach policies to groups rather than to individual entities.
  • Use external groups so offboarding in the identity provider removes access at the next login.
  • Remember entity-level policies are re-evaluated on every request, group changes apply right away.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does an entity alias represent?

    An alias ties an identifier in one auth mount to an entity.
  2. 2. Which group type follows membership in an outside provider such as LDAP?

    External groups are linked by alias to a group name in the provider.
  3. 3. Why use {{identity.entity.name}} in a policy?

    Templates substitute the caller's identity so a single policy serves everyone.
  4. 4. A user logs in through two auth methods mapped to the same entity. The token policies are:

    Identity policies are added on top of what the auth method grants.

Summary

  • Entities unify logins; aliases link a mount and an identifier to an entity.
  • Groups (internal or external, nestable) pass policies to many members.
  • Templated policies use identity values for per-user paths.
  • Identity policies are added to token policies.

Next: Dynamic Secrets and Leases