A new platform for documentation and tutorials is launching soon.

We are migrating Vault documentation into HashiCorp Developer, our new developer experience.

Join Now
Type '/' to Search

»OIDC Identity Provider

Vault is an OpenID Connect (OIDC) identity provider. This enables client applications that speak the OIDC protocol to leverage Vault's source of identity and wide range of authentication methods when authenticating end-users. Client applications can configure their authentication logic to talk to Vault. Once enabled, Vault will act as the bridge to other identity providers via its existing authentication methods. Client applications can also obtain identity information for their end-users by leveraging custom templating of Vault identity information.

Note: For more detailed information on the configuration resources and OIDC endpoints, please visit the OIDC provider concepts page.

»Setup

The Vault OIDC provider system is built on top of the identity secrets engine. This secrets engine is mounted by default and cannot be disabled or moved.

Each Vault namespace has a default OIDC provider and key. This built-in configuration enables client applications to begin using Vault as a source of identity with minimal configuration. For details on the built-in configuration and advanced options, see the OIDC provider concepts page.

The following steps show a minimal configuration that allows a client application to use Vault as an OIDC provider.

  1. Enable a Vault auth method:

    $ vault auth enable userpass
Success! Enabled userpass auth method at: userpass/

    $ vault auth enable userpass
Success! Enabled userpass auth method at: userpass/

Any Vault auth method may be used within the OIDC flow. For simplicity, enable the userpass auth method.

  1. Create a user:

    $ vault write auth/userpass/users/end-user password="securepassword"
Success! Data written to: auth/userpass/users/end-user

    $ vault write auth/userpass/users/end-user password="securepassword"
Success! Data written to: auth/userpass/users/end-user

    This user will authenticate to Vault through a client application, otherwise known as an OIDC relying party.

  2. Create a client application:

    $ vault write identity/oidc/client/my-webapp \
  redirect_uris="https://localhost:9702/auth/oidc-callback" \
  assignments="allow_all"
Success! Data written to: identity/oidc/client/my-webapp

    $ vault write identity/oidc/client/my-webapp \
  redirect_uris="https://localhost:9702/auth/oidc-callback" \
  assignments="allow_all"
Success! Data written to: identity/oidc/client/my-webapp

    This operation creates a client application which can be used to configure an OIDC relying party. See the client applications section for details on different client types, including confidential and public clients.

    The assignments parameter limits the Vault entities and groups that are allowed to authenticate through the client application. By default, no Vault entities are allowed. To allow all Vault entities to authenticate, the built-in allow_all assignment is provided.

  3. Read client credentials:

    $ vault read identity/oidc/client/my-webapp

Key                 Value
---                 -----
access_token_ttl    24h
assignments         [allow_all]
client_id           GSDTnn3KaOrLpNlVGlYLS9TVsZgOTweO
client_secret       hvo_secret_gBKHcTP58C4aq7FqPWsuqKgpiiegd7ahpifGae9WGkHRCwFEJTZA9KGdNVpzE0r8
client_type         confidential
id_token_ttl        24h
key                 default
redirect_uris       [https://localhost:9702/auth/oidc-callback]

    $ vault read identity/oidc/client/my-webapp

Key                 Value
---                 -----
access_token_ttl    24h
assignments         [allow_all]
client_id           GSDTnn3KaOrLpNlVGlYLS9TVsZgOTweO
client_secret       hvo_secret_gBKHcTP58C4aq7FqPWsuqKgpiiegd7ahpifGae9WGkHRCwFEJTZA9KGdNVpzE0r8
client_type         confidential
id_token_ttl        24h
key                 default
redirect_uris       [https://localhost:9702/auth/oidc-callback]

    The client_id and client_secret are the client application's credentials. These values are typically required when configuring an OIDC relying party.

  4. Read OIDC discovery configuration:

    $ curl -s http://127.0.0.1:8200/v1/identity/oidc/provider/default/.well-known/openid-configuration
{
  "issuer": "http://127.0.0.1:8200/v1/identity/oidc/provider/default",
  "jwks_uri": "http://127.0.0.1:8200/v1/identity/oidc/provider/default/.well-known/keys",
  "authorization_endpoint": "http://127.0.0.1:8200/ui/vault/identity/oidc/provider/default/authorize",
  "token_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/default/token",
  "userinfo_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/default/userinfo",
  "request_parameter_supported": false,
  "request_uri_parameter_supported": false,
  "id_token_signing_alg_values_supported": [
    "RS256",
    "RS384",
    "RS512",
    "ES256",
    "ES384",
    "ES512",
    "EdDSA"
  ],
  "response_types_supported": [
    "code"
  ],
  "scopes_supported": [
    "openid"
  ],
  "subject_types_supported": [
    "public"
  ],
  "grant_types_supported": [
    "authorization_code"
  ],
  "token_endpoint_auth_methods_supported": [
    "none",
    "client_secret_basic",
    "client_secret_post"
  ]
}

    $ curl -s http://127.0.0.1:8200/v1/identity/oidc/provider/default/.well-known/openid-configuration
{
  "issuer": "http://127.0.0.1:8200/v1/identity/oidc/provider/default",
  "jwks_uri": "http://127.0.0.1:8200/v1/identity/oidc/provider/default/.well-known/keys",
  "authorization_endpoint": "http://127.0.0.1:8200/ui/vault/identity/oidc/provider/default/authorize",
  "token_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/default/token",
  "userinfo_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/default/userinfo",
  "request_parameter_supported": false,
  "request_uri_parameter_supported": false,
  "id_token_signing_alg_values_supported": [
    "RS256",
    "RS384",
    "RS512",
    "ES256",
    "ES384",
    "ES512",
    "EdDSA"
  ],
  "response_types_supported": [
    "code"
  ],
  "scopes_supported": [
    "openid"
  ],
  "subject_types_supported": [
    "public"
  ],
  "grant_types_supported": [
    "authorization_code"
  ],
  "token_endpoint_auth_methods_supported": [
    "none",
    "client_secret_basic",
    "client_secret_post"
  ]
}

    Each Vault OIDC provider publishes discovery metadata. The issuer value is typically required when configuring an OIDC relying party.

»Usage

After configuring a Vault auth method and client application, the following details can be used to configure an OIDC relying party to delegate end-user authentication to Vault.

  • client_id - The ID of the client application
  • client_secret - The secret of the client application
  • issuer - The issuer of the Vault OIDC provider

A number of HashiCorp products provide OIDC authentication methods. This means that they can leverage Vault as a source of identity using the OIDC protocol. See the following links for details on configuring OIDC authentication for other HashiCorp products:

Otherwise, refer to the documentation of the specific OIDC relying party for usage details.

»Supported Flows

The Vault OIDC provider feature currently supports the following authentication flow:

»Tutorial

Refer to the Vault as an OIDC Identity Provider tutorial to learn how to configure a HashiCorp Boundary to leverage Vault as a source of identity using the OIDC protocol.

»API

The Vault OIDC provider feature has a full HTTP API. Please see the OIDC identity provider API for more details.