secure k8 s

Identity

Summary: Identity unifies the same human or machine across multiple auth methods. An entity represents a client; aliases link the entity to specific auth-method accounts; groups aggregate entities and can hold policies.

Sources: raw/docs/concepts/identity.md, raw/docs/secrets/identity/index.md.

Last updated: 2026-05-19

Entity, alias, group

  • Entity — a single client (human or machine) recognized by OpenBao.
  • Alias — a binding (auth mount, external account) → entity. One alias per auth mount per entity.
  • Group — a set of entities (or other groups). Can carry policies.

A user with both GitHub and LDAP accounts can map to one entity with two aliases — one per auth mount (source: raw/docs/concepts/identity.md).

Constraint: an entity cannot have two aliases on the same auth mount. The same auth type on different mounts is fine.

Where entities come from

When a client authenticates via any auth method except token, OpenBao either matches existing alias data or creates a new entity-with-alias on the fly (source: raw/docs/concepts/identity.md).

Why it matters

  • Single policy surface — attach policies to the entity once instead of duplicating across every auth method the user might use.
  • Identity-aware templating — policies and roles can reference identity.entity.name, group membership, metadata, etc.
  • Audit clarity — every request is attributable to a stable entity ID across method changes.

The Identity secrets engine

Identity is exposed as a built-in secrets engine, mounted at identity/, that can never be unmounted (source: raw/docs/secrets/identity/). Use it to:

  • Create entities/aliases manually.
  • Define internal and external groups.
  • Manage OIDC provider configuration.

OIDC provider

OpenBao can act as its own OIDC provider, issuing ID tokens about its entities. Useful for letting OpenBao be the SSO of last resort for tooling (source: raw/docs/concepts/oidc-provider.md).

  • auth — auth methods produce aliases
  • policies — entities and groups can hold policies directly
  • tokens — service tokens carry the entity ID they were minted for
  • namespaces — identity is namespace-scoped with cross-namespace inheritance