Identity store

Vault's identity store deduplicates users across auth methods, supports group-based policy assignment, and acts as an OIDC issuer. It's mounted at identity/ and is implemented as a regular logical.Backend even though it has special privileges. The package spans 17 files in vault/ and totals well over 350,000 lines of code (most of it the OIDC subsystem).

Purpose

• Maintain a canonical record of who a token belongs to, independent of which auth method issued it.
• Let operators assign policies to entities and groups instead of token-by-token.
• Support multi-cluster identity replication (Enterprise) and Vault-acting-as-OIDC-issuer (identity/oidc/...).

Directory layout

vault/
├── identity_store.go                       # Setup, paths, schema
├── identity_store_aliases.go               # Alias CRUD and merging
├── identity_store_aliases_stubs_oss.go     # CE stubs
├── identity_store_conflicts.go             # Conflict resolution during replication
├── identity_store_entities.go              # Entity CRUD
├── identity_store_entities_update.go
├── identity_store_groups.go                # Group CRUD + transitive resolution
├── identity_store_group_aliases.go         # External group aliases
├── identity_store_oidc.go                  # OIDC keys, scopes, roles (consumer side)
├── identity_store_oidc_provider.go         # OIDC issuer (provider side); 93k lines
├── identity_store_oidc_provider_util.go
├── identity_store_oidc_stubs_oss.go
├── identity_store_oidc_util.go
├── identity_store_schema.go                # MemDB schema definitions
├── identity_store_scim_schema.go           # SCIM mapping (Enterprise)
├── identity_store_scim_oss.go
├── identity_store_structs.go               # Wire types
├── identity_store_upgrade.go               # Schema migrations
├── identity_store_util.go                  # Shared helpers
├── identity_store_util_stubs_oss.go
├── identity_store_oss.go                   # OSS stubs for Enterprise multi-namespace
├── identity_store_test_stubs_oss.go
├── identity_lookup.go                      # Lookup paths
└── identity_store_injector*.go             # Internal test-only seeding
helper/identity/                            # Shared identity types and templating

Key abstractions

Symbol	File	Description
IdentityStore	vault/identity_store.go	The backend struct. Holds a MemDB instance for in-memory indexes.
Entity	helper/identity/types.pb.go	The canonical identity record. Owns aliases, groups, metadata.
Alias	helper/identity/types.pb.go	Per-auth-method record linking an external identity to an entity.
Group	helper/identity/types.pb.go	A collection of entities and/or other groups.
IdentityStore.entityByAliasFactors	vault/identity_store_aliases.go	Hot-path lookup by (mount accessor, alias name).
IdentityStore.MergeEntity	vault/identity_store_entities.go	Merge two entities; used to consolidate aliases that turn out to be the same person.
OIDCProvider paths	vault/identity_store_oidc_provider.go	The full OIDC issuer: discovery, JWKS, token endpoint, userinfo, dynamic clients.

How it works

When an auth method returns an Alias, identity store looks up the entity that owns that alias (mount-accessor scoped). If none exists, it creates one. Group memberships and policies are then resolved transitively for policy evaluation.

graph LR
    AM[Auth method] -->|Alias{mountAccessor, name}| ID[IdentityStore]
    ID -->|new or existing| Ent[Entity]
    Ent --> Groups
    Groups --> Pol[Policies attached to groups]
    Ent --> EntPol[Policies attached to entity]
    Pol & EntPol --> Token[Token policies = union]

External group aliases let external systems (like an OIDC provider, SAML IdP, or LDAP) map their group names onto Vault groups without manual sync.

Templating

Identity templates (helper/identity/identitytpl.go) interpolate entity, alias, and group fields into request paths and parameters. This is what enables, for example, kv policies of the form path "secret/data/users/{{identity.entity.name}}/*".

OIDC

Vault is both an OIDC consumer (via vault-plugin-auth-jwt's OIDC mode) and an OIDC issuer. The issuer side, in identity_store_oidc_provider.go, implements:

• Discovery: .well-known/openid-configuration (proxied through http/handler.go).
• JWKS endpoint.
• Authorize, token, userinfo, introspection endpoints.
• Dynamic client registration.
• Scopes and ID-token claims templated from identity data.

This is what powers auth/oidc clients of other services (Argo CD, Grafana, Boundary, …) talking to Vault as their IdP.

Integration points

• Auth methods: every Auth may carry an Alias (see Auth methods).
• Tokens: token policies pull in IdentityPolicies from the resolved entity/groups (see Token store).
• Replication: identity_store_conflicts.go resolves alias conflicts when secondary clusters merge.
• Activity / billing: client counting groups events by entity for billing (vault/activity_log.go).

Entry points for modification

• Add a new identity field: extend helper/identity/types.proto, regenerate, and update the MemDB schema (identity_store_schema.go).
• Add an OIDC scope: paths under identity/oidc/scope/ in identity_store_oidc.go and templating in identity_store_oidc_util.go.
• Customize alias matching: identity_store_aliases.go is where the per-(mount, alias) lookup happens.
• Custom claim transformation: helper/identity/identitytpl.go.