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

---
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: <required>)` – The name of the provider. This parameter is specified as part of the URL.

- `issuer` `(string: <optional>)` - 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: <optional>)` – The client IDs that are permitted to use the provider. If empty, no clients are allowed. If "*", all clients are allowed.

- `scopes_supported` `([]string: <optional>)` – 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: <required>)` – 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: <required>)` – 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: <required>)` – The name of the scope. This parameter is specified as part of the URL. The `openid` scope name is reserved.

- `template` `(string: <optional>)` - The template string for the scope. This may be provided as escaped JSON or base64 encoded JSON.

- `description` `(string: <optional>)` – 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: <required>)` – 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: <required>)` – 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: <required>)` – The name of the client. This parameter is specified as part of the URL.

- `key` `(string: <required>)` – A reference to a named key resource. This cannot be modified after creation.

- `redirect_uris` `([]string: <optional>)` - 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: <optional>)` – A list of assignment resources associated with the client.

- `id_token_ttl` `(int or duration: <optional>)` – 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: <optional>)` – 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: <required>)` – 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: <required>)` – 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: <required>)` – The name of the assignment. This parameter is specified as part of the URL.

- `entity_ids` `([]string: <optional>)` - A list of Vault [entity](https://www.vaultproject.io/docs/secrets/identity#entities-and-aliases) IDs.

- `group_ids` `([]string: <optional>)` – 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: <required>)` – 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: <required>)` – 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: <required>)` – 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: <required>)` – 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: <required>)` - The name of the provider. This parameter is specified as part of the URL.

- `scope` `(string: <required>)` - A space-delimited list of scopes to be requested. The `openid` scope is required.

- `response_type` `(string: <required>)` - The OIDC authentication flow to be used. The following response types are supported: `code`.

- `client_id` `(string: <required>)` - The ID of the requesting client.

- `redirect_uri` `(string: <required>)` - The redirection URI to which the response will be sent.

- `state` `(string: <required>)` - A value used to maintain state between the authentication request and client.

- `nonce` `(string: <optional>)` - 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: <required>)` - The name of the provider. This parameter is
specified as part of the URL.

- `code` `(string: <required>)` - The authorization code received from the
provider's authorization endpoint.

- `grant_type` `(string: <required>)` - The authorization grant type. The
following grant types are supported: `authorization_code`.

- `redirect_uri` `(string: <required>)` - 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: <required>)` - 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: <required>)` - The name of the provider. This parameter is
specified as part of the URL.

### Headers

- Access Token `(string: <required>)` - The access token provided by the
`Authorization: Bearer <access_token>` 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"}
```