OIDC provider

Vault is an OIDC issuer — applications can use Vault as their identity provider for OAuth 2.0 / OpenID Connect flows. The implementation lives in the identity store: vault/identity_store_oidc.go (63k lines) for the consumer side and vault/identity_store_oidc_provider.go (93k lines) for the provider side.

Purpose

Let applications federate to Vault for sign-in instead of going to Auth0/Okta/Cognito. Vault becomes the IdP and uses its existing identity store and auth methods (LDAP, OIDC, SAML via plugin, …) as the underlying authenticator.

Endpoints

The OIDC provider is namespace-scoped: every namespace can host its own issuer at <ns>/identity/oidc/.... The endpoints follow the OIDC spec:

Endpoint	Path
Discovery	/.well-known/openid-configuration (proxied through http/handler.go)
JWKS	identity/oidc/.well-known/keys
Authorize	identity/oidc/provider/<name>/authorize
Token	identity/oidc/provider/<name>/token
Userinfo	identity/oidc/provider/<name>/userinfo
Introspection	identity/oidc/provider/<name>/introspect
Revocation	identity/oidc/provider/<name>/revoke
Dynamic registration	identity/oidc/provider/<name>/register (if enabled)

Configuration objects

graph LR
    Provider[Provider<br/>identity/oidc/provider/<name>] -->|allows| Client[Client<br/>identity/oidc/client/<name>]
    Provider --> Scope[Scope<br/>identity/oidc/scope/<name>]
    Scope --> Template[Templated claims]
    Provider --> Key[Key<br/>identity/oidc/key/<name>]
    Key --> JWK[JWK published at JWKS]
    Client --> Assignment[Assignment<br/>identity/oidc/assignment/<name>]
    Assignment --> Entity[Entity / Group]

• Key: an issuer signing key. Vault rotates it on a schedule and publishes the public material at the JWKS endpoint.
• Provider: a logical issuer. Has a name, a key, allowed scopes, allowed clients, and an issuer URL.
• Scope: a named set of templated claims. The template uses identity templating (helper/identity/identitytpl.go) to interpolate entity, alias, and group fields into the ID token / userinfo claims.
• Client: an OAuth client (web, native, public, confidential). Has a client_id, client_secret, redirect URIs, allowed grant types.
• Assignment: which entities and groups are allowed to sign in to which clients.

Token issuance

The authorization-code flow:

sequenceDiagram
    participant Browser
    participant App
    participant Vault as Vault OIDC provider
    participant Auth as Vault auth method
    Browser->>App: visit
    App->>Browser: redirect to Vault authorize
    Browser->>Vault: GET authorize?client_id=&scope=&redirect_uri=
    Vault->>Browser: prompt for Vault login (UI)
    Browser->>Auth: log in (LDAP, OIDC consumer, ...)
    Auth-->>Vault: Vault token + entity
    Vault->>Vault: check Assignment
    Vault->>Browser: redirect to redirect_uri?code=<authcode>
    Browser->>App: hand over code
    App->>Vault: POST token { code, client_id, secret }
    Vault->>Vault: build ID token using Scope templates
    Vault-->>App: { id_token, access_token }
    App->>Vault: GET userinfo (Bearer access_token)
    Vault-->>App: claims

ID tokens are JWTs signed with the provider's key. The kid lets clients fetch the right public key from the JWKS endpoint.

Templating

Scopes use Go-template syntax with the identity context exposed as the root. Example scope template:

{
  "groups": "{{identity.entity.groups.names}}",
  "username": "{{identity.entity.aliases.<accessor>.name}}"
}

Templating logic is in helper/identity/identitytpl.go.

Multi-namespace

Each namespace gets a sibling OIDC issuer. Cross-namespace federation isn't supported in CE (Enterprise can use replication and namespace inheritance to share clients).

Integration points

• Identity store owns the configuration objects.
• The HTTP handler proxies the .well-known discovery URL to the identity-store path.
• Audit captures token issuance at the API layer.
• The UI has dedicated flows for managing OIDC clients.

Entry points for modification

• New scope behavior: extend vault/identity_store_oidc.go's scope-template eval loop.
• New client metadata field: extend client paths in vault/identity_store_oidc_provider.go.
• New grant type: implement in oidc_provider.go's token endpoint handler.
• Custom signing algorithms: helper/identity/oidc/ (referenced from the issuer).