feat: Update OAuth docs with user_info_request.response_map (#360)

Author: nbarbettini

examples/code/home/configuration/engine/full_config.1.0.yaml

@@ -65,10 +65,27 @@ auth:
             expires_in: '$.expires_in'
             scope: '$.scope'
             token_type: '$.token_type'
+        token_introspection_request: # Optional
+          endpoint: 'https://example.com/oauth/introspect'
+          method: POST
+          params:
+            token: '{{access_token}}'
+          auth_method: client_secret_basic # Optional
+          request_content_type: application/x-www-form-urlencoded # Optional
+          response_content_type: application/json # Optional
+          response_map: # Optional
+            expires_in: '$.data.expires_in'
+            scope: '$.data.scope'
+          expiration_format: relative_seconds # or absolute_unix_timestamp
+          triggers:
+            on_token_grant: true
+            on_token_refresh: true
         user_info_request: # Optional
           endpoint: 'https://example.com/oauth/userinfo'
           auth_method: bearer_access_token
           response_content_type: application/json
+          response_map:
+            custom_property: '$.data.custom_property'
           triggers:
             on_token_grant: true
             on_token_refresh: true

pages/home/auth-providers/oauth2.mdx

@@ -190,7 +190,7 @@ token_request:
 ```
 
 - `response_content_type` _(optional, default `application/json`)_: The expected content type of the response. Supported values are `application/json` and `application/x-www-form-urlencoded`.
-- `response_map` _(optional)_: A map of keys and values to extract from the response. Supports simple JSONPath expressions. Only applicable if `response_content_type` is `application/json`. See the [JSONPath reference](#jsonpath-expressions-in-response_map) for details on extracting values using JSONPath.
+- `response_map` _(optional)_: A map of keys and values to extract from the response. Supported keys are `access_token`, `expires_in`, `refresh_token`, `scope`, and `token_type`. Supports simple JSONPath expressions. Only applicable if `response_content_type` is `application/json`. See the [JSONPath reference](#jsonpath-expressions-in-response_map) for details on extracting values using JSONPath.
 
 #### `refresh_request`
 
@@ -218,7 +218,7 @@ refresh_request:
 ```
 
 - `response_content_type` _(optional, default `application/json`)_: The expected content type of the response. Supported values are `application/json` and `application/x-www-form-urlencoded`.
-- `response_map` _(optional)_: A map of keys and values to extract from the response. Supports simple JSONPath expressions. Only applicable if `response_content_type` is `application/json`. See the [JSONPath reference](#jsonpath-expressions-in-response_map) for details on extracting values using JSONPath.
+- `response_map` _(optional)_: A map of keys and values to extract from the response. Supported keys are `access_token`, `expires_in`, `refresh_token`, `scope`, and `token_type`. Supports simple JSONPath expressions. Only applicable if `response_content_type` is `application/json`. See the [JSONPath reference](#jsonpath-expressions-in-response_map) for details on extracting values using JSONPath.
 
 #### `user_info_request`
 
@@ -227,6 +227,7 @@ Some OAuth 2.0 APIs provide a user info endpoint that returns information about
 - `endpoint`: The user info endpoint for your OAuth 2.0 server, e.g. `/oauth2/userinfo`
 - `auth_method` _(optional, default `bearer_access_token`)_: The authentication method to use. The only supported value is `bearer_access_token`.
 - `response_content_type` _(optional, default `application/json`)_: The expected content type of the response. The only supported value is `application/json`.
+- `response_map` _(optional)_: A map of keys and values to extract from the response. If no `response_map` is provided, the entire response will be extracted verbatim. Supports simple JSONPath expressions. Only applicable if `response_content_type` is `application/json`. See the [JSONPath reference](#jsonpath-expressions-in-response_map) for details on extracting values using JSONPath.
 - `triggers`: Controls when the user info request is made.
   - `on_token_grant`: If `true`, the user info request will be made when a token is granted. This is typically only once for each user, unless new scopes are granted.
   - `on_token_refresh`: If `true`, the user info request will be made every time a token is refreshed.
@@ -272,17 +273,17 @@ auth:
 - `auth_method` _(optional, default `client_secret_basic`)_: The authentication method to use for the token introspection request. Supported values are `client_secret_basic` and `bearer_access_token`.
 - `request_content_type` _(optional, default `application/x-www-form-urlencoded`)_: The content type of the request body.
 - `response_content_type` _(optional, default `application/json`)_: The content type of the response body.
-- `response_map` _(required)_: A map of keys and values to extract from the response. Supports simple JSONPath expressions. Supported keys are `access_token`, `expires_in`, `refresh_token`, `scope`, and `token_type`.
+- `response_map` _(required)_: A map of keys and values to extract from the response. Supported keys are `expires_in` and `scope`. Supports simple JSONPath expressions.
 - `expiration_format` _(optional, default `absolute_unix_timestamp`)_: The format of the expiration time. Supported values are `absolute_unix_timestamp` and `relative_seconds`.
 - `triggers` _(required)_: Controls when the token introspection request is made.
   - `on_token_grant`: If `true`, the token introspection request will be made when a token is granted. This is typically only once for each user, unless new scopes are granted.
   - `on_token_refresh`: If `true`, the token introspection request will be made every time a token is refreshed.
 
 #### JSONPath expressions in `response_map`
 
-In the `token_request` and `refresh_request` sections, you can optionally configure a `response_map`. Configuring a response map is useful if your OAuth 2.0 server returns a JSON object with nested properties, or properties with non-standard names.
+In the `token_request`, `refresh_request`, `token_introspection_request`, and `user_info_request` sections, you can specify a `response_map`. Configuring a response map is useful if your OAuth 2.0 server returns a JSON object with nested properties, or properties with non-standard names.
 
-The typical JSON payload that most OAuth 2.0 servers return looks like this:
+For example, for the token request, most OAuth 2.0 servers return a JSON payload that looks like this:
 
 ```json
 {
@@ -293,7 +294,7 @@ The typical JSON payload that most OAuth 2.0 servers return looks like this:
 }
 ```
 
-If your server returns a payload that looks like this, you don't need `response_map`.
+If your server returns a payload of this shape, you don't need `response_map`!
 
 But if your server returns:
 
@@ -308,18 +309,18 @@ But if your server returns:
 }
 ```
 
-Then you need to configure `response_map` to extract the properties from inside the `data` object. Use [JSONPath](https://en.wikipedia.org/wiki/JSONPath) expressions to select the properties you need:
+Then you need to configure `response_map` to extract the nested properties from inside the `data` object. Use [JSONPath](https://en.wikipedia.org/wiki/JSONPath) expressions to select the properties you need:
 
 ```yaml
-token_request: # or refresh_request
+token_request:
   response_map:
     access_token: "$.data.access_token"
     expires_in: "$.data.expires_in"
     refresh_token: "$.data.refresh_token" # Only needed if refresh tokens are used
     scope: "$.data.scope" # Only needed if scopes are used
 ```
 
-Not all OAuth 2.0 servers support refresh tokens, or use scopes. The only required properties are `access_token` and `expires_in`.
+Similarly, for user info or token introspection requests, you can use `response_map` to extract custom properties from the response.
 
 #### Handling scope arrays
 
@@ -395,7 +396,7 @@ Here's a full example of the YAML configuration for a custom OAuth 2.0 provider:
 
 <ToggleContent showText="Click to view example" hideText="Hide example">
 
-```yaml file=<rootDir>/examples/code/home/configuration/engine/full_config.1.0.yaml#L8-L71 {11-71}
+```yaml file=<rootDir>/examples/code/home/configuration/engine/full_config.1.0.yaml#L9-L91 {11-83}
 
 ```
 

pages/home/local-deployment/configure/engine.mdx

@@ -119,7 +119,7 @@ Two cache implementations are available:
 - `in_memory` - _(default)_ An in-memory cache implementation suitable for a single-node Arcade Engine deployment.
 - `redis` - A Redis cache implementation suitable for a multi-node Arcade Engine deployment:
 
-```yaml file=<rootDir>/examples/code/home/configuration/engine/full_config.1.0.yaml#L76-L81 {3-6}
+```yaml file=<rootDir>/examples/code/home/configuration/engine/full_config.1.0.yaml#L93-L98 {3-6}
 
 ```
 
@@ -129,7 +129,7 @@ The `security` section configures the root encryption keys that the Arcade Engin
 
 A typical configuration looks like this:
 
-```yaml file=<rootDir>/examples/code/home/configuration/engine/full_config.1.0.yaml#L93-L97
+```yaml file=<rootDir>/examples/code/home/configuration/engine/full_config.1.0.yaml#L110-L116
 
 ```
 
@@ -170,7 +170,7 @@ storage:
 
 - `postgres` - A PostgreSQL database, suitable for production:
 
-```yaml file=<rootDir>/examples/code/home/configuration/engine/full_config.1.0.yaml#L101-L108
+```yaml file=<rootDir>/examples/code/home/configuration/engine/full_config.1.0.yaml#L118-L125 {2-10}
 
 ```
 
@@ -194,7 +194,7 @@ telemetry:
 To connect to OpenTelemetry compatible collectors, set the necessary [OpenTelemetry environment variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) in the `engine.env` file.
 `environment` and `version` are fields that are added to the telemetry attributes, which can be filtered on later.
 
-```yaml file=<rootDir>/examples/code/home/configuration/engine/full_config.1.0.yaml#L110-L114
+```yaml file=<rootDir>/examples/code/home/configuration/engine/full_config.1.0.yaml#L127-L131
 
 ```
 
@@ -210,7 +210,7 @@ Arcade Engine orchestrates [tools](/home/use-tools/tools-overview) that AI model
 
 The `tools.directors` section configures the workers that are available to service tool calls:
 
-```yaml file=<rootDir>/examples/code/home/configuration/engine/full_config.1.0.yaml#L116-L128 {6-13}
+```yaml file=<rootDir>/examples/code/home/configuration/engine/full_config.1.0.yaml#L133-L146 {3-13}
 
 ```