向 Teams 机器人添加身份验证

项目
06/14/2024

可以在 Microsoft Teams 中创建代表用户访问资源的机器人，例如邮件服务。可以使用基于 OAuth 2.0 的 Azure 机器人服务 v4 SDK 身份验证。使用此方法可以更轻松地开发能够基于用户凭据使用身份验证令牌的机器人。关键是标识 提供者的使用。

OAuth 2.0 是Microsoft Entra ID 和许多其他标识提供者使用的身份验证和授权的开放标准。对 OAuth 2.0 的基本理解是在 Teams 中使用身份验证的先决条件。

有关基本了解，请参阅 OAuth 2 简化，有关完整规范，请参阅 OAuth 2.0。

有关 Azure 机器人服务如何处理身份验证的详细信息，请参阅对话中的用户身份验证。

在本文中，您将了解：

如何创建已启用身份验证的机器人。使用 cs-auth-sample 处理用户登录凭据和生成身份验证令牌的。
如何将机器人部署到 Azure 并将其与标识提供程序关联。提供程序根据用户登录凭据颁发令牌。机器人可以使用令牌访问需要身份验证的资源，例如邮件服务。有关详细信息，请参阅 Microsoft机器人的 Teams 身份验证流。
如何在 Microsoft Teams 中集成机器人。集成机器人后，可以在聊天中登录并与其交换消息。

先决条件

了解机器人基础知识、管理状态、对话库以及如何实现顺序会话流。
了解 Azure 和 OAuth 2.0 开发。
Microsoft Visual Studio 和 Git 的最新版本。
Azure AD 帐户。如果需要，可以创建 Azure 免费帐户。

下面是一些示例方案：

示例	BotBuilder 版本	演示
cs-auth-sample 中的机器人身份验证	v4	OAuthCard 支持
js-auth-sample 中的机器人身份验证	v4	OAuthCard 支持
py-auth-sample 中的机器人身份验证	v4	OAuthCard 支持

创建资源组

资源组和服务计划不是严格必需的，但它们允许你方便地释放创建的资源。建议保持资源的组织和可管理性。

使用资源组为 Bot Framework 创建单个资源。为了提高性能，请确保这些资源位于同一 Azure 区域。

在浏览器中，登录到 Microsoft Azure 门户。
在左侧导航面板中，选择“资源组”。
在显示窗口左上角，选择“添加 ”选项卡以创建新的资源组。提供以下详细信息：
1. 订阅。使用现有订阅。
2. 资源组。请输入名称和资源组。例如 ，TeamsResourceGroup。请记住，该名称必须是唯一的。
3. 在 “区域 ”下拉菜单中，选择“ 美国西部”或靠近应用程序的区域。
4. 选择“审阅并创建”按钮。应会看到一条横幅，其中读取了传递的验证。
5. 选择“创建”按钮。创建资源组可能需要几分钟时间。

提示

与本教程稍后将创建的资源一样，最好将此资源组固定到仪表板，以便轻松访问。若要执行此操作，请选择仪表板右上角的固定图标 📌 。

创建服务计划

在Azure 门户的左侧导航面板上，选择“创建资源”。
在搜索框中，键入 App 服务计划。从搜索结果中选择 App 服务计划卡。
选择“创建”。
请提供下列信息：
1. 订阅。可以使用现有订阅。
2. 资源组。选择之前创建的组。
3. 名称。输入服务计划的名称。例如 TeamsServicePlan。请记住，该名称在组中必须是唯一的。
4. 操作系统。选择 Windows 或适用的 OS。
5. 区域。选择 美国西部 或靠近应用程序的区域。
6. 定价层。选择“ 标准 S1”，这是默认值。
7. 选择“审阅并创建”按钮。应会看到一条横幅，其中读取了传递的验证。
8. 选择“创建”。创建应用服务计划可能需要几分钟时间。计划在资源组中列出。

创建 Azure 机器人资源注册

Azure 机器人资源注册会将 Web 服务注册为机器人，机器人框架提供Microsoft应用 ID 和应用密码 (客户端密码) 。

重要

如果机器人未托管在 Azure 中，则只需注册它。如果通过 Azure 门户创建了机器人，则它已向服务注册。如果通过 Bot Framework 或开发人员门户创建了机器人，则机器人不会在 Azure 中注册。

