Token store

The token store is the only auth method mounted by default at auth/token/. It mints, looks up, renews, and revokes the tokens every other request uses for authentication. Source: vault/token_store.go (4,370 lines), with helpers in vault/token_store_util.go, vault/token_store_util_common.go, and vault/tokens/.

Purpose

• Issue Vault tokens with attached policies, TTLs, accessors, and entity bindings.
• Enforce TTL and revocation, including parent/child trees so revoking a parent revokes all children.
• Provide accessor-based introspection and revocation without leaking the token itself.

Directory layout

vault/
├── token_store.go            # the bulk of the implementation
├── token_store_ce.go         # CE stub
├── token_store_util.go
├── token_store_util_common.go
└── tokens/                   # encoding/HMAC helpers
helper/identity/mfa/          # MFA constraints attached to tokens

Key abstractions

Symbol	File	Description
TokenStore	vault/token_store.go	The backend. Has dedicated barrier views for token storage and roles.
TokenEntry	vault/token_store.go	The persisted record: ID, accessor, policies, TTL, parent, entity, namespace, alias.
TokenStore.create / lookupID / revokeOrphan / revokeTreeInternal	vault/token_store.go	Hot-path operations.
Token roles	vault/token_store.go (tokenStoreRolesPrefix)	Named templates that constrain newly minted tokens.
TokenStore.cubbyholeBackend	vault/token_store.go	Hooks into vault/logical_cubbyhole.go so revoking a token clears its cubbyhole.

Token formats

Two on-the-wire formats:

• Service tokens (hvs.…): stored in Vault, have full lifecycle tracking.
• Batch tokens (hvb.…): self-contained, encrypted blobs that include their policies and TTL. Not stored, can't be renewed, but cheap to issue.

Both formats are produced and verified in vault/tokens/.

Lifecycle

stateDiagram-v2
    [*] --> Issued: TokenStore.create
    Issued --> Renewed: vault token renew
    Renewed --> Renewed: still within ExplicitMaxTTL/Period
    Issued --> Revoked: vault token revoke
    Renewed --> Revoked
    Issued --> Expired: TTL elapsed
    Revoked --> [*]
    Expired --> [*]

The expiration manager (vault/expiration.go) is what actually drives the timing: when a token is created, a corresponding lease is registered.

Token hierarchy

Most tokens are children of a parent (the token used to create them). When the parent is revoked, the entire subtree is revoked. The exception is orphan tokens, created with -orphan (or returned from auth methods that always orphan, like userpass for periodic tokens).

The hierarchy is materialized as edges under core/parent/<parent_id>/<child_id>. revokeTreeInternal walks the tree iteratively to avoid deep recursion.

Token roles

A token role (auth/token/roles/<name>) is a template that constrains tokens created against it: which policies are allowed, default policy set, TTLs, allowed entity aliases, namespace bindings. Useful for delegating restricted issuance to apps without giving them full root.

Integration points

• Mounted at auth/token/ by Core.setupCredentials. Cannot be unmounted.
• Reads identity policies via Core.identityStore.
• Registers a lease with Core.expiration for every service token.
• Owns cubbyhole/ interaction: when a token is revoked, its cubbyhole is dropped.
• Login MFA uses vault/login_mfa.go to gate token issuance for MFA-required logins.
• Replicated in Enterprise; OSS hooks in token_store_ce.go.

Entry points for modification

• Add a new token property: extend TokenEntry in vault/token_store.go and the encoding in vault/tokens/.
• Add a new token-role constraint: extend tokenStoreRoleEntry and the validation paths.
• Hook into revocation: add a callback in Core.tokenStore.callbacks (used by cubbyhole and expiration).