Secure Chat (SSO)

Follow flow in

The chatter should be logged into a website with an Identity Provider (IdP) supporting OIDC. The chat client want to call the IdP to get an “Authorization Grant Code” that the Chat API can use to get the claims of the user from the IdP.

1. Redirect to Authorization endpoint

When the chat should start (click start button) the chat client first needs to get a state property and save its own URL to be redirecte4d to after the SSO has completed (POST /v1/auth/state/{customerKey}). The returned state is used in the next redirect to the Autorization endpoint.

The Autorization endpoint of the IdP, see chapter 2.1.1

The authorize endpoint typically looks like:

How to define different parts of url:

  • URL / Domain: The uri of the authorization endpoint that the chat client should redirect towards. New property in Chat Admin? Most flexible with replacement url. Can be used for additional query parameters.

  • client ID: New property in Chat Admin or part of URL?

  • redirect_uri: should be towards chat api auth redirect method (

  • scope: must contain openid connect, but rest is optional

  • state: returned from /v1/auth/state/{customerKey} that should be called first

  • in addition there may be other query parameters like acr_values that the customer wants to use.

How to define if authorizqation endpoint should be called? OIDC Auth is true in configuration.

2. Start chat session with authorization code

When website page is redirected back from IdP and Chat API (/v1/auth/redirect), the chat will load again with an authorization code in its query parameters called authCode. This authCode is set as value to property auth.code when starting a chat session (POST /v1/sessions). Remember to remove authCode from the query parameters so that you do not perform a new SSO on reload.

The auth object to be entered to the start chat session also have two other proerties:

  • connectionName: Authentication connection name should be set to OIDC.

  • mapping: Mapping of Authentication claims to variables, id or name. this is received in chat configuration as property authMapping

Et viola, done.

Do we need to do all these redirects? Yes, but do we need to redirect the whole webside page where the chat resides?

3. Something may go wrong

Some scenarios where things go wrong and SSO did not work.

  • You never get a redirect from Authorization Endpoint.

    • Look at the parameters in the Authorization endpoint.

    • Has the IdP added our redirect endpoint ( to their allowed callback urls?

    • Is SSO towards Puzzel with given client ID allowed in IdP?

  • Receive http 401 from Create session (POST /v1/sessions)

    • err_failed_authentication → This chat requires that your identity is authenticated through a third party application. Unfortunately we were not able to authenticate you.

  • Receive http 400 from Create session (POST /v1/sessions)

    • wrong input parameters like connectionName

  • Receive http 500 from Create session (POST /v1/sessions)

    • Something went wrong, maybe wrong/expired authentication code



02/02/2021 - 11:51

Last updated

10/09/2021 - 15:51