在“创建资源”部分中访问 Azure 门户，并搜索 Azure 机器人。
打开 Azure 机器人，并选择“创建”。
在机器人句柄字段中输入 机器人句柄 名称。
从下拉列表中选择订阅。
从下拉列表中选择 资源组 。
选择应用类型作为 Microsoft 应用 ID 的多租户。
然后“审阅 + 创建”。
如果验证通过，请选择“创建”。

Azure 可在几分钟内预配机器人。
选择“转到资源”。机器人和相关资源在资源组中列出。

已创建 Azure 机器人。

若要创建客户端机密，请执行以下操作：

在设置中，选择“配置”。保存 Microsoft 应用 ID（客户端 ID）供将来参考。
在 “Microsoft应用 ID”旁边，选择“ 管理”。
在“客户端机密”部分中，选择“新建客户端机密”。将显示“添加客户端机密”窗口。
输入“说明”并选择“添加”。
在“值”列中，选择“复制到剪贴板”并保存客户端机密 ID 以供将来参考。

若要添加 Microsoft Teams 频道：

转到“主页”。
从 “最近使用的资源 ”部分打开机器人。
在左窗格中选择“ 频道 ”，然后选择“ Microsoft Teams ”。
选中复选框以接受服务条款，然后选择“ 同意”。
选择“保存”。

有关更多信息，请参阅“为 Teams 创建应用”。

创建标识提供程序

需要标识提供者进行身份验证。在此过程中，将使用 Microsoft Entra 提供程序。或者，也可以使用其他Microsoft Entra ID 支持的标识提供者。

在 Azure 门户的左侧导航面板中，选择“ Microsoft Entra ID”。

提示

必须在租户中创建并注册此Microsoft Entra 资源，在其中可以同意委托应用程序请求的权限。有关创建租户的说明，请参阅访问门户并创建租户。
在左侧面板中，选择“应用注册”。
在右侧面板中，选择左上角的“新建注册”选项卡。
请提供下列信息：
1. 名称。为新的服务应用程序输入一个名称。例如 ，BotTeamsIdentity。请记住，该名称必须是唯一的。
2. 选择应用程序“支持的帐户类型”。 选择任何组织目录中的帐户 (任何Microsoft Entra ID 租户 - 多租户) 和个人Microsoft帐户 (，例如Skype、Xbox) 。
3. 对于 重定向 URI：
  •选择 “Web”。
  ✓ 将 URL 设置为 https://token.botframework.com/.auth/web/redirect。
4. 选择“注册”。
Azure 创建应用后，会显示应用的 “概述 ”页。将以下信息复制并保存到文件：
1. 应用程序（客户端）ID 值。稍后在向机器人注册此 Azure 标识应用程序时，使用此值作为 客户端 ID 。
2. 目录 (租户) ID 值。稍后在向机器人注册此 Azure 标识应用程序时，请使用此值作为 租户 ID 。
在左侧面板中，选择 证书和机密 ，为应用程序创建客户端机密。
1. 在 “客户端机密”下，选择“➕ 新建客户端密码”。
2. 添加说明，从可能需要为此应用创建的其他人（如 Teams 中的 Bot 标识应用）中标识此机密。
3. 将“截止期限”设置为所选内容。
4. 选择“添加”。
5. 在离开此页面之前，请记录机密。稍后在机器人中注册 Microsoft Entra 应用程序时，使用此值作为 客户端密码 。

配置标识提供程序连接，并将其注册到机器人

注意

此处有两个服务提供程序选项：Azure Active Directory v1 和 Azure Active Directory v2。此处汇总了两个提供程序之间的差异，但通常，v2 在更改机器人权限方面提供了更大的灵活性。图形 API 权限列在范围字段中，并且随着新权限的添加，机器人将允许用户在下一次登录时同意新权限。对于 v1，用户必须删除机器人同意，才能在 OAuth 对话框中提示新权限。

Microsoft Azure Active Directory (Azure AD) v1

