Backport of identity/oidc: updates documentation for PKCE, client typ…

…es, and default resources into stable-website (#14668)

* backport of commit 88bc642

* backport of commit d3e53d2

* backport of commit d507ffb

Co-authored-by: Austin Gebauer <[email protected]>
Co-authored-by: Austin Gebauer <[email protected]>

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

@@ -21,7 +21,7 @@ This endpoint creates or updates a Provider.
   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.
+- `allowed_client_ids` `([]string: <optional>)` – The client IDs that are permitted to use the provider. If empty, no clients are allowed. If `"*"` provided, all clients are allowed.
 
 - `scopes_supported` `([]string: <optional>)` – The scopes available for requesting on the provider.
 
@@ -138,7 +138,8 @@ This endpoint creates or updates a scope.
 
 - `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.
+- `template` `(string: <optional>)` - The [JSON template](/docs/concepts/oidc-provider#scopes)
+  string for the scope. This may be provided as escaped JSON or base64 encoded JSON.
 
 - `description` `(string: <optional>)` – A description of the scope.
 
@@ -254,18 +255,40 @@ This endpoint creates or updates a client.
 
 - `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.
+- `key` `(string: "default")` – A reference to a [named key](/api-docs/secret/identity/tokens#create-a-named-key)
+  resource. This key will be used to sign ID tokens for the client. This cannot be modified
+  after creation. If not supplied, defaults to the built-in [default key](/docs/concepts/oidc-provider#keys).
 
 - `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.
+- `assignments` `([]string: <optional>)` – A list of assignment resources associated with
+  the client. Client assignments limit the Vault entities and groups that are allowed to
+  authenticate through the client. By default, no Vault entities are allowed. To allow all
+  Vault entities to authenticate through the client, supply the built-in
+  [allow_all](/docs/concepts/oidc-provider#assignments) assignment.
+
+- `client_type` `(string: "confidential")` – The [client type](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1)
+  based on its ability to maintain confidentiality of credentials. The following list details
+  the differences between confidential and public clients in Vault:
+  - `confidential`
+    - Capable of maintaining the confidentiality of its credentials
+    - Has a client secret
+    - Uses the `client_secret_basic` [client authentication method](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
+    - May use Proof Key for Code Exchange ([PKCE](https://datatracker.ietf.org/doc/html/rfc7636))
+      for the authorization code flow
+  - `public`
+    - Not capable of maintaining the confidentiality of its credentials
+    - Does not have a client secret
+    - Uses the `none` [client authentication method](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
+    - Must use Proof Key for Code Exchange ([PKCE](https://datatracker.ietf.org/doc/html/rfc7636))
+      for the authorization code flow
+
+- `id_token_ttl` `(int or duration: "24h")` – 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.
+- `access_token_ttl` `(int or duration: "24h")` – 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
@@ -317,6 +340,7 @@ $ curl \
       "assignments":[],
       "client_id":"014zXvcvbvIZWwD5NfD1Uzmv7c5JBRMb",
       "client_secret":"hvo_secret_bZtgQPBZaJXK7F5vOI7JlvEuLOfOUS7DmwynFjE3xKcsen7TyowqPFfYFXG2tbWM",
+      "client_type": "confidential",
       "id_token_ttl":3600,
       "key":"test-key",
       "redirect_uris":[]
@@ -547,7 +571,8 @@ $ curl \
     "authorization_code"
   ],
   "token_endpoint_auth_methods_supported": [
-    "client_secret_basic"
+    "client_secret_basic",
+    "none"
   ]}
 ```
 
@@ -622,6 +647,17 @@ to be used for the [Authorization Code Flow](https://openid.net/specs/openid-con
 
 - `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.
 
+- `max_age` `(integer: <optional>)` - The allowable elapsed time in seconds since the last
+  time the end-user was actively authenticated.
+
+- `code_challenge` `(string: <optional>)` - The [PKCE](https://datatracker.ietf.org/doc/html/rfc7636)
+  code challenge derived from the client's code verifier. Optional for `confidential` clients.
+  Required for `public` clients.
+
+- `code_challenge_method` `(string: "plain")` - The method that was used to derive the
+  [PKCE](https://datatracker.ietf.org/doc/html/rfc7636) code challenge. The following
+  methods are supported: `S256`, `plain`.
+
 ### Sample Request
 
 ```shell-session
@@ -659,23 +695,31 @@ for an OIDC provider.
 ### Parameters
 
 - `name` `(string: <required>)` - The name of the provider. This parameter is
-specified as part of the URL.
+  specified as part of the URL.
 
 - `code` `(string: <required>)` - The authorization code received from the
-provider's authorization endpoint.
+  provider's authorization endpoint.
 
 - `grant_type` `(string: <required>)` - The authorization grant type. The
-following grant types are supported: `authorization_code`.
+  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.
+  authorization request was sent. This must match the `redirect_uri` used when the
+  original authorization code was generated.
+
+- `client_id` `(string: <required>)` - The ID of the requesting client. This parameter
+  is only required for `public` clients which do not have a client secret. `confidential`
+  clients should not use this parameter.
+
+- `code_verifier` `(string: <optional>)` - The code verifier associated with the given
+  `code`. Required for authorization codes that were granted using [PKCE](https://datatracker.ietf.org/doc/html/rfc7636).
+  Required for `public` clients.
 
 ### 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.
+- `Authorization: Basic` `(string: <required>)` - An HTTP Basic authentication scheme header
+  including the `client_id` and `client_secret` as described in the [client_secret_basic](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
+  authentication method. This header is only required for `confidential` clients.
 
 ### Sample Request