Share via

添加代码以启用自适应卡片通用操作的 SSO

  • 项目

单一登录 (SSO) 的身份验证步骤类似于 Teams 中的机器人。 下面是在自适应卡通用操作中实现 SSO 的步骤。

注意

若要实现 SSO 流，必须在应用清单中为机器人声明一对一聊天。 当应用用户通过自适应卡片 Action.Execute 协议调用 SSO 流时，系统会显示一条提示，允许应用用户在个人范围内安装应用（如果尚未安装）。

添加代码以处理访问令牌

确保已使用 Microsoft Entra ID 配置机器人以获取访问令牌。 可以更新代码以处理机器人中自适应卡片通用操作的访问令牌。

如果有缓存的令牌，机器人将使用相同的令牌。 如果没有可用的令牌，自适应卡会向机器人服务发送调用响应，该机器人服务会发送 OAuth 卡，其中包含以下值tokenExchangeResource，以指定 SSO 操作：

{
"statusCode": 401,
"type": "application/vnd.microsoft.activity.loginRequest",
"value": {
   "text": "Please sign-in",
   "connectionName": "<configured-connection-name>",
   "tokenExchangeResource": {
      "id": "<unique-indentifier>",
      "uri": "<application-or-resource-identifier>",
      "providerId": "<optional-provider-identifier>"
   },
   "buttons": [
      {
      "title": "Sign-In",
         "text": "Sign-In",
         "type": "signin",
         "value": "<sign-in-URL>"
      }
   ]
}
}

机器人服务将调用响应传递到 Teams 客户端，该客户端使用 tokenExchangeResource 值和 Teams 客户端令牌从Microsoft Entra ID 获取代表令牌或可交换令牌。

当 Teams 客户端出于任何原因（包括无效值、检索可交换令牌时出错）而忽略tokenExchangeResource该值时，SSO 会失败，或者如果Microsoft Entra ID 不支持该值。 然后，Teams 客户端触发名义登录或 OAuth 流。 建议在上述响应中提供登录 URL，以便 OAuth 流正常工作。

如果应用用户首次使用自适应卡片，则必须同意应用使用其标识。 将显示以下对话框：

屏幕截图显示了“同意”对话框。

当应用用户选择“查看并接受”时，将显示现有Microsoft Entra权限同意视图以显示所有权限。 应用用户可以继续执行身份验证流。

添加代码以接收令牌

  1. Teams 客户端将原始 adaptiveCard/action 内容与令牌一起再次发送到机器人，如下所示：

    {
"type": "invoke",
"name": "adaptiveCard/action"
"value": {
"action": {
   "id": "abc123",
   "type": "Action.Execute",
   "verb": "saveCommand",
   "data": {
      "firstName": "Jeff",
      "lastName": "Derstadt"
   }
},
"authentication": {
   "id": "8769-xyz",
   "connectionName": "oauthConnection",
   "token": "...single sign-on token..."
}
}
}

    以下代码片段演示如何在机器人服务中接收调用活动：

            protected override async Task<InvokeResponse> OnInvokeActivityAsync(ITurnContext<IInvokeActivity> turnContext, 
     CancellationToken cancellationToken)
        {
          JObject value = JsonConvert.DeserializeObject<JObject>
          (turnContext.Activity.Value.ToString());
          JObject authentication = null;
          if (value["authentication"] != null)
          {
          authentication = JsonConvert.DeserializeObject<JObject>(value["authentication"].ToString());
          }
        }

  2. Teams 客户端向机器人发送调用请求。 机器人会收到应用用户的同意，并使用其标识来帮助使用机器人框架令牌服务和Microsoft Entra ID 进行令牌交换过程。 机器人框架令牌服务将应用用户访问令牌传递给机器人。

    • 如果值不正确，机器人服务将忽略访问令牌。

    • 在执行令牌交换时遇到错误的机器人服务必须响应错误或不包含 SSO 信息的第二个登录请求。 如果机器人服务响应时出现错误，则错误必须为：

       {
  "statusCode" = 412,
  "type" = "application/vnd.microsoft.error.preconditionFailed",
  "value" = {
    "code" = "412",
    "message" = "authentication token expired"    }
    }

    • SSO 失败时，Teams 客户端在卡页脚中显示一个登录按钮，用于启动名义登录流。

  3. 机器人代表应用用户使用访问令牌来执行其操作。

  4. 机器人使用卡或消息向 Teams 客户端返回非错误响应。

注意

若要在应用用户注销时处理访问令牌，请参阅 处理应用用户注销。

代码示例

示例名称 说明 .NET Node.js 清单
自适应卡片通用操作的 SSO 此示例代码演示如何在机器人中为自适应卡片通用操作启用 SSO 身份验证。 View View View

另请参阅