在Azure 门户中，从仪表板中选择资源组。
选择机器人注册链接。
打开资源页，然后在“设置”下选择“配置”。
选择“添加 OAuth 连接设置”按钮。下图在资源页中显示相应的选择：
如下所示完成表单：
1. 名称。输入连接的名称。在文件中的机器人 appsettings.json 中使用此名称。例如 BotTeamsAuthADv1。
2. 服务提供程序。选择“Azure Active Directory”。选择此选项后，将显示特定于 Azure Active Directory 的字段。
3. 客户端 ID。输入为 Azure 标识提供者应用记录的应用程序 (客户端) ID。
4. 客户端密码。输入为 Azure 标识提供者应用记录的机密。
5. 授权类型。输入 authorization_code。
6. 登录 URL。输入 https://login.microsoftonline.com。
7. 租户 ID，输入之前为 Azure 标识应用记录 的目录（租户）ID ，或创建标识提供程序应用时选择的受支持帐户类型的 常见 ID 。若要确定要分配的值，请遵循以下条件：
  - 如果选择 了“仅 (Microsoft 此组织目录中的帐户” - 单租户) “或 ”任何组织目录中的帐户“ (”任何Microsoft Entra ID 租户 - 多租户) “，请输入之前为 Microsoft Entra 应用记录的 租户 ID 。这将是与可进行身份验证用户关联的租户。
  - 如果选择 了任何组织目录中的帐户 (任何Microsoft Entra ID 租户 - 多租户) 和个人Microsoft帐户 (例如Skype，则 Xbox) 输入 单词 common 而不是租户 ID。否则，Microsoft Entra 应用将通过选择其 ID 的租户进行验证，并排除个人Microsoft帐户。
h. 对于 资源 URL，请输入 https://graph.microsoft.com/。代码示例中未使用此 URL。
i. 将范围留空。下图是一个示例：
选择“保存”。

Microsoft Azure Active Directory (Azure AD) v2

在Azure 门户中，从仪表板中选择 Azure 机器人。
在资源页中，选择“设置”下的“配置”。
选择“添加 OAuth 连接设置”按钮。
下图在资源页中显示相应的选择：
如下所示完成表单：
1. 名称。输入连接的名称。在文件中的机器人中 appsettings.json 使用此名称。例如 BotTeamsAuthADv2。
2. 服务提供程序。选择“ Azure Active Directory v2”。选择此选项后，将显示特定于 Azure AD v2 的字段。
3. 客户端 ID。输入为 Azure 标识提供者应用记录的应用程序 (客户端) ID。
4. 客户端密码。输入为 Azure 标识提供者应用记录的机密。
5. 令牌 Exchange URL。将其留空。
6. 租户 ID，输入之前为 Azure 标识应用记录 的目录（租户）ID ，或创建标识提供程序应用时选择的受支持帐户类型的 常见 ID 。若要确定要分配的值，请遵循以下条件：
  - 如果选择 了“仅 (Microsoft 此组织目录中的帐户” - 单租户) “或 ”任何组织目录中的帐户“ (”任何Microsoft Entra ID 租户 - 多租户) “，请输入之前为 Microsoft Entra 应用记录的 租户 ID 。这将是与可进行身份验证用户关联的租户。
  - 如果选择 了任何组织目录中的帐户 (任何Microsoft Entra ID 租户 - 多租户) 和个人Microsoft帐户 (例如Skype，则 Xbox) 输入 单词 common 而不是租户 ID。否则，Microsoft Entra 应用将通过选择其 ID 的租户进行验证，并排除个人Microsoft帐户。
7. 对于 “作用域”，请输入此应用程序所需的以空格分隔的图形权限列表，例如 User.Read、 User.ReadBasic.All 或 Mail.Read。
选择“保存”。

测试连接

选择连接项以打开创建的连接。
在“服务提供程序连接设置”面板顶部选择“测试连接”。
它首次打开一个新的浏览器窗口，要求你选择帐户。选择要使用的帐户。
接下来，允许标识提供者使用数据 (凭据) 。下图是一个示例：
选择“接受”。
此时会打开 与 <“连接名称> 已成功”页的测试连接 。如果收到错误，请刷新页面。下图是一个示例：

机器人代码使用连接名称来检索用户身份验证令牌。

准备机器人示例代码

完成初步设置后，让我们重点介绍如何创建要在本文中使用的机器人。

