Single sign-on authentication for apps

Single Sign-On (SSO) allows users to interact with third-party applications directly through the embedded chat experience without logging in every time.

Builders or admins of the tenant can configure the SSO authentication. They must integrate the application with the Identity Provider (IdP), for example, Microsoft Entra ID, Okta, and IBM Security Verify. As part of this setup, they must ensure that all users of the tenant are included in the configuration. The IdP validates user credentials when they login and issue an SSO token.

When a user access an app for example, Workday through the embedded chat, watsonx Orchestrate uses a JWT (JSON Web Token) to authenticate them. The JWT must contain a valid sso_token under the user_payload, which is specific to the user who is running the embedded chat session. This sso_token is then used in the token exchange flow between IdP and the third-party app. The third-party app validates the token and if the user's token is valid, completes the intended task for the user. For more technical details, see OAuth 2.0 Token Exchange Launch icon .

SSO simplifies the authentication process for users. After configuration, users can access skills through the chat interface without being prompted to enter credentials each time. SSO authentication also ensures that the user's authorization is passed to the third-party application, thereby enhancing security, enabling quick access to skills, and eliminating the need to implement role-based authorization.

Before you begin

Before you configure SSO in watsonx Orchestrate, complete the following prerequisite:

Integrate your third-party application with your identity provider (IdP). For example, if you're configuring SSO for the Workday app, first integrate Workday with your IdP (for example, Microsoft Entra ID). For detailed guidance, see Microsoft Entra single sign-on (SSO) integration with Workday .

Steps to configure SSO authentication

Follow these steps to configure SSO for apps in wwatsonx Orchestrate:

Step 1: Configure the app in the Skill studio

From the main menu , select Skill studio.
Under the Skill and apps section, select Apps.
Click Edit next to the app that you want to configure.
Select the Configuration tab.
From the Authentication type drop-down, select SSO Authentication.
Provide the following details:

Server URL – The URL of the application server.

IdP URL – The authentication URL of your identity provider.

App URL – The endpoint of the app that watsonx Orchestrate need to connect to using the SSO token.

Step 2: Add authentication parameters

Some applications require more parameters to establish a successful SSO connection.

Click Add field to define new parameters.
In the Add new field dialog:

a. Select the method for sending the data:
- Send as header: To include the parameter in the request header.
- Send as body: To include the parameter in the request body.
b. Enter the Field name (must match exactly with the API specification).

c. Provide the Value for the field (for example, client ID, grant type).

d. Click Save to add the parameter.
Repeat the preceding steps to add all necessary fields.
Click Save to save the app configuration.

Step 3: Configure the embedded chat for SSO

Follow the steps to allow users to access the SSO enabled app through embedded chat:

From the main menu , go to AI agent configuration > Embed chat tab.
Toggle the Security switch to On.
In your custom JavaScript code that generates the JWT token, include the valid sso_token within the user_payload object. For more details, refer to Embedding the watsonx Orchestrate chat in a page.

The following sample code shows a user_payload object with a valid sso_token:

user_payload:{
    name: 'User',
    custom_user_id: userID,
    custom_message: 'hi hello',
    sso_token: `<Insert_SSO_token_here> `,
}

Results

After the configuration is complete,

In the Skill sets page, the Credential type for the app is set to Member. You can't edit the connection you can only change the app configuration to edit the credential type.
Users can access the skills through the embedded chat without manually authenticating.
The app is securely connected by using the SSO credentials that are configured by the builder.