| --- |
| layout: docs |
| page_title: OIDC Provider |
| description: >- |
| Describes how Vault can be an OIDC identity provider. |
| --- |
| |
| # OIDC provider |
| |
| This document provides conceptual information about the Vault **OpenID Connect (OIDC) identity |
| provider** feature. This feature enables client applications that speak the OIDC protocol to |
| leverage Vault's source of [identity](/vault/docs/concepts/identity) and wide range of [authentication methods](/vault/docs/auth) |
| when authenticating end-users. For more information about the usage of Vault's OIDC provider, |
| refer to the [OIDC identity provider](/vault/docs/secrets/identity/oidc-provider) documentation. |
| |
| ## Configuration options |
| |
| The next few sections of the document provide implementation details for each resource that permits Vault configuration as an OIDC identity provider. |
| |
| ### OIDC providers |
| |
| Each Vault namespace will contain a built-in provider resource named `default`. The `default` |
| provider will allow all client applications within the namespace to use it for OIDC flows. |
| The `default` provider can be modified but not deleted. |
| |
| Additionally, a Vault namespace may contain several provider resources. Each configured provider will publish the APIs listed within the [OIDC flow](/vault/docs/concepts/oidc-provider#oidc-flow) section. The APIs will be served via backend path-based routing on Vault's listen [address](/vault/docs/configuration/listener/tcp#address). |
| |
| A provider has the following configuration parameters: |
| |
| * **Issuer URL**: used in the `iss` claim of ID tokens |
| * **Allowed client IDs**: limits which clients can access the provider |
| * **Scopes supported**: limits what identity information is available as claims |
| |
| The issuer URL parameter is necessary for the validation of ID tokens by clients. If an URL parameter is not provided explicitly, it will default to a URL with Vault's [api_addr](/vault/docs/configuration#api_addr) as the `scheme://host:port` component and `/v1/:namespace/identity/oidc/provider/:name` as the path component. This means tokens issued by a provider in a specified Vault cluster must be validated within that same cluster. If the issuer URL is provided explicitly, it must point to a Vault instance that is network-reachable by clients for ID token validation. |
| |
| The allowed client IDs parameter utilizes the list of client IDs that have been generated by Vault as a part of client registration. By default, all clients will be *disallowed*. Providing `*` as the parameter value will allow all clients to use the provider. |
| |
| The scopes parameter employs a list of references to named scope resources. The values provided are discoverable by the `scopes_supported` key in the OIDC discovery document of the provider. By default, a provider will have the `openid` scope available. See the scopes section below for more details on the `openid` scope. |
| |
| ### Scopes |
| |
| Providers may reference scope resources via the `scopes_supported` parameter to make specific identity information available as claims. |
| |
| A scope will have the following configuration parameters: |
| |
| * **Description**: identity information captured by the scope |
| * **Template**: maps individual claims to Vault identity information |
| |
| |
| The template parameter takes advantage of the [JSON-based templating](/vault/api-docs/secret/identity/tokens#template) used by identity tokens for claims mapping. This means the parameter will take a JSON string of arbitrary structure where the values may be replaced with specific identity information. Template parameters that are not present for a Vault identity are omitted from the resulting claims without an error. |
| |
| |
| Example of a JSON template for a scope: |
| |
| ``` |
| { |
| "username": {{identity.entity.aliases.$MOUNT_ACCESSOR.name}}, |
| "contact": { |
| "email": {{identity.entity.metadata.email}}, |
| "phone_number": {{identity.entity.metadata.phone_number}} |
| }, |
| "groups": {{identity.entity.groups.names}} |
| } |
| ``` |
| |
| The full list of template parameters are included in the following table: |
| |
| | Name | Description | |
| | :------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- | |
| | `identity.entity.id` | The entity's ID | |
| | `identity.entity.name` | The entity's name | |
| | `identity.entity.groups.ids` | The IDs of the groups the entity is a member of | |
| | `identity.entity.groups.names` | The names of the groups the entity is a member of | |
| | `identity.entity.metadata` | Metadata associated with the entity | |
| | `identity.entity.metadata.<metadata key>` | Metadata associated with the entity for the given key | |
| | `identity.entity.aliases.<mount accessor>.id` | Entity alias ID for the given mount | |
| | `identity.entity.aliases.<mount accessor>.name` | Entity alias name for the given mount | |
| | `identity.entity.aliases.<mount accessor>.metadata` | Metadata associated with the alias for the given mount | |
| | `identity.entity.aliases.<mount accessor>.metadata.<metadata key>` | Metadata associated with the alias for the given mount and metadata key | |
| | `identity.entity.aliases.<mount accessor>.custom_metadata` | Custom metadata associated with the alias for the given mount | |
| | `identity.entity.aliases.<mount accessor>.custom_metadata.<custom_metadata key>` | Custom metadata associated with the alias for the given mount and custom metadata key | |
| | `time.now` | Current time as integral seconds since the Epoch | |
| | `time.now.plus.<duration>` | Current time plus a [duration format string](/vault/docs/concepts/duration-format) | |
| | `time.now.minus.<duration>` | Current time minus a [duration format string](/vault/docs/concepts/duration-format) | |
| |
| |
| Several named scopes can be made available on an individual provider. Note that the top-level keys in a JSON template may conflict with those in another scope. When scopes are made available on a provider, their templates are checked for top-level conflicts. A warning will be issued to the Vault operator if any conflicts are found. This may result in an error if the scopes are requested in an OIDC Authentication Request. |
| |
| The `openid` scope is a unique case scope that may not be modified or deleted. The scope will exist in Vault and supported by each provider by default. The scope represents the minimum set of claims required by the OIDC specification for inclusion in ID tokens. As such, templates may not contain top-level keys that overwrite the claims populated by the openid scope. |
| |
| The following defines the claims key and value mapping for the `openid` scope: |
| |
| * `iss`- configured issuer of the provider |
| * `sub`- unique entity ID of the Vault user |
| * `aud`- ID of the client |
| * `iat`- time of token issue |
| * `exp`- time of token issue + ID token TTL |
| |
| ### Client applications |
| |
| A client resource represents an application that wants to delegate end-user authentication |
| to Vault using the OIDC protocol. The information provided by a client resource can be used |
| to configure an OIDC [relying party](https://openid.net/specs/openid-connect-core-1_0.html#Terminology). |
| |
| A client has the following configuration parameters: |
| |
| * **Redirect URIs**: limits the valid redirect URIs in an authentication request |
| * **Assignments**: determine who can authenticate with the client |
| * **Key**: used to sign the ID tokens |
| * **ID token TTL**: specifies the time-to-live for ID tokens |
| * **Access token TTL**: specifies the time-to-live for access tokens |
| * **Client type**: determines the client's ability to maintain confidentiality of credentials |
| |
| The `key` parameter is optional. The key will be used to sign ID tokens for the client. |
| It cannot be modified after creation. If not supplied, defaults to the built-in |
| [default key](/vault/docs/concepts/oidc-provider#keys). |
| |
| A `client_id` is generated and returned after a successful client registration. The |
| `client_id` uniquely identifies the client. Its value will be a string with 32 random |
| characters from the base62 character set. |
| |
| ~> **Note**: At least one of the redirect URIs of a client must exactly match the `redirect_uri` parameter used in an authentication request initiated by the client. |
| |
| #### Client types |
| |
| A client resource has a `client_type` parameter which specifies the OAuth 2.0 |
| [client type](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1) based on |
| its ability to maintain confidentiality of credentials. The following sections detail |
| the differences between confidential and public clients in Vault. |
| |
| ##### Confidential |
| |
| Confidential clients are capable of maintaining the confidentiality of their credentials. |
| Confidential clients have a `client_secret`. The `client_secret` will have a prefix of |
| `hvo_secret` followed by 64 random characters in the base62 character set. |
| |
| Confidential clients may use Proof Key for Code Exchange ([PKCE](https://datatracker.ietf.org/doc/html/rfc7636)) |
| during the authorization code flow. |
| |
| Confidential clients must authenticate to the token endpoint using the |
| `client_secret_basic` or `client_secret_post` [client authentication method](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication). |
| |
| ##### Public |
| |
| Public clients are not capable of maintaining the confidentiality of their credentials. |
| As such, public clients do not have a `client_secret`. |
| |
| Public clients must use Proof Key for Code Exchange ([PKCE](https://datatracker.ietf.org/doc/html/rfc7636)) |
| during the authorization code flow. |
| |
| Public clients use the `none` [client authentication method](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication). |
| |
| ### Assignments |
| |
| Assignment resources are referenced by clients via the `assignments` parameter. This parameter limits the set of Vault users allowed to authenticate. The assignments of an associated client are validated during the authentication request, ensuring that the Vault identity associated with the request is a member of the assignment's entities or groups. |
| |
| Each Vault namespace will contain a built-in assignment resource named `allow_all`. The |
| `allow_all` assignment allows all Vault entities to authenticate through a client. The |
| `allow_all` assignment cannot be modified or deleted. |
| |
| ### Keys |
| |
| Key resources are referenced by clients via the `key` parameter. This parameter specifies |
| the key that will be used to sign ID tokens for the client. See existing |
| [documentation](/vault/api-docs/secret/identity/tokens#create-a-named-key) for details on keyring |
| management, supported signing algorithms, rotation periods, and verification TTLs. Currently, |
| a key referenced by a client cannot be changed. |
| |
| Each Vault namespace will contain a built-in key resource named `default`. The `default` |
| key can be modified but not deleted. Clients that don't specify the `key` parameter at |
| creation time will use the `default` key. |
| |
| The `default` key will have the following configuration: |
| |
| - `algorithm` - `RS256` |
| - `allowed_client_ids` - `*` |
| - `rotation_period` - `24h` |
| - `verification_ttl` - `24h` |
| |
| ## OIDC flow |
| |
| ~> **Note**: The Vault OIDC Provider feature currently only supports the [authorization code flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth). |
| |
| The following sections provide implementation details for the OIDC compliant APIs provided by Vault OIDC providers. |
| |
| Vault OIDC providers enable registered clients to authenticate and obtain identity information (or "claims") for their end-users. They do this by providing the APIs and behavior required to satisfy the OIDC specification for the [authorization code flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth). All clients are treated as first-party. This means that end-users will not be required to provide consent to the provider as detailed in section [3.1.2.4](https://openid.net/specs/openid-connect-core-1_0.html#Consent) of the OIDC specification. The provider will release information to clients as long as the end-user has ACL access to the provider and their identity has been authorized via an assignment. |
| |
| Vault OIDC providers implement Proof Key for Code Exchange ([PKCE](https://datatracker.ietf.org/doc/html/rfc7636)) |
| to mitigate authorization code interception attacks. PKCE is required for `public` client types |
| and optional for `confidential` client types. |
| |
| ### OpenID configuration |
| |
| Each provider offers an unauthenticated endpoint that facilitates OIDC Discovery. All required metadata listed in [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) is included in the discovery document. Additionally, the recommended `userinfo_endpoint` and `scopes_supported` metadata are included. |
| |
| ### Keys |
| |
| Each provider offers an unauthenticated endpoint that provides the public portion of keys used to sign ID tokens. The keys are published in a JSON Web Key Set [(JWKS)](https://datatracker.ietf.org/doc/html/rfc7517) format. The keyset for an individual provider contains the keys referenced by all clients via the `allowed_client_ids` configuration parameter. A `Cache-Control` header to set based on responses, allowing clients to refresh their keys upon rotation. The `max-age` of the header is set based on the earliest rotation time of any of the keys in the keyset. |
| |
| ### Authorization endpoint |
| |
| Each provider offers an authenticated [authorization endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint). The authorization endpoint for each provider is added to Vault's [default policy](/vault/docs/concepts/policies#default-policy) using the `identity/oidc/provider/+/authorize` path. The endpoint incorporates all required [authentication request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) parameters as input. |
| |
| The endpoint [validates](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequestValidation) client requests and ensures that all required parameters are present and valid. The `redirect_uri` of the request is validated against the client's `redirect_uris`. The requesting Vault entity will be validated against the client's `assignments`. An appropriate [error code](https://openid.net/specs/openid-connect-core-1_0.html#AuthError) is returned for invalid requests. |
| |
| An authorization code is generated with a successful validation of the request. The authorization code is single-use and cached with a lifetime of approximately 5 minutes, which mitigates the risk of leaks. A response including the original `state` presented by the client and `code` will be returned to the Vault UI which initiated the request. Vault will issue an HTTP 302 redirect to the `redirect_uri` of the request, which includes the `code` and `state` as query parameters. |
| |
| ### Token endpoint |
| |
| Each provider will offer a [token endpoint](/vault/api-docs/secret/identity/oidc-provider#token-endpoint). The endpoint may be unauthenticated in Vault but is authenticated by requiring a `client_secret` as described in [client authentication](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication). The endpoint ingests all required [token request](/vault/api-docs/secret/identity/oidc-provider#parameters-15) parameters as input. The endpoint [validates](https://openid.net/specs/openid-connect-core-1_0.html#TokenRequestValidation) the client requests and exchanges an authorization code for the ID token and access token. The cache of authorization codes will be verified against the code presented in the exchange. The appropriate [error codes](https://openid.net/specs/openid-connect-core-1_0.html#TokenErrorResponse) are returned for all invalid requests. |
| |
| The ID token is generated and returned upon successful client authentication and request validation. The ID token will contain a combination of required and configurable claims. The required claims are enumerated in the scopes section above for the `openid` scope. The configurable claims are populated by templates associated with the scopes provided in the authentication request that generated the authorization code. |
| |
| An access token is also generated and returned upon successful client authentication and request validation. The access token is a Vault [batch token](/vault/docs/concepts/tokens#batch-tokens) with a policy that only provides read access to the issuing provider's [userinfo endpoint](/vault/api-docs/secret/identity/oidc-provider#userinfo-endpoint). The access token is also a TTL as defined by the `access_token_ttl` of the requesting client. |
| |
| ### UserInfo endpoint |
| |
| Each provider provides an authenticated [userinfo endpoint](/vault/api-docs/secret/identity/oidc-provider#userinfo-endpoint). The endpoint accepts the access token obtained from the token endpoint as a [bearer token](/vault/api-docs#authentication). The userinfo response is a JSON object with the `application/json` content type. The JSON object contains claims for the Vault entity associated with the access token. The claims returned are determined by the scopes requested in the authentication request that produced the access token. The `sub` claim is always returned as the entity ID in the userinfo response. |