克隆 cs-auth-sample。
打开 Visual Studio。
在工具栏中，选择“ 文件 > 打开 > 项目/解决方案 ”并打开机器人项目。
在 C# 中，更新 appsettings.json 如下所示：
- 设置 ConnectionName 为添加到机器人注册的标识提供程序连接的名称。本示例中使用的名称是 BotTeamsAuthADv1。
- 设置 MicrosoftAppId 为机器人注册时保存的 机器人应用 ID 。
- 设置 MicrosoftAppPassword 为机器人注册时保存的 客户机密 。
根据机器人机密中的字符，可能需要对密码进行 XML 转义。例如， (&) 的任何和号都必须编码为 &。
```
{
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "ConnectionName": "",
```
在“解决方案资源管理器”中，转到 TeamsAppManifest 文件夹，打开 manifest.json 并设置 id ，并 botId 转到 在机器人 注册时保存的机器人应用 ID。有关详细信息，请参阅应用清单。

克隆 node-auth-sample。
在控制台中，转到项目：

cd samples/bot-teams-authentication/nodejs
安装模块

npm install
按如下所示更新 .env 配置：
- 设置 MicrosoftAppId 为机器人注册时保存的 机器人应用 ID 。
- 设置 MicrosoftAppPassword 为机器人注册时保存的 客户机密 。
- 将 connectionName 设置为标识提供程序连接的名称。根据机器人机密中的字符，可能需要对密码进行 XML 转义。例如， (&) 的任何和号都必须编码为 &。
```
MicrosoftAppId=
MicrosoftAppPassword=
connectionName=
MicrosoftAppType= MultiTenant # Set this to SingleTenant if you are using a single tenant app registration
MicrosoftAppTenantId= common # Set your tenantId here if you are using single tenant app registration.
```
在 teamsAppManifest 文件夹中，打开 manifest.json 并设置为Microsoft应用 ID，并botId设置为id在机器人注册时保存的机器人应用 ID。

从 GitHub 存储库克隆 py-auth-sample 。
更新 config.py：
- 设置 ConnectionName 为添加到机器人的 OAuth 连接设置的名称。
- 设置 MicrosoftAppId 为机器人的应用 ID，以及 MicrosoftAppPassword 为应用机密。
  
  根据机器人机密中的字符，可能需要对密码进行 XML 转义。例如， (&) 的任何和号都必须编码为 &。
```
APP_ID = os.environ.get("MicrosoftAppId", "")
APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
CONNECTION_NAME = os.environ.get("ConnectionName", "")
```

将机器人部署到 Azure

若要部署机器人，请按照如何将机器人部署到 Azure 中的步骤操作。

或者，在 Visual Studio 中，可以执行以下步骤：

在 Visual Studio 解决方案资源管理器中，选择并按住 (或右键单击) 项目名称。
在下拉菜单中，选择“ 发布”。
在显示的窗口中，选择“新建”链接。
在对话框窗口中，选择“ 应用服务 ”和“ 新建”。
选择“发布”按钮。
在下一个对话框窗口中，输入所需的信息。
选择“创建”。
如果部署成功完成，应会在 Visual Studio 中看到它。在默认浏览器中打开一个页面，其中显示 消息“机器人已准备就绪！”。 URL 类似于 https://botteamsauth.azurewebsites.net/。将其保存到文件。
在浏览器中，转到 Azure 门户。
检查资源组，机器人会与其他资源一起列出。下图是一个示例：
在资源组中，选择机器人注册名称（链接）。
在左侧面板中，选择“设置”。
在 “消息终结点 ”框中，输入刚刚获取的 URL， api/messages后跟。例如，https://botteamsauth.azurewebsites.net/api/messages。

注意

一个机器人只允许一个消息传送终结点。
选择左上角的“保存”按钮。

使用 Emulator 测试机器人

安装 Microsoft Bot Framework Emulator。有关详细信息，请参阅使用模拟器进行测试和调试。

若要使机器人示例登录正常工作，必须配置模拟器。

为身份验证配置 Emulator

如果机器人需要身份验证，则必须配置Emulator。配置：

