From 5b7f7208add36cb2a8bf1683484c1568ad7bc8e1 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Tue, 3 Feb 2026 12:04:05 -0800 Subject: [PATCH 1/6] Add In-Task Authorization Code and OAuth 2.0 OBO Credential Injection sections to af-project-files.adoc Introduced new authentication configurations for in-task authorization and OAuth 2.0 On-Behalf-Of credential injection, including detailed YAML examples for implementation. --- modules/ROOT/pages/af-project-files.adoc | 55 ++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/modules/ROOT/pages/af-project-files.adoc b/modules/ROOT/pages/af-project-files.adoc index ac031f5a1..532a0cf09 100644 --- a/modules/ROOT/pages/af-project-files.adoc +++ b/modules/ROOT/pages/af-project-files.adoc @@ -924,6 +924,61 @@ authentication: headerName: X-Custom-Auth-Token # Custom header name ---- +[[in-task-auth]] +==== In-Task Authorization Code + +[source,yaml] +---- +authentication: + kind: in-task-authorization-code + secondaryAuthProvider: providerName + authorizationEndpoint: https://oauth.provider.com/authorize + tokenEndpoint: https://oauth.provider.com/token + scopes: Read + redirectUri: https://oauth.provider.com/callback + responseType: code + tokenAudience: https://api.example.com/agents/my-agent + codeChallengeMethod: S256 + bodyEncoding: form + challengeResponseStatusCode: 200 #Optional, Status code for challenge response. Default: 200. + tokenTimeout: 300 #Optional. Timeout in seconds for token requests. Default: 300. +---- + +[[obo-credential-injection]] +==== OAuth 2.0 OBO Credential Injection + +This authentication type supports OAuth 2.0 Token Exchange and Microsoft Entra ID On-Behalf-Of protocols. + +Using OAuth 2.0 Token Exchange: + +[source,yaml] +---- +authentication: + kind: oauth2-obo + flow: oauth2-token-exchange + tokenEndpoint: https://oauth.provider.com/token + clientId: clientId + clientSecret: clientSecret + targetType: audience + targetValue: https://api.example.com/agents/my-agent + scope: Read #optional, OAuth 2.0 scope to request. Required for Microsoft Entra OBO (for example, api://downstream-client-id/.default). Optional for OAuth 2.0 Token Exchange (RFC 8693). + timeout: 50000 #optional, Timeout for token exchange requests in milliseconds. Default: 10000. +---- + +Using Microsoft Entra ID On-Behalf-Of: + +[source,yaml] +---- +authentication: + kind: oauth2-obo + flow: microsoft-entra-obo + timeout: 50000 #optional, Timeout for token exchange requests in milliseconds. Default: 10000. + tokenEndpoint: https://oauth.provider.com/token + clientId: clientId + clientSecret: clientSecret + scope: api://downstream-client-id/.default +---- + [[exchange-json-file-element]] == exchange.json File Element From eb7b15f16adb3ed4562a8d463ce3fff508203bf6 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Tue, 3 Feb 2026 12:08:18 -0800 Subject: [PATCH 2/6] Update authentication options in af-project-files.adoc to include 'in-task-authorization-code' and 'oauth2-obo' types. Expanded the description of the 'spec.authentication.kind' property to reflect these additions. --- modules/ROOT/pages/af-project-files.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/af-project-files.adoc b/modules/ROOT/pages/af-project-files.adoc index 532a0cf09..3fc3a687e 100644 --- a/modules/ROOT/pages/af-project-files.adoc +++ b/modules/ROOT/pages/af-project-files.adoc @@ -779,7 +779,7 @@ The `connections` element has these properties. |`spec` |Connection specification. Properties vary by connection kind. |Object |Object with spec properties (See <>) |Yes |`spec.url` |The URL for the connection endpoint. |String |Valid URL string |Yes (for agent and llm), No (for mcp) |`spec.authentication` |Authentication configuration for the connection. |Object |Authentication object (See <>) |No -|`spec.authentication.kind` |The type of authentication. |String |`basic`, `oauth2-client-credentials`, `apikey-client-credentials`, `apiKey` |Yes (when authentication is specified) +|`spec.authentication.kind` |The type of authentication. |String |`basic`, `oauth2-client-credentials`, `apikey-client-credentials`, `apiKey`, `in-task-authorization-code`, and `oauth2-obo` |Yes (when authentication is specified) |`spec.authentication.username` |The username for basic authentication. |String |Any string value |Yes (for basic auth) |`spec.authentication.password` |The password for basic authentication. |String |Any string value |Yes (for basic auth) |`spec.authentication.headerName` |The name of the header in which to set the key. If not specified, 'Authorization' is set by default. |String |Any string value |No From 2697b3ad49ea10a07be43edef23c427fbcc29d2f Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Tue, 3 Feb 2026 12:25:38 -0800 Subject: [PATCH 3/6] Update timeout values in af-project-files.adoc for OAuth 2.0 token exchange requests from 50000ms to 5000ms to align with default settings. --- modules/ROOT/pages/af-project-files.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/af-project-files.adoc b/modules/ROOT/pages/af-project-files.adoc index 3fc3a687e..1c0ac2f02 100644 --- a/modules/ROOT/pages/af-project-files.adoc +++ b/modules/ROOT/pages/af-project-files.adoc @@ -962,7 +962,7 @@ authentication: targetType: audience targetValue: https://api.example.com/agents/my-agent scope: Read #optional, OAuth 2.0 scope to request. Required for Microsoft Entra OBO (for example, api://downstream-client-id/.default). Optional for OAuth 2.0 Token Exchange (RFC 8693). - timeout: 50000 #optional, Timeout for token exchange requests in milliseconds. Default: 10000. + timeout: 5000 #optional, Timeout for token exchange requests in milliseconds. Default: 5000. ---- Using Microsoft Entra ID On-Behalf-Of: @@ -972,11 +972,11 @@ Using Microsoft Entra ID On-Behalf-Of: authentication: kind: oauth2-obo flow: microsoft-entra-obo - timeout: 50000 #optional, Timeout for token exchange requests in milliseconds. Default: 10000. tokenEndpoint: https://oauth.provider.com/token clientId: clientId clientSecret: clientSecret scope: api://downstream-client-id/.default + timeout: 5000 #optional, Timeout for token exchange requests in milliseconds. Default: 5000. ---- [[exchange-json-file-element]] From 7cfac368d672eab104fa12298d551bf3a222aa6a Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Tue, 3 Feb 2026 12:41:47 -0800 Subject: [PATCH 4/6] Update timeout default values in af-project-files.adoc for OAuth 2.0 token exchange requests from 5000ms to 10000ms to ensure consistency with the latest specifications. --- modules/ROOT/pages/af-project-files.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/af-project-files.adoc b/modules/ROOT/pages/af-project-files.adoc index 1c0ac2f02..8d742a458 100644 --- a/modules/ROOT/pages/af-project-files.adoc +++ b/modules/ROOT/pages/af-project-files.adoc @@ -962,7 +962,7 @@ authentication: targetType: audience targetValue: https://api.example.com/agents/my-agent scope: Read #optional, OAuth 2.0 scope to request. Required for Microsoft Entra OBO (for example, api://downstream-client-id/.default). Optional for OAuth 2.0 Token Exchange (RFC 8693). - timeout: 5000 #optional, Timeout for token exchange requests in milliseconds. Default: 5000. + timeout: 5000 #optional, Timeout for token exchange requests in milliseconds. Default: 10000. ---- Using Microsoft Entra ID On-Behalf-Of: @@ -976,7 +976,7 @@ authentication: clientId: clientId clientSecret: clientSecret scope: api://downstream-client-id/.default - timeout: 5000 #optional, Timeout for token exchange requests in milliseconds. Default: 5000. + timeout: 5000 #optional, Timeout for token exchange requests in milliseconds. Default: 10000. ---- [[exchange-json-file-element]] From 152c4aa463c8c38af38668a7e3cb145e43302745 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Wed, 4 Feb 2026 12:13:16 -0800 Subject: [PATCH 5/6] Enhance authentication documentation in af-project-files.adoc by adding detailed property tables for 'basic', 'oauth2-client-credentials', 'apikey-client-credentials', 'in-task-authorization-code', and 'oauth2-obo' types. Updated YAML examples and descriptions for clarity and consistency. --- modules/ROOT/pages/af-project-files.adoc | 101 ++++++++++++++++++++++- 1 file changed, 97 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/af-project-files.adoc b/modules/ROOT/pages/af-project-files.adoc index 8d742a458..2a1cf442a 100644 --- a/modules/ROOT/pages/af-project-files.adoc +++ b/modules/ROOT/pages/af-project-files.adoc @@ -864,7 +864,7 @@ Both agents and MCP servers support the same authentication types with custom he [source,yaml] ---- authentication: - Kind: basic + kind: basic username: "username" password: "password" ---- @@ -879,6 +879,18 @@ kind: basic headerName: X-API-Authorization # Custom header instead of default "Authorization" ---- +The `basic` authentication has these properties. + +[cols="1,2,1,2,1",options="header"] +|=== +|Parameter |Description |Type |Valid Values |Required + +|`kind` |Authentication type. |String |`basic` |Yes +|`username` |The username for authentication. |String |Any string |Yes +|`password` |The password for authentication. |String |Any string |Yes +|`headerName` |The name of the header in which to set the credentials. If not specified, `Authorization` is used. |String |Any string |No +|=== + [[oauth-client-credentials]] ==== OAuth 2.0 Client Credentials @@ -888,10 +900,29 @@ authentication: kind: oauth2-client-credentials clientId: "client_id" clientSecret: "client_secret" - tokenUrl: "https://oauth.provider.com/token" + token: + url: "https://oauth.provider.com/token" + bodyEncoding: form + timeout: 300 scopes: ["read", "write"] # Optional ---- +The `oauth2-client-credentials` authentication has these properties. + +[cols="1,2,1,2,1",options="header"] +|=== +|Parameter |Description |Type |Valid Values |Required + +|`kind` |Authentication type. |String |`oauth2-client-credentials` |Yes +|`clientId` |The client ID. |String |Any string |Yes +|`clientSecret` |The client secret. |String |Any string |Yes +|`token` |Configuration for fetching the token. |Object |Object with token properties |Yes +|`token.url` |The URL of the token provider. |String |Valid URL |Yes +|`token.timeout` |Time in seconds to wait for the service to return the token. |Number |Any number |No +|`token.bodyEncoding` |The encoding format for the token request body. |String |`form`, `json` |No +|`scopes` |An array of scopes to request. |Array |Array of scope strings |No +|=== + [[anypoint-client-credentials]] ==== Anypoint Client Credentials @@ -903,6 +934,17 @@ authentication: clientSecret: "client_secret" ---- +The `apikey-client-credentials` authentication has these properties. + +[cols="1,2,1,2,1",options="header"] +|=== +|Parameter |Description |Type |Valid Values |Required + +|`kind` |Authentication type. |String |`apikey-client-credentials` |Yes +|`clientId` |The client ID. |Object |Object with `value` and optional `name` (default header name is `client_id`) |Yes +|`clientSecret` |The client secret. |Object |Object with `value` and optional `name` (default header name is `client_secret`) |Yes +|=== + [[api-key]] ==== API Key Authentication @@ -924,9 +966,22 @@ authentication: headerName: X-Custom-Auth-Token # Custom header name ---- +The `apiKey` authentication has these properties. + +[cols="1,2,1,2,1",options="header"] +|=== +|Parameter |Description |Type |Valid Values |Required + +|`kind` |Authentication type. |String |`apiKey` |Yes +|`apiKey` |The value of the API key. |String |Any string |Yes +|`headerName` |The name of the header in which to set the key. If not specified, `Authorization` is used. |String |Any string |No +|=== + [[in-task-auth]] ==== In-Task Authorization Code +Use `in-task authorization code` when the connection needs secondary credentials obtained during a task using the OAuth 2.0 Authorization Code flow. OAuth2 tokens are extracted from message data and injected into the `Authorization` header for upstream calls. This supports step-up or in-task authentication (for example, when a user must re-authenticate for a sensitive action). For more information about the associated policy, see xref:gateway::policies-outbound-a2a-intask-authorization-code.adoc[]. + [source,yaml] ---- authentication: @@ -944,10 +999,31 @@ authentication: tokenTimeout: 300 #Optional. Timeout in seconds for token requests. Default: 300. ---- +The `in-task-authorization-code` authentication has these properties. + +[cols="1,2,1,2,1",options="header"] +|=== +|Parameter |Description |Type |Valid Values |Required + +|`kind` |Authentication type. |String |`in-task-authorization-code` |Yes +|`authorizationEndpoint` |OAuth2 authorization endpoint URL. Used to generate the authentication challenge. |String |Valid URL |Yes +|`tokenEndpoint` |OAuth2 token endpoint URL. Used to generate the authentication challenge. |String |Valid URL |Yes +|`scopes` |OAuth2 scopes required for step-up authentication. |String |Space- or comma-separated scope list (e.g. `openid profile email`) |Yes +|`redirectUri` |OAuth2 redirect URI the client uses in the authorization flow. |String |Valid URI |Yes +|`secondaryAuthProvider` |Name of the IdP (e.g. `okta`, `auth0`). Informational only, for the authentication card. |String |Any string |No +|`responseType` |OAuth2 response type. |String |Typically `code`. Default: `code` |No +|`codeChallengeMethod` |PKCE code challenge method. |String |Typically `S256`. Default: `S256` |No +|`tokenAudience` |Intended recipient of the token (e.g. agent or API URL). |String |Any string |No +|`bodyEncoding` |Encoding for the token request body. |String |`form`, `json`. Default: `form` |No +|`tokenTimeout` |Timeout in seconds for token requests. |Integer |Positive integer. Default: 300 |No +|`challengeResponseStatusCode` |HTTP status code returned for auth-required challenge responses. Typically 200 for JSON-RPC compatibility. |Integer |HTTP status code. Default: 200 |No +|=== + + [[obo-credential-injection]] ==== OAuth 2.0 OBO Credential Injection -This authentication type supports OAuth 2.0 Token Exchange and Microsoft Entra ID On-Behalf-Of protocols. +This authentication type supports OAuth 2.0 Token Exchange and Microsoft Entra ID On-Behalf-Of protocols. For more information about the associated policy, see xref:gateway::policies-outbound-oauth-obo.adoc[]. Using OAuth 2.0 Token Exchange: @@ -977,7 +1053,24 @@ authentication: clientSecret: clientSecret scope: api://downstream-client-id/.default timeout: 5000 #optional, Timeout for token exchange requests in milliseconds. Default: 10000. ----- +---- + +The `oauth2-obo` authentication has these properties. + +[cols="1,2,1,2,1",options="header"] +|=== +|Parameter |Description |Type |Valid Values |Required + +|`kind` |Authentication type. |String |`oauth2-obo` |Yes +|`flow` |Token exchange flow type. |String |`oauth2-token-exchange` (RFC 8693), `microsoft-entra-obo` |Yes +|`clientId` |OAuth2 client ID for token exchange. |String |Any string |Yes +|`clientSecret` |OAuth2 client secret for token exchange. |String |Any string |Yes +|`tokenEndpoint` |OAuth2 token endpoint URL for token exchange. |String |Valid URL |Yes +|`targetType` |Parameter type for specifying the target service (audience for logical name, resource for physical URI). Used for OAuth 2.0 Token Exchange. |String |`audience`, `resource`. Default: `audience` |No +|`targetValue` |Target audience URI or resource URI for the exchanged token. Required for OAuth 2.0 Token Exchange. |String |Valid URI |Required when using `oauth2-token-exchange` with a target +|`scope` |OAuth scope to request. Required for Microsoft Entra OBO (e.g. `api://downstream-client-id/.default`). Optional for OAuth 2.0 Token Exchange. |String |Any string |Required for `microsoft-entra-obo` +|`timeout` |Timeout for token exchange requests in milliseconds. |Integer |Positive integer. Default: 10000 |No +|=== [[exchange-json-file-element]] == exchange.json File Element From 95aca70ad0380c406c9a5384dff72c7f56715e98 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Wed, 4 Feb 2026 12:15:36 -0800 Subject: [PATCH 6/6] Refine OAuth2 authentication property descriptions in af-project-files.adoc for clarity. Updated examples for 'scopes', 'secondaryAuthProvider', and 'tokenAudience' to enhance understanding and consistency. --- modules/ROOT/pages/af-project-files.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/af-project-files.adoc b/modules/ROOT/pages/af-project-files.adoc index 2a1cf442a..bf3a030ed 100644 --- a/modules/ROOT/pages/af-project-files.adoc +++ b/modules/ROOT/pages/af-project-files.adoc @@ -1008,12 +1008,12 @@ The `in-task-authorization-code` authentication has these properties. |`kind` |Authentication type. |String |`in-task-authorization-code` |Yes |`authorizationEndpoint` |OAuth2 authorization endpoint URL. Used to generate the authentication challenge. |String |Valid URL |Yes |`tokenEndpoint` |OAuth2 token endpoint URL. Used to generate the authentication challenge. |String |Valid URL |Yes -|`scopes` |OAuth2 scopes required for step-up authentication. |String |Space- or comma-separated scope list (e.g. `openid profile email`) |Yes +|`scopes` |OAuth2 scopes required for step-up authentication. |String |Space- or comma-separated scope list (for example, `openid profile email`) |Yes |`redirectUri` |OAuth2 redirect URI the client uses in the authorization flow. |String |Valid URI |Yes -|`secondaryAuthProvider` |Name of the IdP (e.g. `okta`, `auth0`). Informational only, for the authentication card. |String |Any string |No +|`secondaryAuthProvider` |Name of the IdP (for example, `okta`, `auth0`). Informational only, for the authentication card. |String |Any string |No |`responseType` |OAuth2 response type. |String |Typically `code`. Default: `code` |No |`codeChallengeMethod` |PKCE code challenge method. |String |Typically `S256`. Default: `S256` |No -|`tokenAudience` |Intended recipient of the token (e.g. agent or API URL). |String |Any string |No +|`tokenAudience` |Intended recipient of the token (for example, `agent1` or API URL). |String |Any string |No |`bodyEncoding` |Encoding for the token request body. |String |`form`, `json`. Default: `form` |No |`tokenTimeout` |Timeout in seconds for token requests. |Integer |Positive integer. Default: 300 |No |`challengeResponseStatusCode` |HTTP status code returned for auth-required challenge responses. Typically 200 for JSON-RPC compatibility. |Integer |HTTP status code. Default: 200 |No @@ -1062,7 +1062,7 @@ The `oauth2-obo` authentication has these properties. |Parameter |Description |Type |Valid Values |Required |`kind` |Authentication type. |String |`oauth2-obo` |Yes -|`flow` |Token exchange flow type. |String |`oauth2-token-exchange` (RFC 8693), `microsoft-entra-obo` |Yes +|`flow` |Token exchange flow type. |String |`oauth2-token-exchange`, `microsoft-entra-obo` |Yes |`clientId` |OAuth2 client ID for token exchange. |String |Any string |Yes |`clientSecret` |OAuth2 client secret for token exchange. |String |Any string |Yes |`tokenEndpoint` |OAuth2 token endpoint URL for token exchange. |String |Valid URL |Yes