向自适应卡片通用操作添加第三方身份验证

项目
11/18/2024

自适应卡片通用操作使用机器人作为处理操作的常见后端，并引入了一种新的操作类型，该类型 Action.Execute适用于 Teams 和 Outlook 等应用。

注意

对自适应卡片通用操作架构版本 v1.4 的支持仅适用于机器人发送的卡片。

可以在自适应卡通用操作上启用以下方案 Action.Execute ：

若要详细了解自适应卡片通用操作，请参阅自适应卡片通用操作。

如果要在共享具有通用操作的自适应卡片的实例中添加特定于用户的视图，则可能需要对用户进行身份验证。

过去，与机器人一对一聊天的用户必须等待，而你向他们发送单独的身份验证卡进行身份验证。若要与机器人通信，用户需要从会干扰流的群组聊天或频道中切换。

Action.Execute 协议中的身份验证流

在协议中 Action.Execute ，OAuth 的身份验证流在共享自适应卡片的群组聊天或频道对话的上下文中启用身份验证。

机器人可以使用登录请求来响应 Action.Execute 以下情况：

机器人在一对一聊天、群组聊天或频道中发送的自适应卡片。
应用用户通过消息扩展应用发送的自适应卡片 (机器人在一对一聊天、群组聊天或频道中) 提供支持。
当用户撰写邮件时，自适应卡片显示在撰写或预览区域中。在撰写区域中，自适应卡片中的刷新工作正常，机器人可能希望在将卡发送到聊天之前，使用令牌向应用用户提供特定于用户的视图。

OAuth 或名义登录流入门

使用通用操作的自适应卡片的 OAuth 或名义身份验证步骤类似于 Teams 中的机器人。

确保向 Teams 机器人添加了身份验证。若要详细了解如何创建启用了身份验证的机器人、如何将机器人部署到 Azure 并将其与标识提供者相关联，以及如何在 Microsoft Teams 中集成机器人，请参阅向 Teams 机器人添加身份验证。

对于 OAuth 或名义登录体验（其中向用户显示登录按钮或链接），以下是 OAuth 或名义登录流：

屏幕截图显示了具有通用操作的自适应卡的身份验证流。

Teams 客户端向机器人发送自适应卡片或 actionInvokeActivity 请求。
如果已存在字段中指定的activity.from.id用户的缓存令牌，机器人将使用令牌服务协议检查。通道在 activity.channelId 已配置的机器人和连接的字段中指定。
如果有缓存的令牌，机器人可以使用此令牌。如果没有令牌，机器人会创建一个 OAuthCard，并将其置于具有以下值的响应中：
```
{
  'statusCode': 401,
  'type': 'application/vnd.microsoft.activity.loginRequest',
  'value': {
     'text': 'Please sign-in',
     'connectionName': '<configured-connection-name>',
     'buttons': [
        {
           'title': 'Sign-In',
           'text': 'Sign-In',
           'type': 'signin',
           'value': '<sign-in-URL>'
        }
     ]
  }
}   
```
- 发件人必须包含符合 OAuthCard 格式的值。
- 发件人必须包含 connectionName。接收方可能会忽略具有空或缺失 connectionName的登录请求。
- 发送方必须包含 button 具有非空按钮数组的。
收到此响应后，Teams 客户端会在卡页脚中显示“登录”按钮，用户可以在其中登录。
当用户选择“ 登录 ”按钮时，标识提供者的登录页将在浏览器窗口中打开。用户登录后，“令牌服务”页会显示授权代码值。

Teams 客户端使用 name创建并发送adaptiveCard/action调用活动。该值包括 state 包含授权代码的字段：

{
   'type': 'invoke',
   'name': 'adaptiveCard/action'
   'value': {
      'action': {
         'id': 'abc123',
         'type': 'Action.Execute',
         'verb': 'saveCommand',
         'data': {
            'firstName': 'Jeff',
            'lastName': 'Derstadt'
         }
      },
   'state': '123456'
   },
   ...
}

发件人必须包含字段 state 。

通道将此调用传递给机器人，机器人使用身份验证代码从令牌服务检索令牌。令牌服务将用户的访问令牌传递给机器人。

如果缺少或空state字段，adaptiveCard/action接收方可能会忽略调用或答复并显示错误。

如果字段中的值 state 不正确，则机器人会向 Teams 客户端返回错误，如下所示：
```
  {
   'statusCode': 401,
   'type': 'application/vnd.microsoft.error.invalidAuthCode',
  }
```
Teams 客户端可以再次提示用户输入正确的授权代码，也可以再次发送 Action.Execute 请求。
如果字段中的 state 授权代码正确，机器人将代表用户使用访问令牌来执行其操作。
机器人使用卡或消息响应 Teams 客户端，而不会出错。

通过

向自适应卡片通用操作添加第三方身份验证

Action.Execute 协议中的身份验证流

OAuth 或名义登录流入门

另请参阅

其他资源