启动 Emulator。
在模拟器中，选择左下角的齿轮图标⚙，或选择右上方的 “仿真器设置” 选项卡。
选中“使用版本 1.0 身份验证令牌”框。
输入 ngrok 工具的本地路径。 请参阅Bot Framework Emulator/ngrok 隧道集成 Wiki。有关详细工具信息，请参阅 ngrok。
启动 Emulator 时，按“运行 ngrok” 选中框。
选择“保存”按钮。

当机器人显示登录卡，并且用户选择登录按钮时，Emulator 将打开一个页面，用户可以使用该页面与身份验证提供程序一起登录。用户执行此操作后，提供程序将生成用户令牌并将其发送到机器人。之后，机器人可以代表用户执行操作。

测试本地机器人

配置身份验证机制后，可以执行实际的机器人测试。

例如，通过 Visual Studio 在计算机上本地运行机器人示例。
启动 Emulator。
选择“打开机器人”按钮。
在 机器人 URL 中，输入机器人的本地 URL。路径通常为 http://localhost:3978/api/messages。
在 “Microsoft应用 ID”中，输入机器人的应用 ID appsettings.json。
在 “Microsoft应用密码”中，输入 appsettings.json机器人的应用密码。
选择“连接”。
机器人启动并运行后，输入任何文本以显示登录卡。
选择“登录”按钮。
此时将显示一个弹出对话框“ 确认打开 URL ”，用于) (机器人的用户进行身份验证。
选择“确认”。
如果有要求，请选择适用用户的帐户。
根据用于模拟器的配置，可获取以下选项之一：
1. 使用登录验证码
  ✓ 此时会打开一个窗口，显示验证代码。
  • 将验证码复制并输入到聊天框中，以完成登录。
2. 使用身份验证令牌。
  • 你已根据凭据登录。
下图是登录后的机器人 UI 示例：
如果在机器人询问是否查看令牌时选择“是”，则会收到以下响应：
在输入聊天框中输入注销。它会释放用户令牌，在再次登录之前，机器人将无法代表你执行操作。

注意

机器人身份验证需要使用 Bot Connector 服务。该服务访问机器人的机器人注册信息。

测试部署机器人

在浏览器中，转到 Azure 门户。
查找资源组。
选择资源链接。将显示资源页。
在资源页中，选择“在 Web 聊天测试”。机器人启动并显示预定义的问候语。
在聊天框中键入任何内容。
选择“登录”框。
此时将显示一个弹出对话框“ 确认打开 URL ”，用于) (机器人的用户进行身份验证。
选择“确认”。
如果有要求，请选择适用用户的帐户。下图是登录后的机器人 UI 示例：
选择“是”按钮以显示身份验证令牌。下图是一个示例：
在输入聊天框中输入注销。

注意

如果登录时遇到问题，请尝试再次测试连接，如前面的步骤中所述。这可以重新创建身份验证令牌。使用 Azure 中的 Bot Framework Web 聊天客户端，可能需要多次登录，然后才能正确建立身份验证。

在 Teams 中安装和测试机器人

在机器人项目中，确保 TeamsAppManifest 文件夹包含 manifest.json 随附文件 outline.png 和 color.png 文件。
在“解决方案资源管理器”中，转到 TeamsAppManifest 文件夹。通过分配以下值进行编辑 manifest.json ：
1. 确保在机器人注册时收到的 机器人应用 ID 已分配到 id 和 botId分配。
2. 分配此值：validDomains: [ "token.botframework.com" ]。
选择并压缩manifest.json、outline.png文件和color.png文件。
打开 Microsoft Teams。
在左侧面板的底部，选择“应用图标”。
在右侧面板的底部，选择“上传自定义应用”。
转到文件夹并 TeamsAppManifest 上传压缩的清单。将显示以下窗口：
选择“添加到团队”按钮。
在下一个窗口中，选择要在其中使用机器人的团队。
选择“设置机器人”按钮。
选择左侧面板中 (●●●) 的三个点。然后选择“ 开发人员门户” 图标。
选择“清单编辑器 ”选项卡。应该会看到上传的机器人的图标。
此外，你应该能够在聊天列表中看到机器人作为联系人列出，可以使用该联系人与机器人交换消息。

在 Teams 中本地测试机器人

Teams 是完全基于云的产品。它要求它访问的所有服务都可使用 HTTPS 终结点从云中获取。因此，若要使机器人（示例）在 Teams 中工作，需要将代码发布到所选云中，或者使本地运行的实例可通过隧道工具在外部访问。建议使用 ngrok，它为在计算机上本地打开的端口创建外部可寻址 URL。若要设置 ngrok 以准备在本地运行 Teams 应用，请执行以下步骤：

在终端窗口中，转到已安装 ngrok.exe 目录。建议将 环境变量 路径设置为指向该变量。
例如，运行 ngrok http 3978 --host-header=localhost:3978。根据需要替换端口号。它会启动 ngrok 以侦听指定的端口。作为回报，它为你提供了一个外部可寻址的 URL，只要 ngrok 正在运行，该 URL 就有效。下图是一个示例：
复制类似于的转发 HTTPS 地址： https://dea822bf.ngrok.io/。
追加 /api/messages 以获取 https://dea822bf.ngrok.io/api/messages，这是计算机上本地运行的机器人 的消息终结点 ，可在 Teams 中的聊天中通过 Web 访问。
要执行的最后一步是更新已部署机器人的消息终结点。在该示例中，我们在 Azure 中部署了机器人。因此，让我们执行以下步骤：
1. 在浏览器中，转到 Azure 门户。
2. 选择 机器人注册。
3. 在左侧面板中，选择“设置”。
4. 在右侧面板的“消息传送”终结点框中，在示例 https://dea822bf.ngrok.io/api/messages 中输入 ngrok URL。
在本地启动机器人，例如在 Visual Studio 下调试模型。
使用 Bot Framework 门户的 测试 Web 聊天在本地运行时测试机器人。与 Emulator 一样，此测试不允许访问特定于 Teams 的功能。
在运行的终端窗口 ngrok 中，可以看到机器人与 Web 聊天客户端之间的 HTTP 流量。如果需要更详细的视图，请在浏览器窗口中输入 http://127.0.0.1:4040 从上一个终端窗口获取的视图。下图是一个示例：

注意

如果停止并重新启动 ngrok，URL 会更改。若要在项目中使用 ngrok，并且根据使用的功能，必须更新所有 URL 引用。

其他信息

TeamsAppManifest/manifest.json

此清单包含 Teams 与机器人连接所需的信息：

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.8/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "version": "1.0.0",
  "id": "",
  "developer": {
    "name": "TeamsBotAuth",
    "websiteUrl": "https://www.microsoft.com",
    "privacyUrl": "https://www.teams.com/privacy",
    "termsOfUseUrl": "https://www.teams.com/termsofuse"
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "name": {
    "short": "TeamsBotAuth",
    "full": "Teams Bot Authentication"
  },
  "description": {
    "short": "TeamsBotAuth",
    "full": "Teams Bot Authentication"
  },
  "accentColor": "#FFFFFF",
  "bots": [
    {
      "botId": "",
      "scopes": [
        "groupchat",
        "team"
      ],
      "supportsFiles": false,
      "isNotificationOnly": false
    }
  ],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [ "token.botframework.com" ]
}

使用身份验证时，Teams 的行为与其他频道不同。

处理调用活动

调用活动将发送到机器人，而不是其他通道使用的事件活动，这是通过对 ActivityHandler 进行子类化来完成的。

Bots/DialogBot.cs

    public class DialogBot<T> : TeamsActivityHandler where T : Dialog
    {
        protected readonly BotState ConversationState;
        protected readonly Dialog Dialog;
        protected readonly ILogger Logger;
        protected readonly BotState UserState;

        public DialogBot(ConversationState conversationState, UserState userState, T dialog, ILogger<DialogBot<T>> logger)
        {
            ConversationState = conversationState;
            UserState = userState;
            Dialog = dialog;
            Logger = logger;
        }

        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default(CancellationToken))
        {
            await base.OnTurnAsync(turnContext, cancellationToken);

            // Save any state changes that might have occurred during the turn.
            await ConversationState.SaveChangesAsync(turnContext, false, cancellationToken);
            await UserState.SaveChangesAsync(turnContext, false, cancellationToken);
        }

        protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            Logger.LogInformation("Running dialog with Message Activity.");

            // Run the Dialog with the new message Activity.
            await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
        }
    }
}

