From ebb904031fc61a45019e379daa42c1f3acafee76 Mon Sep 17 00:00:00 2001 From: vinay-gopalan <86625824+vinay-gopalan@users.noreply.github.com> Date: Tue, 2 Nov 2021 11:01:28 -0700 Subject: [PATCH] [VAULT-3969] Document CRUD APIs for OIDC client and assignment (#12939) --- .../secret/identity/oidc-provider.mdx | 254 +++++++++++++++++- 1 file changed, 253 insertions(+), 1 deletion(-) diff --git a/website/content/api-docs/secret/identity/oidc-provider.mdx b/website/content/api-docs/secret/identity/oidc-provider.mdx index fe017e9b2..bdcf36f3c 100644 --- a/website/content/api-docs/secret/identity/oidc-provider.mdx +++ b/website/content/api-docs/secret/identity/oidc-provider.mdx @@ -17,7 +17,7 @@ This endpoint creates or updates a Provider. - `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. Defaults to a URL with +- `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. @@ -240,4 +240,256 @@ $ 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 ``` \ No newline at end of file