Single Sign-On and Sign-Out

Talkdesk® provides users with direct access to all apps installed from Talkdesk AppConnect™ within their instance of Talkdesk. To further streamline this experience, you are required to provide Single Sign-On and Single Sign-Out via Talkdesk to your hosted web apps.

When a user launches an app from their Talkdesk environment, they'll be re-directed to the standalone URL you provided when you registered your app's version.

From here, you are able to provide the users with the proper access and user experience in your hosted web apps. See below how to implement these processes.

Single Sign-On Implementation

👍

Single Sign-On is accomplished using the OAuth 2.0 Authorization Code grant type.

1 - Register an app

Registering your app will allow you to set up the technical information, including the events callback URL, testing it on your account and eventually publishing it on AppConnect to make it available for customers. If you have already registered your app, please proceed to step 2.

2 - Create the app technical version, setting up the events callback URL

2.1 - Configure the events callback URL - this is the webhook endpoint that allows the app to listen to the events sent by AppConnect.
2.2 - Configure the standalone URL - this is the URL to which the user will be directed to when clicking the icon on the App Manager, triggering the OAuth authentication flow.
2.3 - Configure the redirect URL - this is the endpoint to which the user will be redirected to once the authentication is successful.

3 - Store installation information

When a user installs an app, an event will be triggered to the events callback URL, containing all required credentials to make use of your OAuth Client. You must store this information on your side, and associate it with the installation ID. You must also store information (for the purposes of the Single Sign-On) regarding the authorization, tokens and userinfo links.

4 - Use the standalone endpoint to request an authorization code via Talkdesk

AppConnect passes the installation ID and the user ID parameters when calling the standalone URL webhook. You can use the installation ID to retrieve the OAuth Client information you stored (see step 3). By using this OAuth Client information, you will be able to call Talkdesk's authorization endpoint, which was also sent in the installation event. This will provide you with an authorization code.

When opening an installed app from Talkdesk, the user is redirected to the standalone URL you provided with these query parameters:

🚧

User ID

The user ID is meant to be used as a hint only, and it must not be used to authenticate Talkdesk users under any circumstance.

5 - Request a Talkdesk access token

By using the OAuth Client (step 4), the token endpoint you saved (step 3), and the authorization code (step 4), you can request an access token so that you can get information about the user (using the userinfo endpoint).

👍

Automated Authentication

When users are redirected to the standalone URL you provided, you must initiate the Single Sign-On process immediately. No additional clicks (i.e. "Login with Talkdesk") must be required from the user.

❗️

SSO Fail

If the Single Sign-On fails for any reason, or if you can’t resolve the Talkdesk user to an authenticated user in your system, you must present an error page with the user's contact.
Talkdesk recommends capturing these errors in your system automatically, so that you can provide proactive troubleshooting services to your customers.

Single Sign-Out Implementation

You must handle, on your side, the user.logout event.

🚧

Troubleshooting

If you have questions or technical issues, please open a ticket using this form.