Bots/TeamsBot.cs

如果使用 OAuthPrompt，则必须将“调用活动”转发到对话框。

protected override async Task OnTeamsSigninVerifyStateAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with signin/verifystate from an Invoke Activity.");

    // The OAuth Prompt needs to see the Invoke Activity in order to complete the login process.

    // Run the Dialog with the new Invoke Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

TeamsActivityHandler.cs


protected virtual Task OnInvokeActivityAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    switch (turnContext.Activity.Name)
    {
        case "signin/verifyState":
            return OnSigninVerifyStateAsync(turnContext, cancellationToken);

        default:
            return Task.CompletedTask;
    }
}

protected virtual Task OnSigninVerifyStateAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    return Task.CompletedTask;
}

bots/dialogBot.js

const { TeamsActivityHandler } = require('botbuilder');
class DialogBot extends TeamsActivityHandler {
    /**
     *
     * @param {ConversationState} conversationState
     * @param {UserState} userState
     * @param {Dialog} dialog
     */
    constructor(conversationState, userState, dialog) {
        super();
        if (!conversationState) {
            throw new Error('[DialogBot]: Missing parameter. conversationState is required');
        }
        if (!userState) {
            throw new Error('[DialogBot]: Missing parameter. userState is required');
        }
        if (!dialog) {
            throw new Error('[DialogBot]: Missing parameter. dialog is required');
        }

        this.conversationState = conversationState;
        this.userState = userState;
        this.dialog = dialog;
        this.dialogState = this.conversationState.createProperty('DialogState');

        this.onMessage(async (context, next) => {
            console.log('Running dialog with Message Activity.');

            // Run the Dialog with the new message Activity.
            await this.dialog.run(context, this.dialogState);

            await next();
        });
    }

