Vault Identity Entities and Groups

Unlock the full power of HashiCorp Vault by mastering its Identity system. In this guide, you’ll learn how Entities, Aliases, and Groups help you manage user and machine identities, unify authentication methods, and streamline permission assignment.

Vault Entities

A Vault Entity is the canonical representation of a user or machine (Vault client). When a unique client first authenticates, Vault’s Identity Secrets Engine creates an entity:

• Every entity has its own unique ID (canonical_id).
• Zero or more Aliases can link different auth methods and identifiers to the same entity.
• Attach policies and metadata (e.g., department, team) directly to an entity for centralized authorization.

Entity Aliases

An alias connects an auth method (e.g., Userpass, LDAP, GitHub) and the user’s login identifier to an entity. If no matching alias exists at login, Vault automatically creates both the entity and its alias.

In this example, Julie Smith has three aliases:

Without unification, Julie would need to log out and back in to switch permission sets.

Unifying Aliases Under One Entity

To grant Julie all her permissions in a single login, manually create one entity and map all aliases to it. Entities and aliases contribute their policies additively.

1. Create Julie’s entity with management metadata:

   vault write identity/entity \
     name="Julie Smith" \
     policies="it-management" \
     metadata="organization"="HCVOP, Inc" \
     metadata="team"="management"
   

   Save the returned entity_id (the canonical_id).

2. Add each alias, using the appropriate mount_accessor for the auth method:

   # GitHub alias
   vault write identity/entity-alias \
     name="jsmith22" \
     canonical_id="<entity_id>" \
     mount_accessor="<github_auth_accessor>"
   
   # LDAP alias
   vault write identity/entity-alias \
     name="[email protected]" \
     canonical_id="<entity_id>" \
     mount_accessor="<ldap_auth_accessor>"
   

   Get your mount_accessor values with:

   vault auth list
   

Once configured, any login by Julie—whether via LDAP, GitHub, or Userpass—yields a token with:

• Policies from the alias (e.g., finance)
• Policies from the entity (e.g., it-management)

Vault Groups

Groups let you bundle multiple entities (and even other groups) under shared policies. This structure scales permission management across teams.

Example group configuration:

• Maria Shi (alias maria.she) has base_user via her entity.
• John Lee (alias john.lee) has superuser via his entity.

When John logs in:

• He inherits superuser (alias).
• He gets management (entity).
• He also receives finance (group).

Internal vs. External Groups

Internal Groups

• Defined and managed solely within Vault.
• Ideal for grouping entities that share identical permission sets.
• Permissions automatically propagate into child namespaces without reconfiguring auth backends.

External Groups

• Created in Vault to mirror groups from external identity providers (LDAP, Okta, OIDC).
• Membership is controlled at the IDP—Vault simply assigns matching policies.
• Automatically keeps Vault policies in sync with your existing corporate groups.

Workflow for External Groups:

1. Enable and configure the auth method (e.g., LDAP).
2. Create an external group in Vault matching the IDP’s group name.
3. Attach policies to that external group.
4. Users in the IDP group inherit those policies on Vault login.

Further Reading and References

• Vault Identity Secrets Engine
• Vault Authentication Methods
• Vault Namespaces
• HashiCorp Vault Documentation

Master these Identity features to automate policy management, simplify user access, and maintain tight security controls in your Vault environment.