open-vault/website/content/docs/secrets/identity/oidc-provider.mdx

---
layout: docs
page_title: OIDC Identity Provider
description: >-
  Setup and configuration for Vault as an OpenID Connect (OIDC) identity provider.
---

# OIDC Identity Provider

~> **Note:** This feature is currently a ***Tech Preview*** and not recommended
for deployment in production.

Vault as an OIDC identity provider allows clients speaking the OIDC protocol to
take advantage of Vault's various authentication methods and source of
identity. Clients can configure their authentication logic to talk to Vault.
Once enabled, Vault will act as the bridge to identity providers via its
existing authentication methods. Clients will also obtain identity information
for their end-users by leveraging custom templating of Vault identity
information.

The Vault OIDC provider feature currently only supports the 
[authorization code flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth).

## OIDC Provider Configuration

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.

Most secrets engines must be configured in advance before they can perform
their functions. These steps are usually completed by an operator or
configuration management tool.

1. Create a key that will be used to sign/verify ID tokens:
   ```text
   $ vault write identity/oidc/key/my-key \
     allowed_client_ids="xxAQWBYzD2WXsB8GiZqwq4jsUwfG0hJV" \
     verification_ttl="1h" \
     rotation_period="1h" \
     algorithm="RS256"
   Success! Data written to: identity/oidc/key/my-key
   ```

1. Create an assignment. This specifies which Vault entities and groups are
authorized to use a specific OIDC client for authentication flows:

   ```text
   $ vault write identity/oidc/assignment/my-assignment \
     group_ids="b6ea7804-acbd-e866-7c51-0896456bd4bb" \
     entity_ids="aa786a7a-da2f-dca7-3680-0710771cca51"
   Success! Data written to: identity/oidc/assignment/my-assignment
   ```

1. Create the 'user' custom scope:

   ```text
   $ TOKEN_TEMPLATE=$(cat << EOF
   {
       "username": {{identity.entity.aliases.$USERPASS_ACCESSOR.name}},
       "contact": {
           "email": {{identity.entity.metadata.email}},
           "phone_number": {{identity.entity.metadata.phone_number}}
       }
   }
   EOF
   )
   $ vault write identity/oidc/scope/user \
     description="Scope for user metadata" \
     template="$(echo $TOKEN_TEMPLATE | base64 -)"
   Success! Data written to: identity/oidc/scope/user
   ```

1. Create an OIDC client:

   ```text
   $ vault write identity/oidc/client/my-webapp \
     redirect_uris="http://127.0.0.1:8251/callback,http://127.0.0.1:8500/ui/oidc/callback" \
     assignments="my-assignment" \
     key="my-key" \
     id_token_ttl="30m" \
     access_token_ttl="1h"
   Success! Data written to: identity/oidc/client/my-webapp
   ```

1. Create an OIDC provider:

   ```text
   $ vault write identity/oidc/provider/my-provider \
     allowed_client_ids="xxAQWBYzD2WXsB8GiZqwq4jsUwfG0hJV" \
     scopes_supported="user"
   Success! Data written to: identity/oidc/provider/my-provider
   ```

1. Query the OIDC provider configuration:

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

## API

The Vault OIDC provider feature has a full HTTP API. Please see the
[OIDC identity provider API](/api-docs/secret/identity/oidc-provider) for more
details.