Single sign on
APPLIES TO: SDK v4
Single Sign on (SSO) allows a client, such as virtual assistant, WebChat and so on, to communicate with a bot or skill on behalf of the user. Currently, only the Azure AD v2 identity provider is supported.
SSO applies to the following scenarios:
- Virtual assistant and one or more skill bots. The user can sign in once into the virtual assistant. The assistant then invokes multiple skills on behalf of the user. See also Virtual assistant.
- Webchat embedded into a website. The user sign in the website. The website then invokes a bot or a skill on behalf of the user.
SSO provides the following advantages:
- The user does not have to login over again, if already signed in a virtual assistant or website.
- The virtual assistant or website do not have knowledge of user permissions.
Note
SSO is a new feature in Bot Framework SDK v4.8.
SSO components interaction
The following time sequence diagrams show the interactions between the SSO various components.
The following diagram shows a normal flow when using a virtual assistant client.

The following shows a normal and a fallback flow when using a WebChat client.

In the case of failure, SSO falls back to the existing behavior of showing the OAuth card. The failure may be caused for example if the user consent is required or if the token exchange fails.
Let's analyze the flow.
The client starts a conversation with the bot triggering an OAuth scenario.
The bot sends back an OAuth Card to the client.
The client intercepts the OAuth card before displaying it to the user and checks if it contains a
TokenExchangeResourceproperty.If the property exisists, the client sends a
TokenExchangeInvokeRequestto the bot. The client must have an exchangeable token for the user, which must be an Azure AD v2 token and whose audience must be the same asTokenExchangeResource.Uriproperty. The client 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 skill bot (from the OAuth Card)>", "token": "<exchangeable token>" } }The bot processes the
TokenExchangeInvokeRequestand returns aTokenExchangeInvokeResponseback to the client. The client should wait till it receives theTokenExchangeInvokeResponse.{ "status": "<response code>", "body": { "id":"<unique ID>", "connectionName": "<connection Name on the skill bot (from the OAuth Card)>", "failureDetail": "<failure reason if status code is not 200, null otherwise>" } }If the
TokenExchangeInvokeResponsehas astatusof200, then the client does not show the OAuth card. See the normal flow diagram. For any otherstatusor if theTokenExchangeInvokeResponseis not received, then the client shows the OAuth card to the user. See the fallback flow diagram. This ensures that the SSO flow falls back to normal OAuthCard flow, in case of any errors or unmet dependencies like user consent.