你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Web 聊天的单一登录

项目
12/20/2023

适用于：SDK v4

单一登录 (SSO) 使客户端（例如 Web 聊天控件）能够代表用户与机器人进行通信。目前仅支持 Microsoft Entra ID 标识提供者。

通常，Web 聊天嵌入在网站页面中。当用户登录到网站时，Web 聊天会代表用户调用机器人。网站客户端的基于用户凭据的令牌将交换为用于访问机器人的不同令牌。这样，用户就无需登录两次：第一次在网站上登录，第二次在机器人上登录，这就是术语 SSO 的由来。

下图显示了使用 Web 聊天客户端时的 SSO 流。

Sequence diagram for sign-on flow for Web Chat.

失败时，SSO 会回退到现有行为：显示 OAuth 卡。当需要用户同意或令牌交换失败时，可能会失败。

我们来分析流。

用户登录到网站。
Web 聊天接收 OAuth 触发器活动。
Web 聊天通过 OAuth 触发器活动开始与机器人聊天。
机器人将 OAuth 卡发回 Web 聊天。
Web 聊天在向用户显示 OAuth 卡之前将其截获，并检查它是否包含 TokenExchangeResource 属性。
如果该属性存在，则 Web 聊天必须获取用户的可交换令牌，该令牌必须是 Microsoft Entra ID 令牌。

Web 聊天使用如下所示的正文，向机器人发送调用活动。

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

机器人通过向 Azure AI 机器人服务发出获取可交换令牌的请求来处理 TokenExchangeInvokeRequest。
Azure AI 机器人服务将该令牌发送到机器人。

机器人将 TokenExchangeInvokeResponse 返回给 Web 聊天。在收到 TokenExchangeInvokeResponse 之前，Web 聊天会一直等待。

{
    "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>"
    }
}

如果 TokenExchangeInvokeResponse 的 status 为 200，则 Web 聊天不显示 OAuth 卡。如果是任何其他 status 或未收到 TokenExchangeInvokeResponse，则 Web 聊天会向用户显示 OAuth 卡。这可确保在发生错误或不符合依赖项（如用户许可）要求时 SSO 流回退到正常的 OAuthCard 流。

有关实现示例，请参阅此 SSO 示例。

使用 Web 聊天的单一登录

其他资源