Single sign with a Web Chat

APPLIES TO: SDK v4

Single sign-on (SSO) allows a client, such as a Web Chat control, to communicate with a bot on behalf of the user. Currently, only the Microsoft Entra ID identity provider is supported.

Typically, a Web Chat is embedded in a website page. When the user signs in to the website, the Web Chat invokes a bot on behalf of the user. The website client's token, based on the user's credentials, is exchanged for a different one to access the bot. In this way, the user doesn't have to sign in twice; the first time on the website, and the second time on the bot, hence the term SSO.

The following diagram shows the SSO flow when using a Web Chat client.

On failure, SSO falls back to the existing behavior of showing the OAuth card. Failure can occur when user consent is required or when the token exchange fails.

Let's analyze the flow.

1. The user signs in to the website.

2. An OAuth trigger activity is received by the Web Chat.

3. The Web Chat starts a conversation with the bot via an OAuth trigger activity.

4. The bot sends back an OAuth Card to the Web Chat.

5. The Web Chat intercepts the OAuth card before displaying it to the user and checks if it contains a TokenExchangeResource property.

6. If the property exists, the Web Chat must get an exchangeable token for the user, which must be an Microsoft Entra ID token.

7. The Web Chat sends an Invoke activity to the bot with the body shown below.

   {
       "type": "Invoke",
       "name": "signin/tokenExchange",
       "value": {
           "id": "<any unique ID>",
           "connectionName": "<connection name on the bot (from the OAuth Card)>",
           "token": "<exchangeable token>"
       }
   }
   

8. The bot processes the TokenExchangeInvokeRequest by issuing a request to the Azure AI Bot Service to obtain an exchangeable token.

9. The Azure AI Bot Service sends the token to the bot.

10. The bot returns a TokenExchangeInvokeResponse back to the Web Chat. The Web Chat waits until it receives the TokenExchangeInvokeResponse.

    {
        "status": "<response code>",
        "body": {
            "id":"<unique ID>",
            "connectionName": "<connection Name on the bot (from the OAuth Card)>",
            "failureDetail": "<failure reason if status code isn't 200, null otherwise>"
        }
    }
    

11. If the TokenExchangeInvokeResponse has a status of 200, then the Web Chat doesn't show the OAuth card. For any other status or if the TokenExchangeInvokeResponse isn't received, then the Web Chat shows the OAuth card to the user. This ensures that the SSO flow falls back to normal OAuthCard flow, in case of any errors or unmet dependencies like user consent.

For an implementation example, please refer to this SSO sample.