Contact Us 1-800-596-4880
  1. Homepage
  2. Flex Gateway (1.11)
  3. Securing Flex Gateway Instances with Policies
  4. Outbound Policies Directory

  5. In-Task Authorization Code

In-Task Authorization Code Policy

Policy Name

In-Task Authorization Code

Summary

Ensures secondary credentials are present for in-task authentication using OAuth 2.0 Authorization Code flow

Category

A2A

First Flex Gateway version available

v1.11.4

Returned Status Codes

200 (authentication challenge), 401 (authentication failure)
This policy supports Agent2Agent Protocol (A2A) version v0.3.0. To learn more about A2A versions, see A2A Releases.

Summary

The In-Task Authorization Code policy is an outbound policy that ensures secondary credentials are present for in-task authentication using OAuth 2.0 Authorization Code flow. When requests require additional authentication beyond the initial connection, this policy:

  1. Detects if a request contains a secondary authentication token at $.params.message.parts[].data.auth_credentials.accessToken. This policy assumes that all requests besides agent card requests require secondary authentication.

  2. If a secondary token is missing, the policy returns an auth-required challenge with details of where the agent can obtain the token from the OAuth 2.0 authentication provider.

    To learn more about the authentication challenge response, see Challenge Response Format.

  3. If the token was initially provided or returned from the challenge response, the policy extracts the token from the request body.

  4. The policy sets the extracted token in the Authorization header and removes the token from the request body to prevent token leakage.

    To learn more about token handling, see Token Handling.

  5. The policy then forwards the request to upstream services.

To ensure agent discovery works uninterrupted, requests to these agent card endpoints bypass the policy without authentication:

  • /.well-known/agent-card.json

  • Any path ending in agent-card.json

Configuring Policy Parameters

Flex Gateway Local Mode

The In-Task Authorization Code policy isn’t supported in Local Mode.

Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy to your API instance from the UI, the following parameters are displayed:

Element Description Required

Secondary Auth Provider

Name of the OAuth 2.0 identity provider. For example: okta, azure-ad, auth0.

Optional

Authorization Endpoint

Authorization endpoint URL of the OAuth 2.0 service. For example: https://dev-12345.okta.com/oauth2/v1/authorize.

Required

Token Endpoint

Token endpoint of the OAuth 2.0 service. For example: https://dev-12345.okta.com/oauth2/v1/token.

Required

Scopes

Space or comma separated list of the OAuth 2.0 scopes required for in-task authentication. For example: openid profile email transaction:execute.

Required

Redirect URI

OAuth 2.0 redirect URI that the client uses in the authorization flow.

Required

Token Audience

OAuth 2.0 token audience. The intended recipient of the token. For example: https://my-agent.example.com/api.

Optional

Response Type

OAuth 2.0 response type. Typically code for authorization code flow.

Optional

Code Challenge Method

PKCE code challenge method. Typically S256 for SHA-256.

Optional

Body Encoding

Encoding format for token request body. Typically form for application/x-www-form-urlencoded. Default: form.

Optional

Token Timeout

Timeout in seconds for token requests.

Optional

User ID Header

Header name containing the user ID for user context propagation. Default: X-User-Id.

Optional

Challenge Response Status Code

HTTP status code to return for auth-required challenge responses. Typically 200 to maintain JSON-RPC compatibility.

Optional

Token Handling

For GET and POST requests, the policy handles the token differently:

  • GET: The policy removes the request body after the token extraction.

  • POST: The policy removes only the token property from the body and preserves the rest of the body.

The token is always removed from the body after extraction to prevent token leakage to the upstream service. The extracted token is set in the Authorization header as the Bearer <token> before forwarding the request. This overrides any existing Authorization header. Perform any authentication of the first authorization header prior to this policy.

The policy extracts the token from $.params.message.parts[].data.auth_credentials.accessToken. For example, using the default JSONPath, the policy extracts the token ("eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…​") from the following request body:

{
  "jsonrpc": "2.0",
  "id": "req-18",
  "method": "message/send",
  "params": {
    "taskId": "task-123",
    "contextId": "ctx-456",
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "data",
          "data": {
            "auth_credentials": {
              "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
            }
          }
        }
      ]
    }
  }
}

Challenge Response Format

If no secondary authentication token is found, the policy returns an auth-required A2A task response. The response preserves the taskId and contextId from the request if originally provided:

{
  "jsonrpc": "2.0",
  "id": "req-18",
  "result": {
    "id": "task-123",
    "contextId": "ctx-456",
    "status": {
      "state": "auth-required",
      "message": {
        "kind": "message",
        "role": "agent",
        "messageId": "msg-abc123",
        "taskId": "task-123",
        "parts": [
          {
            "kind": "text",
            "text": "To continue this task, additional authorization is required."
          },
          {
            "kind": "data",
            "data": {
              "authChallenge": {
                "secondaryAuthProvider": "okta",
                "authorizationEndpoint": "https://dev-12345.okta.com/oauth2/v1/authorize",
                "tokenEndpoint": "https://dev-12345.okta.com/oauth2/v1/token",
                "scopes": ["openid", "profile", "email"],
                "audience": "https://my-agent.example.com/api",
                "redirectUri": "https://myapp.example.com/oauth/callback",
                "responseType": "code",
                "codeChallengeMethod": "S256",
                "bodyEncoding": "form"
              }
            }
          }
        ],
        "metadata": {}
      },
      "timestamp": "2025-01-01T00:00:00.000Z"
    },
    "kind": "task"
  }
}
Only taskId and contextId are preserved. Snake_case variants, such as task_id or context_id are not supported.

See Also