OAuth2 Token Exchange

Edit online

This SSO implementation in watsonx Orchestrate communicates directly with the application for authentication. It is a single-step token exchange process.

Core parameters

The following parameters define the basic configuration for the OAuth2 Token Exchange.

Parameter

Description

Server URL

Base URL of the application server

Token URL

Endpoint to request the exchanged token

Client ID

The client identifier registered with the third-party application

Grant Type

It is pre-filled based on selected authentication type

These values are required to establish the connection and initiate the token exchange process.

Adding token request fields

The Token request field is used to add extra fields that the application authorization server requires when exchanging a token for an access token. They are useful for custom implementations.

Note:

These additional fields are specific to the application. Ensure that you gather this information as a prerequisite before you begin configuring the connection.

To add a token request field:

  1. Click Add field under the Token request field.

  2. On the Add token field page:

    • Send via: Choose where the field must be included in the request:

      • body: Adds the field in the request body (most common).

      • header: Adds the field in the HTTP header.

      • query: Adds the field as a query parameter in the URL.

    • Field name: Enter the exact parameter name expected by the token endpoint (for example, subject_token, subject_token_use).

    • Value: Enter the value for that parameter.

  3. Click Add to save the field.

Common token request fields

The following fields define the payload for the token exchange request:

  • app_token_key: Specifies the parameter name that the application endpoint uses to accept the SSO token in the token exchange request. The configured key must match the parameter name expected by the application token endpoint (for example, subject_token for OIDC providers). If not provided, watsonx Orchestrate defaults to assertion. For app_token_key, set Send via to Body.

    Example:

    app_token_key = subject_token

    This configuration sends the SSO token using subject_token instead of the default assertion.

  • requested_token_use: Specifies how the new token is used.

  • subject_token_use: Defines the role of the subject token.

These parameters ensure that the authorization server understands which token is being exchanged, what the new token represents, and how it will be used in the application flow.

Important:

  • OAuth2 Token Exchange on watsonx Orchestrate is currently supported only for in-portal chat scenarios.

  • It is a Beta feature.

  • If app_token_key is missing, watsonx Orchestrate defaults to assertion automatically.