    /**
     * Override the ActivityHandler.run() method to save state changes after the bot logic completes.
     */
    async run(context) {
        await super.run(context);

        // Save any state changes. The load happened during the execution of the Dialog.
        await this.conversationState.saveChanges(context, false);

bots/teamsBot.js

如果使用 OAuthPrompt，则必须将“调用活动”转发到对话框。

const { DialogBot } = require('./dialogBot');

class TeamsBot extends DialogBot {
    /**
     *
     * @param {ConversationState} conversationState
     * @param {UserState} userState
     * @param {Dialog} dialog
     */
    constructor(conversationState, userState, dialog) {
        super(conversationState, userState, dialog);

        this.onMembersAdded(async (context, next) => {
            const membersAdded = context.activity.membersAdded;
            for (let cnt = 0; cnt < membersAdded.length; cnt++) {
                if (membersAdded[cnt].id !== context.activity.recipient.id) {
                    await context.sendActivity('Welcome to TeamsBot. Type anything to get logged in. Type \'logout\' to sign-out.');
                }
            }

            await next();
        });
    }
    
    async handleTeamsSigninVerifyState(context, query) {
        console.log('Running dialog with signin/verifystate from an Invoke Activity.');
        await this.dialog.run(context, this.dialogState);
    }

    async handleTeamsSigninTokenExchange(context, query) {

dialogs/mainDialog.js

在对话步骤中，使用 beginDialog 启动 OAuth 提示符，要求用户登录。

如果用户已登录，它将生成令牌响应事件，而不会提示用户。
否则，它会提示用户登录。 Azure 机器人服务在用户尝试登录后发送令牌响应事件。


async promptStep(stepContext) {
    try {

在以下对话步骤中，检查上一步的结果中是否存在令牌。如果它不为 null，则表示用户已成功登录。


async promptStep(stepContext) {
    try {
        return await stepContext.beginDialog(OAUTH_PROMPT);
    } catch (err) {
        console.error(err);
    }
}

async loginStep(stepContext) {
    // Get the token from the previous step. Note that we could also have gotten the
    // token directly from the prompt itself. There is an example of this in the next method.
    const tokenResponse = stepContext.result;
    if (!tokenResponse || !tokenResponse.token) {
        await stepContext.context.sendActivity('Login was not successful please try again.');

dialogs/logoutDialog.js

async interrupt(innerDc) {
    if (innerDc.context.activity.type === ActivityTypes.Message) {
        const text = innerDc.context.activity.text.toLowerCase();
        if (text === 'logout') {
            const userTokenClient = innerDc.context.turnState.get(innerDc.context.adapter.UserTokenClientKey);

            const { activity } = innerDc.context;
            await userTokenClient.signOutUser(activity.from.id, this.connectionName, activity.channelId);

            await innerDc.context.sendActivity('You have been signed out.');
            return await innerDc.cancelAllDialogs();
        }

bots/dialog_bot.py

def __init__(
    self,
    conversation_state: ConversationState,
    user_state: UserState,
    dialog: Dialog,
):
    if conversation_state is None:
        raise Exception(
            "[DialogBot]: Missing parameter. conversation_state is required"
        )
    if user_state is None:
        raise Exception("[DialogBot]: Missing parameter. user_state is required")
    if dialog is None:
        raise Exception("[DialogBot]: Missing parameter. dialog is required")

    self.conversation_state = conversation_state
    self.user_state = user_state
    self.dialog = dialog

async def on_turn(self, turn_context: TurnContext):
    await super().on_turn(turn_context)

    # Save any state changes that might have occurred during the turn.
    await self.conversation_state.save_changes(turn_context, False)
    await self.user_state.save_changes(turn_context, False)

async def on_message_activity(self, turn_context: TurnContext):
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

bots/teams_bot.py

如果使用 OAuthPrompt，则必须将“调用活动”转发到对话框。

async def on_teams_signin_verify_state(self, turn_context: TurnContext):
    # Run the Dialog with the new Token Response Event Activity.
    # The OAuth Prompt needs to see the Invoke Activity in order to complete the login process.
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

dialogs/main_dialog.py

在对话步骤中，使用 begin_dialog 启动 OAuth 提示符，要求用户登录。如果用户已登录，它将生成令牌响应事件，而不会提示用户。否则，它会提示用户登录。 Azure 机器人服务在用户尝试登录后发送令牌响应事件。

async def prompt_step(self, step_context: WaterfallStepContext) -> DialogTurnResult:
    return await step_context.begin_dialog(OAuthPrompt.__name__)

在以下对话步骤中，检查上一步的结果中是否存在令牌。如果它不为 null，则表示用户已成功登录。

async def login_step(self, step_context: WaterfallStepContext) -> DialogTurnResult:
    # Get the token from the previous step. Note that we could also have gotten the
    # token directly from the prompt itself. There is an example of this in the next method.
    if step_context.result:
        await step_context.context.send_activity("You are now logged in.")
        return await step_context.prompt(
            ConfirmPrompt.__name__,
            PromptOptions(
                prompt=MessageFactory.text("Would you like to view your token?")
            ),
        )

dialogs/logout_dialog.py

text = inner_dc.context.activity.text.lower()
if text == "logout":
    bot_adapter: BotFrameworkAdapter = inner_dc.context.adapter
    await bot_adapter.sign_out_user(inner_dc.context, self.connection_name)
    await inner_dc.context.send_activity("You have been signed out.")
    return await inner_dc.cancel_all_dialogs()

代码示例

本部分提供机器人身份验证 v3 SDK 示例。

示例名称	说明	.NET	Node.js	Python	清单
机器人身份验证	此示例演示如何在 Teams 机器人中开始进行身份验证。	View	View	View	View
选项卡、机器人和消息扩展 (ME) SSO	此示例演示 Tab、机器人和 ME 的 Microsoft Entra SSO - 搜索、操作、链接展开。	View	View	不适用	View

通过

向 Teams 机器人添加身份验证

先决条件

创建资源组

创建服务计划

创建 Azure 机器人资源注册

创建标识提供程序

配置标识提供程序连接，并将其注册到机器人

Microsoft Azure Active Directory (Azure AD) v1

Microsoft Azure Active Directory (Azure AD) v2

测试连接

准备机器人示例代码

将机器人部署到 Azure

使用 Emulator 测试机器人

为身份验证配置 Emulator

测试本地机器人

测试部署机器人

在 Teams 中安装和测试机器人

在 Teams 中本地测试机器人

其他信息

TeamsAppManifest/manifest.json

处理调用活动

TeamsActivityHandler.cs

代码示例

另请参阅

其他资源