Identity Secrets Engine

Vault’s Identity Secrets Engine is the core component for managing identities and policies in Vault. It tracks all clients (entities), maps authentication methods to those entities via aliases, and enables scalable policy assignment using groups.

Overview

Key characteristics:

• Represents every Vault client as an entity, each with:
  • A unique entity ID.
  • Zero or more aliases linking auth methods.
• Operators can manage entities, aliases, and groups via the UI, CLI, or API.
• On first login, Vault auto-creates an entity and alias if none exist.

Entities and Aliases

An entity represents one person or system. An alias maps a particular authentication method to that entity. You can pre-create entities and add aliases later or let Vault handle it automatically.

When a new user logs in via userpass, Vault:

1. Creates an entity (e.g., b81de864-...).
2. Attaches an alias combining the auth method (userpass) and username (JSmith).
3. Associates policies and optional metadata.

Example CLI commands:

vault write identity/entity name="Julie Smith" metadata=department=finance policies="management"
vault write identity/entity-alias name="JSmith" canonical_id="E48C..." mount_accessor="$(vault auth list -format=json | jq -r '.userpass_accessor')"

Multiple Authentication Methods

Without consolidation, multiple auth methods create separate entities:

• userpass/JSmith → entity B81D… (policy: accounting)
• ldap/[email protected] → entity E93D… (policy: finance)
• github/jsmith22 → entity F45A… (policy: accounts-payable)

This fragmentation can complicate policy management and reporting.

Consolidating into a Single Entity

To unify access, create one Julie Smith entity and attach all auth method aliases:

1. Create the entity and assign shared policy (management):

   vault write identity/entity name="Julie Smith" policies="management"
   

2. Add aliases for each auth method:

   vault write identity/entity-alias name="JSmith" canonical_id="E48C..." mount_accessor="userpass_accessor"
   vault write identity/entity-alias name="[email protected]" canonical_id="E48C..." mount_accessor="ldap_accessor"
   vault write identity/entity-alias name="jsmith22" canonical_id="E48C..." mount_accessor="github_accessor"
   

3. On login via any method, tokens inherit:
   • Alias-level policy (e.g., accounting)
   • Entity-level policy (management)

Vault Groups

Groups enable policy management for many entities simultaneously:

• A group can contain entities and subgroups.
• Assign policies at the group level; all members inherit them.
• Similar to directory-based groups (LDAP/AD).

Example: A Finance Team group with the finance policy includes:

• Maria (entity-level accounts-payable)
• John (entity-level management)

On login, tokens merge policies from:

1. Alias
2. Entity
3. Group

Internal vs. External Groups

Vault supports two group types:

Internal Groups and Namespaces

Use internal groups at the root namespace to grant child namespaces access without reconfiguring auth everywhere:

• At root: create an internal group team-finance with policy finance.
• In child namespace (finance): reference the root group as a subgroup.
• Users authenticated at root automatically gain child namespace permissions.

External Groups

External groups sync with your identity provider’s groups:

• Create a Vault external group (e.g., team-finance).
• Map an alias to the provider’s group name or UUID.
• Assign policies in Vault; manage membership in your IdP.

On login, Vault reflects current IdP memberships and applies policies.

Summary

• Entities unify clients under a unique identifier.
• Aliases link auth methods to entities for granular policies.
• Groups (internal/external) scale policy management across teams and namespaces.
• Use the Vault CLI and UI to configure entities, aliases, and groups.

Links and References

• Vault Identity Secrets Engine
• Managing Identities and Access
• HashiCorp Vault CLI