--- layout: api page_title: 'OIDC Identity Provider' description: >- This is the API documentation for configuring and managing OIDC providers with Vault. --- ## Create or Update a Provider This endpoint creates or updates a Provider. | Method | Path | | :----- | :----------------- | | `POST` | `identity/oidc/provider/:name` | ### Parameters - `name` `(string: )` – The name of the provider. This parameter is specified as part of the URL. - `issuer` `(string: )` - Specifies what will be used as the `scheme://host:port` component for the `iss` claim of ID tokens. This defaults to a URL with Vault's `api_addr` as the `scheme://host:port` component and `/v1/:namespace/identity/oidc/provider/:name` as the path component. If provided explicitly, it must point to a Vault instance that is network reachable by clients for ID token validation. - `allowed_client_ids` `([]string: )` – The client IDs that are permitted to use the provider. If empty, no clients are allowed. If "*", all clients are allowed. - `scopes_supported` `([]string: )` – The scopes available for requesting on the provider. ### Sample Payload ```json { "allowed_client_ids": ["*"], "scopes_supported": ["test-scope"] } ``` ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider ``` ## Read Provider by Name This endpoint queries the OIDC provider by its name. | Method | Path | | :----- | :------------------------ | | `GET` | `/identity/oidc/provider/:name` | ### Parameters - `name` `(string: )` – The name of the provider. ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider ``` ### Sample Response ```json { "data": { "allowed_client_ids":["*"], "issuer":"", "scopes_supported":["test-scope"] } } ``` ## List Providers This endpoint returns a list of all OIDC providers. | Method | Path | | :----- | :------------------------------ | | `LIST` | `/identity/oidc/provider` | ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request LIST \ http://127.0.0.1:8200/v1/identity/oidc/provider ``` ### Sample Response ```json { "data": { "keys":[ "test-provider" ] } } ``` ## Delete Provider by Name This endpoint deletes an OIDC provider. | Method | Path | | :------- | :------------------------ | | `DELETE` | `/identity/oidc/provider/:name` | ### Parameters - `name` `(string: )` – The name of the provider. ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request DELETE \ http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider ``` ## Create or Update a Scope This endpoint creates or updates a scope. | Method | Path | | :----- | :----------------- | | `POST` | `identity/oidc/scope/:name` | ### Parameters - `name` `(string: )` – The name of the scope. This parameter is specified as part of the URL. The `openid` scope name is reserved. - `template` `(string: )` - The template string for the scope. This may be provided as escaped JSON or base64 encoded JSON. - `description` `(string: )` – A description of the scope. ### Sample Payload ```json { "template":"{ \"groups\": {{identity.entity.groups.names}} }", "description":"A simple scope example." } ``` ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/identity/oidc/scope/test-scope ``` ## Read Scope by Name This endpoint queries a scope by its name. | Method | Path | | :----- | :------------------------ | | `GET` | `/identity/oidc/scope/:name` | ### Parameters - `name` `(string: )` – The name of the scope. ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/identity/oidc/scope/test-scope ``` ### Sample Response ```json { "data": { "description":"A simple scope example.", "template":"{ \"groups\": {{identity.entity.groups.names}} }" } } ``` ## List Scopes This endpoint returns a list of all configured scopes. | Method | Path | | :----- | :------------------------------ | | `LIST` | `/identity/oidc/scope` | ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request LIST \ http://127.0.0.1:8200/v1/identity/oidc/scope ``` ### Sample Response ```json { "data": { "keys":[ "test-scope" ] } } ``` ## Delete Scope by Name This endpoint deletes a scope. | Method | Path | | :------- | :------------------------ | | `DELETE` | `/identity/oidc/scope/:name` | ### Parameters - `name` `(string: )` – The name of the scope. ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request DELETE \ http://127.0.0.1:8200/v1/identity/oidc/scope/test-scope ``` ## Create or Update a Client This endpoint creates or updates a client. | Method | Path | | :----- | :----------------- | | `POST` | `identity/oidc/client/:name` | ### Parameters - `name` `(string: )` – The name of the client. This parameter is specified as part of the URL. - `key` `(string: )` – A reference to a named key resource. This cannot be modified after creation. - `redirect_uris` `([]string: )` - Redirection URI values used by the client. One of these values must exactly match the `redirect_uri` parameter value used in each [authentication request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). - `assignments` `([]string: )` – A list of assignment resources associated with the client. - `id_token_ttl` `(int or duration: )` – The time-to-live for ID tokens obtained by the client. This can be specified as a number of seconds or as a [Go duration format string](https://golang.org/pkg/time/#ParseDuration) like `"30m"` or `"6h"`. The value should be less than the `verification_ttl` on the key. - `access_token_ttl` `(int or duration: )` – The time-to-live for access tokens obtained by the client. This can be specified as a number of seconds or as a [Go duration format string](https://golang.org/pkg/time/#ParseDuration) like `"30m"` or `"6h"`. ### Sample Payload ```json { "key":"test-key", "access_token_ttl":"30m", "id_token_ttl":"1h" } ``` ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/identity/oidc/client/test-client ``` ## Read Client by Name This endpoint queries a client by its name. | Method | Path | | :----- | :------------------------ | | `GET` | `/identity/oidc/client/:name` | ### Parameters - `name` `(string: )` – The name of the client. ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/identity/oidc/client/test-client ``` ### Sample Response ```json { "data":{ "access_token_ttl":1800, "assignments":[], "client_id":"014zXvcvbvIZWwD5NfD1Uzmv7c5JBRMb", "client_secret":"hvo_secret_bZtgQPBZaJXK7F5vOI7JlvEuLOfOUS7DmwynFjE3xKcsen7TyowqPFfYFXG2tbWM", "id_token_ttl":3600, "key":"test-key", "redirect_uris":[] } } ``` ## List Clients This endpoint returns a list of all configured clients. | Method | Path | | :----- | :------------------------------ | | `LIST` | `/identity/oidc/client` | ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request LIST \ http://127.0.0.1:8200/v1/identity/oidc/client ``` ### Sample Response ```json { "data": { "keys":[ "test-client" ] } } ``` ## Delete Client by Name This endpoint deletes a client. | Method | Path | | :------- | :------------------------ | | `DELETE` | `/identity/oidc/client/:name` | ### Parameters - `name` `(string: )` – The name of the client. ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request DELETE \ http://127.0.0.1:8200/v1/identity/oidc/client/test-client ``` ## Create or Update an Assignment This endpoint creates or updates an assignment. | Method | Path | | :----- | :----------------- | | `POST` | `identity/oidc/assignment/:name` | ### Parameters - `name` `(string: )` – The name of the assignment. This parameter is specified as part of the URL. - `entity_ids` `([]string: )` - A list of Vault [entity](https://www.vaultproject.io/docs/secrets/identity#entities-and-aliases) IDs. - `group_ids` `([]string: )` – A list of Vault [group](https://www.vaultproject.io/docs/secrets/identity#identity-groups) IDs. ### Sample Payload ```json { "group_ids":["my-group"], "entity_ids":["my-entity"] } ``` ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/identity/oidc/assignment/test-assignment ``` ## Read Assignment by Name This endpoint queries an assignment by its name. | Method | Path | | :----- | :------------------------ | | `GET` | `/identity/oidc/assignment/:name` | ### Parameters - `name` `(string: )` – The name of the assignment. ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/identity/oidc/assignment/test-assignment ``` ### Sample Response ```json { "data":{ "entity_ids":[ "my-entity" ], "group_ids":[ "my-group" ] } } ``` ## List Assignments This endpoint returns a list of all configured assignments. | Method | Path | | :----- | :------------------------------ | | `LIST` | `/identity/oidc/assignment` | ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request LIST \ http://127.0.0.1:8200/v1/identity/oidc/assignment ``` ### Sample Response ```json { "data": { "keys":[ "test-assignment" ] } } ``` ## Delete Assignment by Name This endpoint deletes an assignment. | Method | Path | | :------- | :------------------------ | | `DELETE` | `/identity/oidc/assignment/:name` | ### Parameters - `name` `(string: )` – The name of the assignment. ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request DELETE \ http://127.0.0.1:8200/v1/identity/oidc/assignment/test-assignment ``` ## Read Provider OpenID Configuration Returns OpenID Connect Metadata for a named OIDC provider. The response is a compliant [OpenID Provider Configuration Response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse). | Method | Path | | :----- | :--------------------------------------------------------------- | | `GET` | `/identity/oidc/provider/:name/.well-known/openid-configuration` | ### Parameters - `name` `(string: )` – The name of the provider. This parameter is specified as part of the URL. ### Sample Request ```shell-session $ curl \ --request GET \ http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/.well-known/openid-configuration ``` ### Sample Response ```json { "issuer": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider", "jwks_uri": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/.well-known/keys", "authorization_endpoint": "http://127.0.0.1:8200/ui/vault/identity/oidc/provider/test-provider/authorize", "token_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/token", "userinfo_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-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": [ "openid" ], "subject_types_supported": [ "public" ], "grant_types_supported": [ "authorization_code" ], "token_endpoint_auth_methods_supported": [ "client_secret_basic" ]} ``` ## Read Provider Public Keys Query this path to retrieve the public portion of keys for an OIDC provider. Clients can use them to validate the authenticity of an identity token. | Method | Path | | :----- | :----------------------------------------------- | | `GET` | `/identity/oidc/provider/:name/.well-known/keys` | ### Parameters - `name` `(string: )` – The name of the provider. This parameter is specified as part of the URL. ### Sample Request ```shell-session $ curl \ --request GET \ http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/.well-known/keys ``` ### Sample Response ```json { "keys": [ { "use": "sig", "kty": "RSA", "kid": "ee7c0920-fdb9-5c1a-9c69-6dab710d1a09", "alg": "RS256", "n": "zdFjUV9lBw5nQPvTtwH-gzKgRG7iepvYbFoc2hNB0-inJL25oh-mvNW3GS8jPY5XHLsiWa_1TKKE99JrKQgane2C96soFeOvR7SozbCeH8_FpZelH1Pym1NV038j05Vp87uB9FeKPsy1PNOLPTs_Fp42JIAenly7ojYwPp1s61p9V0U9rOhtldY7GkXHLN9s8v3aJjxqrTS3Puhs9MFS7EgRrEDAc69uiLXCoYXKygjXddvJi6j446XxnO2eTRMGl1f2t04s_vDgVnFQgjQSKYWPbOMhf2slkeR47fqE3qqUDzINxauqMbkW-PlLP9IN0crR2uC07cG2os4RxN4YHw", "e": "AQAB" }, { "use": "sig", "kty": "RSA", "kid": "6e468221-b7c2-9d2d-744d-33b7ae0357cb", "alg": "RS256", "n": "rMaucILJKiFg_lkCE8ZEV_8jiYdaVDjKkc-8XPBW8S34wIRl1EbsgCYfMHtJnIJ_3eUgOVorW5KVeN9C8W16LR3lhqRWS9y4qlt0AcWpOvsmxr5q5dS_QqgCjeftCKwJzUsMi5bMW8wKjRZdd-qLz6X1rVSZWX82G0So8nRBg9d3MNJbKcdIJrRbrxWkm8U9xMqRouzbyQ2Hsp2rRVgGh7yjEA6daI5Ao8UsPdBmlCM9oKZ1_Kje5JTfZKeHlT-58vn_ylCjMVlapLuUsDN6He2kPVyOzGbie297VOfjmB7QX0ah1f7Ni1UJFJYHrVK9wMfCLTltSFZBcQ9--FlVdQ", "e": "AQAB" } ]} ``` ## Authorization Endpoint Provides the [Authorization Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) for an OIDC provider. This allows OIDC clients to request an authorization code to be used for the [Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth). | Method | Path | | :---------- | :---------------------------------------- | | `GET/POST` | `/identity/oidc/provider/:name/authorize` | ### Parameters - `name` `(string: )` - The name of the provider. This parameter is specified as part of the URL. - `scope` `(string: )` - A space-delimited list of scopes to be requested. The `openid` scope is required. - `response_type` `(string: )` - The OIDC authentication flow to be used. The following response types are supported: `code`. - `client_id` `(string: )` - The ID of the requesting client. - `redirect_uri` `(string: )` - The redirection URI to which the response will be sent. - `state` `(string: )` - A value used to maintain state between the authentication request and client. - `nonce` `(string: )` - A value that is returned in the ID token nonce claim. It is used to mitigate replay attacks, so we *strongly encourage* providing this optional parameter. ### Sample Request ```shell-session $ curl \ --request GET \ --header "X-Vault-Token: ..." \ -G \ -d "response_type=code" \ -d "client_id=$CLIENT_ID" \ -d "state=af0ifjsldkj" \ -d "nonce=abcdefghijk" \ --data-urlencode "scope=openid" \ --data-urlencode "redirect_uri=http://127.0.0.1:8251/callback" \ http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/authorize ``` ### Sample Response ```json { "code": "BDSc9kVYljxND93YpveBuJtSvguM3AWe", "state": "af0ifjsldkj" } ``` ## Token Endpoint Provides the [Token Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) for an OIDC provider. | Method | Path | | :------ | :------------------------------------ | | `POST` | `/identity/oidc/provider/:name/token` | ### Parameters - `name` `(string: )` - The name of the provider. This parameter is specified as part of the URL. - `code` `(string: )` - The authorization code received from the provider's authorization endpoint. - `grant_type` `(string: )` - The authorization grant type. The following grant types are supported: `authorization_code`. - `redirect_uri` `(string: )` - The callback location where the authorization request was sent. This must match the `redirect_uri` used when the original authorization code was generated. ### Headers - Basic Auth `(string: )` - Authenticate the client using the `client_id` and `client_secret` as described in the [client_secret_basic authentication method](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication). The authentication method uses the HTTP Basic authentication scheme. ### Sample Request ```shell-session $ BASIC_AUTH_CREDS=$(printf "%s:%s" "$CLIENT_ID" "$CLIENT_SECRET" | base64) $ curl \ --request POST \ --header "Authorization: Basic $BASIC_AUTH_CREDS" \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d "code=4RL50r78p8HsNJY0GVUNGfjLHnpkRf3N" \ -d "grant_type=authorization_code" \ -d "redirect_uri=http://127.0.0.1:8251/callback" \ http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/token ``` ### Sample Response ```json { "access_token": "b.AAAAAQJEH5VXjfjUESCwySTKk2MS1MGVNc9oU-N2EyoLKVo9SYa-NnOWAXloYfrlO45UWC3R1PC5ZShl3JdmRJ0264julNnlBduSNXJkYjgCQsFQwXTKHcjhqdNsmJNMWiPaHPn5NLSpNQVtzAxfHADt4r9rmX-UEG5seOWbmK_Z5WwS_4a8-wcVPB7FpOGzfBydP7yMxHu-3H1TWyQvYVr28XUfYxcBbdlzxhJn0yqkWItgmZ25xEOp7SW7Pg4tYB7AXfk", "expires_in": 3600, "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImEzMjk5ZWVmLTllNDEtOGNiYS1kNWExLTZmZWM2NjIyODRjYyJ9.eyJhdF9oYXNoIjoiMUdlQlEzUFdtUjJ2ajZVU2swSW42USIsImF1ZCI6InpTSktMVmk0R1BYS1o3TTZzUUEwY3FNc05VaHNPYkVTIiwiY19oYXNoIjoiN09SOUszNmhNdllENzJkUkFLUHhNdyIsImNvbnRhY3QiOnsiZW1haWwiOiJ2YXVsdEBoYXNoaWNvcnAuY29tIiwicGhvbmVfbnVtYmVyIjoiMTIzLTQ1Ni03ODkwIn0sImV4cCI6MTYzMzEwNjI5NCwiZ3JvdXBzIjpbImVuZ2luZWVyaW5nIl0sImlhdCI6MTYzMzEwNDQ5NCwiaXNzIjoiaHR0cDovLzEyNy4wLjAuMTo4MjAwL3YxL2lkZW50aXR5L29pZGMvcHJvdmlkZXIvbXktcHJvdmlkZXIiLCJuYW1lc3BhY2UiOiJyb290Iiwibm9uY2UiOiJhYmNkZWZnaGlqayIsInN1YiI6IjUwMDA3OTZlLTM2ZGYtMGQ4Yy02NDYwLTgxODUzZDliMjY2NyIsInVzZXJuYW1lIjoiZW5kLXVzZXIifQ.ehdLj6jnrJvltar1kkVSyNK48w2M5vkh5DTFJFZDqatnDWhQbbKGLZnVgd3wD6KPboXRaUwhGe4jDiTIiSoJaovOhsia77NKukym_ROLvGZw-LG7xaYkzJLnmEfeQhelLxWe0DHPROB7VXcFqBx8vX5hkuoVyqrB87vwiobK42pDPZ9MRsmbM2yzBC3wrnT7RQFtT4q2Bbyt9YIAHUaq9rU0PwJRoNISw6of1uQHo3_UzLdpwth7PEOEcI47OBGFA5vR_Gw3ocREfSrUWfCWOInAKCT43cImvg4Bts6qiZYfv9n-iNBq4AihGqq_VEF-hB1Hrprn7VgnEZ1VjUHaQQ", "token_type": "Bearer" } ``` ## UserInfo Endpoint Provides the [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) for an OIDC provider. The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. | Method | Path | | :------ | :--------------------------------------- | | `POST` | `/identity/oidc/provider/:name/userinfo` | ### Parameters - `name` `(string: )` - The name of the provider. This parameter is specified as part of the URL. ### Headers - Access Token `(string: )` - The access token provided by the `Authorization: Bearer ` HTTP header acquired from the authorization endpoint. ### Sample Request ```shell-session $ curl \ -X GET \ --header "Authorization: Bearer $ACCESS_TOKEN" \ http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/userinfo ``` ### Sample Response ```json { "contact": { "email": "vault@hashicorp.com", "phone_number": "123-456-7890" }, "groups": [ "engineering" ], "sub": "5000796e-36df-0d8c-6460-81853d9b2667", "username": "end-user"} ```