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

向机器人添加身份验证

项目
12/20/2023

适用于：SDK v4

Azure AI 机器人服务 v4 SDK 简化了可访问需要用户身份验证的联机资源的机器人的开发。机器人不需要管理身份验证令牌，因为 Azure 使用 OAuth 2.0 根据每个用户的凭据生成令牌。机器人使用 Azure 生成的令牌来访问这些资源。用户可以通过这种方式访问受保护的资源，不必向机器人提供 ID 和密码，只需向受信任的标识提供者提供。

有关 Bot Framework 如何处理此类身份验证的概述，请参阅用户身份验证。

本文引用了两个示例。一个示例演示如何获取身份验证令牌。另一个示例较复杂，演示如何代表用户访问 Microsoft Graph。在这两种情况下，都可以使用 Azure AD v1 或 v2 作为标识提供者来获取机器人的 OAuth 标记。本文介绍了如何：

创建 Azure 机器人资源
创建 Microsoft Entra ID 标识提供者
使用机器人注册 Microsoft Entra ID 标识提供者
准备机器人代码

完成本文后，就会获得一个能够响应一些简单任务的机器人。以 Microsoft Graph 为例，你可以发送电子邮件，显示你是谁，并查看最近的电子邮件。无需发布机器人即可测试 OAuth 功能；但是，机器人需要有效的 Azure 应用 ID 和密码。

注意

Bot Framework JavaScript、C# 和 Python SDK 将继续受支持，但 Java SDK 即将停用，最终长期支持将于 2023 年 11 月结束。

使用 Java SDK 构建的现有机器人将继续正常运行。

对于新的机器人生成，请考虑使用 Power Virtual Agents 并参阅选择合适的聊天机器人解决方案。

有关详细信息，请参阅机器人构建的未来。

网络聊天和 Direct Line 注意事项

重要

在使用 Web 聊天控件连接到机器人时，需要使用 Direct Line（已启用增强身份验证）来降低安全风险。有关详细信息，请参阅 Direct Line 增强身份验证。

先决条件

了解机器人基础知识、管理状态、对话库、如何实现顺序聊天流，以及如何重复使用对话。
具备 Azure 和 OAuth 2.0 开发方面的知识。
适用于 .NET 的 Visual Studio 2017 或更高版本。
适用于 JavaScript 的 Node.js。
适用于 Python 的 Python 3.8+。

下面列出的示例之一。

示例	BotBuilder 版本	演示
C# 或 JavaScript 或 Java 或 Python 中的“身份验证”	v4	OAuthCard 支持
C# 或 JavaScript 或 Java 或 Python 中的“Microsoft Graph 身份验证”	v4	使用 OAuth 2.0 的 Microsoft Graph API 支持
C# 或 JavaScript 或 Java 或 Python 中的“Microsoft Teams 身份验证”	v4	使用 OAuth 2.0 的 Microsoft Graph API 支持

若要运行本文中引用的示例，你需要：

要在 Azure 中注册机器人资源的 Microsoft Entra ID 应用程序。此应用程序允许机器人访问受保护的外部资源，如 Microsoft Graph。它还允许用户通过多个频道（如 Web Chat）与机器人通信。
作为标识提供者的单独 Microsoft Entra ID 应用程序。此应用程序提供在机器人与受保护资源之间建立 OAuth 连接所需的凭据。请注意，本文使用 Active Directory 作为标识提供者。另外还支持许多其他的提供者。

重要

每当你在 Azure 中注册机器人时，系统都会为它分配一个 Microsoft Entra ID 应用程序。但是，此应用程序可确保从通道到机器人的访问的安全性。对于每个受保护的外部资源，如果希望机器人代表用户对其进行访问，则需要一个额外的 Microsoft Entra ID 应用程序。

创建资源

创建 Azure 机器人资源，以便将机器人注册到 Azure AI 机器人服务。

提示

无法创建新的 Web 应用机器人和机器人通道注册资源；但是，已配置和部署的任何此类现有资源将继续有效。使用（从 SDK 版本 4.14.1.2 或更高版本创建的）VSIX 或 Yeoman 模板创建的机器人包含将生成 Azure 机器人资源的 ARM 模板。

转到 Azure 门户。
在右窗格中，选择“创建资源”。
在搜索框中，键入 bot，然后按 Enter。
选择 Azure 机器人卡。
选择创建。
在必填字段中输入值，并检查和更新设置。
1. 在“项目详细信息”下提供信息。选择机器人是具有全局数据驻留还是本地数据驻留。目前，本地数据驻留功能可用于“westeurope”和“centralindia”区域中的资源。有关详细信息，请参阅 Azure AI 机器人服务中的区域化。
2. 在“Microsoft 应用 ID”下提供信息。选择如何在 Azure 中管理机器人标识，以及是创建新的标识还是使用现有标识。
选择“查看 + 创建”。
验证通过后，选择“创建”。
部署完成后，请选择“转到资源”。应会看到所选资源组中列出的机器人和相关资源。
如果还没有 Bot Framework SDK，请选择“从 GitHub 下载”，了解如何使用首选语言的包。

现在，你已经准备好使用 Bot Framework SDK 生成机器人。

提示

当 Azure 使用新的应用 ID 创建新的单租户或多租户 Azure 机器人资源时，它还会生成密码。

机器人标识信息

按照以下步骤将标识信息添加到机器人的配置文件。该文件因创建机器人所用的编程语言而异。

重要

Bot Framework SDK 的 Java 版本仅支持多租户机器人。 Bot Framework SDK 的 Python 版本支持多租户和单租户机器人。 C# 和 JavaScript 版本支持所有三种应用程序类型来管理机器人的标识。

语言	文件名	备注
C#	appsettings.json	支持所有三种应用程序类型来管理机器人的标识。
JavaScript	.env	支持所有三种应用程序类型来管理机器人的标识。
Java	application.properties	仅支持多租户机器人。
Python	config.py	支持多租户和单租户机器人。将属性作为参数 `os.environ.get` 提供给方法调用。

需要添加的标识信息取决于机器人的应用程序类型。提供配置文件中的以下值。

仅适用于 C# 和 JavaScript 机器人。

属性	值
`MicrosoftAppType`	`UserAssignedMSI`
`MicrosoftAppId`	用户分配的托管标识的客户端 ID。
`MicrosoftAppPassword`	不适用。此处为用户分配的托管标识机器人保留空白。
`MicrosoftAppTenantId`	用户分配的托管标识的租户 ID。

仅适用于 C#、JavaScript 和 Python 机器人。

属性	值
`MicrosoftAppType`	`SingleTenant`
`MicrosoftAppId`	机器人的应用 ID。
`MicrosoftAppPassword`	机器人的应用密码。
`MicrosoftAppTenantId`	机器人的应用租户 ID。

适用于使用所有编程语言的机器人：C#、JavaScript、Java 和 Python。

属性	值
`MicrosoftAppType`	`MultiTenant`
`MicrosoftAppId`	机器人的应用 ID。
`MicrosoftAppPassword`	机器人的应用密码。
`MicrosoftAppTenantId`	不适用。如果是多租户机器人则留空。

若要更新应用服务

如果机器人具有现有的App 服务资源（Web 应用），并且机器人是用户分配的托管标识应用程序，则可能需要更新机器人的应用服务：

转到机器人 Web 应用的“应用程序服务”边栏选项卡。
在“设置”下选择“标识”。
在“标识”边栏选项卡上，选择“用户分配”选项卡和“添加”（+）。
在“添加用户分配的托管标识”边栏选项卡上：
1. 选择订阅。
2. 对于用户分配的托管标识，请选择机器人的托管标识。如果自动生成托管标识，它将与机器人同名。
3. 选择“添加”以将此标识用于机器人。

若要获取应用或租户 ID

若要获取机器人的应用或租户 ID：

转到机器人的“Azure 机器人”资源边栏选项卡。
转到机器人的“配置”边栏选项卡。在此边栏选项卡中，可以复制机器人的“Microsoft 应用 ID”或“应用租户 ID”。

若要生成新密码

单租户和多租户机器人具有某些操作所需的应用机密或密码。 Azure AI 机器人服务会隐藏机器人机密。但是，机器人的应用服务资源的所有者可以生成新密码：

转到机器人的“Azure 机器人”资源边栏选项卡。
转到机器人的“配置”边栏选项卡。
选择“管理”，在 Microsoft 应用 ID 旁边，转到应用服务的“证书 + 机密”边栏选项卡。
按照边栏选项卡上的说明创建新的客户端密码，并将值记录在安全的位置。

Microsoft Entra ID 标识服务

Azure AD 是一个云标识服务，你可以通过它生成应用程序，以便使用 OAuth 2.0 之类的行业标准协议安全地登录用户。

可以使用以下两个标识服务之一：

Microsoft Entra ID 开发人员平台 (v1.0)。也称 Azure AD v1 终结点，用于生成应用，方便用户使用 Microsoft 工作或学校帐户安全地登录。有关详细信息，请查看面向开发人员的 Microsoft Entra ID (v1.0) 概述。
Microsoft 标识平台 (v2.0)。也称 Microsoft Entra ID 端点，这是 Azure AD 平台 (v1.0) 的演进版。可以通过它来生成应用程序，以便登录到所有 Microsoft 标识提供者，并获取令牌来调用 Microsoft API（例如 Microsoft Graph 或开发人员生成的其他 API）。有关详细信息，请参阅 Microsoft 标识平台 (v2.0) 概述。

若要了解 v1 和 v2 终结点的差异，请参阅为什么要更新到 Microsoft 标识平台 (v2.0)？。有关完整信息，请参阅 Microsoft 标识平台（旧称针对开发人员的 Microsoft Entra ID）。

创建 Microsoft Entra ID 标识提供者

本部分介绍如何创建使用 OAuth 2.0 对机器人进行身份验证的 Microsoft Entra ID 标识提供者。可以使用 Azure AD v1 或 Microsoft Entra ID 端点。

提示

你需要在租户中创建和注册 Microsoft Entra ID 应用程序，在租户中你可以同意应用程序请求的委托权限。

在 Azure 门户中打开 Microsoft Entra ID 面板。如果进入了错误的租户，请选择“切换目录”切换到正确的租户。（有关创建租户方法的信息，请参阅访问门户并创建租户。）
打开“应用注册”面板。
在“应用注册”面板中，选择“新建注册”。
填写必填字段并创建应用注册。
1. 为应用程序命名。
2. 为应用程序选择“支持的帐户类型”。（这些选项中的任何一个都可以用于此示例。）
3. 对于“重定向 URI”，请选择 Web，并将 URL 设置为受支持的 OAuth 重定向 URL 之一。
4. 选择“注册”。
  - 创建应用以后，Azure 会显示应用的“概览”页。
  - 记录“应用程序(客户端) ID”值。稍后在创建连接字符串并将 Microsoft Entra ID 提供程序注册到机器人注册时，将此值用作“客户端 ID”。
  - 记录“目录(租户) ID”值。可以用它将此提供商应用程序注册到机器人。
在导航窗格中，选择“ 证书和机密 ”，为应用程序创建机密。
1. 在“客户端机密”下，选择“新建客户端密钥” 。
2. 添加一项说明，用于将此机密与可能需要为此应用创建的其他机密（例如 bot login）区别开来。
3. 对于“过期”，请选择机密过期的时长。
4. 选择添加。
5. 在离开 证书和机密之前，请记录机密。稍后在将 Microsoft Entra ID 应用程序注册到机器人时，需将此值用作“客户端机密”。
在导航窗格中，选择“API 权限”打开“API 权限”面板。最佳做法是为应用显式设置 API 权限。
1. 选择“添加权限”，显示“请求 API 权限”窗格。
2. 对于此示例，请选择“Microsoft API”和“Microsoft Graph”。
3. 选择“委托的权限”，确保选中所需权限。本示例需要这些权限。
  
  注意
  
  标记为“需要管理员同意”的任何权限都需要用户和租户管理员登录，因此对于机器人来说，请尽量避免这些操作。
  - openid
  - profile
  - Mail.Read
  - Mail.Send
  - User.Read
  - User.ReadBasic.All
4. 选择“添加权限”。（用户首次通过机器人访问此应用时，需授予许可。）

现在你已配置 Microsoft Entra ID 应用程序。

注意

创建连接字符串并在机器人注册中注册标识提供者时分配“应用程序（客户端）ID”和“客户端密码”。请参阅下一节。

使用机器人注册 Microsoft Entra ID 标识提供者

下一步是向机器人注册标识提供者。

Microsoft Entra ID
Azure AD v1

在 Azure 门户中，打开机器人的“Azure 机器人”资源页。
选择“设置”。
在页面底部附近的“OAuth 连接设置”下，选择“添加设置”。
按如下所示填写表单：
1. Name。输入连接的名称。在机器人代码中会用到。
2. 服务提供商。选择 Microsoft Entra ID 以显示特定于 Microsoft Entra ID 的字段。
3. “客户端 ID”。输入为 Microsoft Entra ID 标识提供者记录的应用程序（客户端）ID。
4. 客户端密码。输入为 Microsoft Entra ID 标识提供者记录的机密。
  
  提示
  
  如果要使用证书，可以选择“使用证书的 AAD v2”提供程序。需要向机器人服务令牌存储 (appid: 5b404cf4-a79d-4cfe-b866-24bf8e1a4921) 授予获取证书的权限。
5. 令牌交换 URL。将它留空，因为它仅用于 Microsoft Entra ID 中的 SSO。
6. 租户 ID。请输入此前为 Microsoft Entra ID 应用记录的“目录（租户）ID”，或者输入 common，具体取决于在创建 Azure DD 应用时所选的受支持帐户的类型。若要确定要分配的值，请遵循以下条件：
  - 如果已选择“仅在此组织目录中的帐户 (仅 Microsoft - 单一租户)”，请在创建 Microsoft Entra ID 应用时，输入此前为 Microsoft Entra ID 应用记录的租户 ID。
  - 但是，如果选择了“任何组织目录中的帐户 (任何 Microsoft Entra ID 目录 - 多租户和个人 Microsoft 帐户，例如 Xbox、Outlook.com)”或“任何组织目录中的帐户 (Microsoft Entra ID 目录 - 多租户)”，请输入 common 而不是租户 ID。否则，Microsoft Entra ID 应用会通过租户验证谁的 ID 已选中，并排除个人 Microsoft 帐户。
  此租户将与可进行身份验证的用户相关联。有关详细信息，请参阅 Microsoft Entra ID 中的租户。
7. 对于“范围”，输入从应用程序注册中选择的权限的名称。对于测试，可只输入：openid profile。
  
  注意
  
  对于 Microsoft Entra ID，“范围”字段的值区分大小写，以空格分隔。
选择“保存”。

在 Azure 门户中，导航到机器人的资源页。
选择“设置”。
在页面底部附近的“OAuth 连接设置”下，选择“添加设置”。
按如下所示填写表单：
1. 对于“名称”，输入连接的名称。稍后将在机器人代码中使用此名称。
2. 对于“服务提供方”，选择 Microsoft Entra ID。选择该选项后，将显示特定于 Microsoft Entra ID 的字段。
3. 对于“客户端 ID”，请输入为 Azure AD v1 应用程序记录的应用程序（客户端）ID。
4. 对于“客户端机密”，请输入所创建的机密，以便为机器人授予访问 Microsoft Entra ID 应用的权限。
5. 对于“授权类型”，输入 authorization_code。
6. 对于“登录 URL”，输入 https://login.microsoftonline.com。
7. 对于“租户 ID”，请输入此前为 Microsoft Entra ID 应用记录的目录（租户）ID，或者输入 common，具体取决于在创建 ADD 应用时所选的受支持帐户的类型。若要确定要分配的值，请遵循以下条件：
  - 如果已选择“仅在此组织目录中的帐户 (仅 Microsoft - 单一租户)”，请在创建 Microsoft Entra ID 应用时，输入此前为 Microsoft Entra ID 应用记录的租户 ID。
  - 但是，如果选择了“任何组织目录中的帐户 (任何 Microsoft Entra ID 目录 - 多租户和个人 Microsoft 帐户，例如 Xbox、Outlook.com)”或“任何组织目录中的帐户 (Microsoft Entra ID 目录 - 多租户)”，请输入 common 而不是租户 ID。否则，Microsoft Entra ID 应用会通过租户验证谁的 ID 已选中，并排除个人 MS 帐户。
  此租户将与可进行身份验证的用户相关联。有关详细信息，请参阅 Microsoft Entra ID 中的租户。
8. 对于资源 URL，输入 https://graph.microsoft.com/。
9. 将“作用域”留空。
选择“保存”。

注意

这些值让应用程序可以通过 Microsoft Graph API 访问 Office 365 数据。此外，“令牌交换 URL”应留空，因为它仅用于 Microsoft Entra ID 中的 SSO。

测试您的连接

选择连接项打开创建的连接。
选择“服务提供方连接设置”窗格顶部的“测试连接”。
第一次进行此操作时，应该会打开一个新的浏览器选项卡（其中列出了应用请求的权限）并提示你接受。
选择“接受”。
然后，应会重定向到“<连接名称 > 的连接测试成功”页。

现在可以在机器人代码中使用此连接名称检索用户令牌。

准备机器人代码

需要机器人的应用 ID 和密码才能完成此过程。

从 GitHub 存储库克隆要使用的示例：机器人身份验证或 Microsoft Graph 的机器人身份验证。

更新 appsettings.json：

将 ConnectionName 设置为要添加到机器人的 OAuth 连接设置的名称。
将 MicrosoftAppId 和 MicrosoftAppPassword 设置为机器人的应用 ID 和应用机密。

根据机器人机密中的字符，可能需要 XML 转义密码。例如，任何连字符 (&) 都需要编码为 &。

{
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",
  "ConnectionName": ""
}

若要配合公有云中的数据驻留在机器人中使用 OAuth，必须在 appsettings 中添加以下配置

"OAuthUrl": "<Regional-OAuth-Uri>",
"ToChannelFromBotOAuthScope": "https://api.botframework.com",
"ToChannelFromBotLoginUrlTemplate": "https://api.botframework.com",
"PublicAzureChannel": "https://api.botframework.com",
"ToBotFromChannelOpenIdMetadataUrl": "https://login.botframework.com/v1/.well-known/openidconfiguration",
"ToBotFromEmulatorOpenIdMetadataUrl": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
"ToBotFromChannelTokenIssuer": "https://api.botframework.com",
"ToChannelFromBotLoginUrl": "https://login.microsoftonline.com/botframework.com",

其中 <Regional-OAuth-Url> 是以下 URI 之一：

URI	说明
`https://europe.api.botframework.com`	对于在欧洲具有数据驻留的公有云机器人。
`https://unitedstates.api.botframework.com`	对于在美国具有数据驻留的公有云机器人。
`https://india.api.botframework.com`	对于在印度拥有数据驻留的公有云机器人。

更新 Startup.cs：

若要在“非公有 Azure 云”（如政府云）中使用 OAuth，必须在 Startup.cs 文件中添加以下代码。

string uri = "<uri-to-use>";
MicrosoftAppCredentials.TrustServiceUrl(uri);
OAuthClientConfig.OAuthEndpoint = uri;

其中 <uri-to-use> 是以下 URI 之一：

URI	说明
`https://api.botframework.azure.us`	对于没有数据驻留的美国政府云机器人。
`https://api.botframework.com`	对于没有数据驻留的公有云机器人。这是默认 URI，不需要更改 Startup.cs。

从 GitHub 存储库克隆要使用的内容：机器人身份验证或 Microsoft Graph 的机器人身份验证。
更新 .env：
- 将 connectionName 设置为要添加到机器人的 OAuth 连接设置的名称。
- 将 MicrosoftAppId 和 MicrosoftAppPassword 值设置为机器人的应用 ID 和应用机密。
  
  根据机器人机密中的字符，可能需要 XML 转义密码。例如，任何连字符 (&) 都需要编码为 &。
```
MicrosoftAppType=
MicrosoftAppId=
MicrosoftAppPassword=
MicrosoftAppTenantId=
connectionName=
```

从 GitHub 存储库克隆要使用的示例：机器人身份验证或 Microsoft Graph 的机器人身份验证。
更新 application.properties：
- 将 ConnectionName 设置为要添加到机器人的 OAuth 连接设置的名称。
- 将 MicrosoftAppId 和 MicrosoftAppPassword 设置为机器人的应用 ID 和应用机密。
```
MicrosoftAppId=
MicrosoftAppPassword=
server.port=3978
ConnectionName=
```

从 GitHub 存储库克隆要使用的示例：机器人身份验证或 Microsoft Graph 的机器人身份验证。

更新 config.py：

将 ConnectionName 设置为要添加到机器人的 OAuth 连接设置的名称。
将 MicrosoftAppId 和 MicrosoftAppPassword 设置为机器人的应用 ID 和应用机密。

根据机器人机密中的字符，可能需要 XML 转义密码。例如，任何连字符 (&) 都需要编码为 &。

#!/usr/bin/env python3
# Copyright (c) Microsoft Corporation. All rights reserved.
# Licensed under the MIT License.

import os

""" Bot Configuration """


class DefaultConfig:
    """ Bot Configuration """

    PORT = 3978
    APP_ID = os.environ.get("MicrosoftAppId", "")
    APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
    APP_TYPE = os.environ.get("MicrosoftAppType", "MultiTenant")
    APP_TENANTID = os.environ.get("MicrosoftAppTenantId", "")
    CONNECTION_NAME = os.environ.get("ConnectionName", "")

若要获取“Microsoft 应用 ID”和“Microsoft 应用密码”值，请参阅获取注册密码。

注意

现在即可将此机器人代码发布到 Azure 订阅（右键单击该项目并选择“发布”），但本文不需要这样做。需要设置一个发布配置，以便使用在 Azure 门户中配置机器人时使用的应用程序和托管计划。

使用 Emulator 测试机器人

安装 Bot Framework Emulator（如果尚未安装）。另请参阅使用模拟器进行调试。

为了使机器人示例登录正常工作，你必须按照配置模拟器以进行身份验证中的说明，配置模拟器。

测试

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

注意

考虑到机器人示例的实现方式，系统可能会要求你输入幻码。此幻码是 RFC#7636 的一部分，用于添加额外的安全元素。删除幻码会增加安全风险。这可以通过启用增强身份验证的 Direct Line 来缓解。有关详细信息，请参阅 Bot Framework 增强身份验证。

在计算机本地运行机器人示例。
启动模拟器。
在连接到机器人时，需提供机器人的应用 ID 和密码。
- 你可从 Azure 应用注册获取应用 ID 和密码。这些值与你在 appsettings.json 或 .env 文件中分配给机器人应用的值相同。在 Emulator 中，可以在配置文件中或首次连接到机器人时分配这些值。
- 如果以前需要对机器人代码中的密码进行 XML 转义，则还需在此处进行该操作。
键入 help 查看机器人的可用命令列表，然后测试身份验证功能。
登录后，在注销前都无需再次提供凭据。
要注销并取消身份验证，请键入 logout。

注意

机器人身份验证需要使用 Bot Connector 服务。该服务从 Azure 机器人资源访问信息。

身份验证示例

在机器人身份验证示例中，此对话被设计为在用户登录后检索用户令牌。

与身份验证示例机器人的示例对话。

Microsoft Graph 身份验证示例

在“Microsoft Graph 的机器人身份验证”示例中，此对话被设计为在用户登录后接受有限的一组命令。

与 Microsoft Graph 身份验证示例机器人的示例对话。

其他信息

如果用户要求机器人执行某项操作，而该操作要求机器人让用户登录，则机器人可以使用 OAuthPrompt 来开始检索给定连接的令牌。 OAuthPrompt 创建一个令牌检索流，其中包含：

查看 Azure AI 机器人服务是否已经有一个适用于当前用户和连接的令牌。如果有令牌，则会返回令牌。
如果 Azure AI 机器人服务没有缓存的令牌，则会创建 OAuthCard，这是一个可供用户选择的登录按钮。
用户选择 OAuthCard 登录按钮以后，Azure AI 机器人服务会向机器人直接发送用户的令牌，或者会向用户提供一个可在聊天窗口中输入的 6 位数身份验证代码。
如果 Azure 机器人服务向用户提供身份验证代码，则机器人会用此身份验证代码来交换获取用户的令牌。

以下部分描述示例如何执行某些常见的身份验证任务。

使用 OAuth 提示来登录用户并获取令牌

C# 示例的体系结构关系图。

Dialogs\MainDialog.cs

将 OAuth 提示添加到其构造函数中的 MainDialog。在这里，连接名称的值已从 appsettings.json 文件中检索。

AddDialog(new OAuthPrompt(
    nameof(OAuthPrompt),
    new OAuthPromptSettings
    {
        ConnectionName = ConnectionName,
        Text = "Please Sign In",
        Title = "Sign In",
        Timeout = 300000, // User has 5 minutes to login (1000 * 60 * 5)
    }));

在对话步骤中，请使用 BeginDialogAsync 来启动 OAuth 提示，该提示要求用户登录。

如果用户已登录，则会在不提示用户的情况下生成一个令牌响应事件，
否则会提示用户登录。 Azure AI 机器人服务会在用户尝试登录后发送令牌响应事件。

return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

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

// 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.
var tokenResponse = (TokenResponse)stepContext.Result;

JavaScript 示例的体系结构关系图。

dialogs/mainDialog.js

将 OAuth 提示添加到其构造函数中的 MainDialog。在这里，连接名称的值已从 .env 文件中检索。

this.addDialog(new WaterfallDialog(MAIN_WATERFALL_DIALOG, [
    this.promptStep.bind(this),
    this.loginStep.bind(this),
    this.displayTokenPhase1.bind(this),
    this.displayTokenPhase2.bind(this)
]));

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

如果用户已登录，则会在不提示用户的情况下生成一个令牌响应事件，
否则会提示用户登录。 Azure AI 机器人服务会在用户尝试登录后发送令牌响应事件。

const tokenResponse = stepContext.result;

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

await stepContext.context.sendActivity('Login was not successful please try again.');
return await stepContext.endDialog();

Java 示例的体系结构关系图。

MainDialog.java

将 OAuth 提示添加到其构造函数中的 MainDialog。在这里，连接名称的值已从 application.properties 文件中检索。

OAuthPromptSettings settings = new OAuthPromptSettings();
settings.setText("Please Sign In");
settings.setTitle("Sign In");
settings.setConnectionName(configuration.getProperty("ConnectionName"));
settings.setTimeout(300000); // User has 5 minutes to login (1000 * 60 * 5)

addDialog(new OAuthPrompt("OAuthPrompt", settings));

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

如果用户已登录，则会在不提示用户的情况下生成一个令牌响应事件，
否则会提示用户登录。 Azure AI 机器人服务会在用户尝试登录后发送令牌响应事件。

return stepContext.beginDialog("OAuthPrompt");

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

// Get the token from the previous step. Note that we could also have gotten the
// token directly from the prompt itself. There instanceof an example of this in the next method.
TokenResponse tokenResponse = (TokenResponse) stepContext.getResult();

Python 示例的体系结构关系图。

dialogs/main_dialog.py

将 OAuth 提示添加到其构造函数中的 MainDialog。在这里，连接名称的值已从 config.py 文件中检索。

self.add_dialog(
    WaterfallDialog(
        "WFDialog",
        [
            self.prompt_step,
            self.login_step,
            self.display_token_phase1,
            self.display_token_phase2,
        ],
    )
)

在对话步骤中，请使用 begin_dialog 来启动 OAuth 提示，该提示要求用户登录。

如果用户已登录，则会在不提示用户的情况下生成一个令牌响应事件，
否则会提示用户登录。 Azure AI 机器人服务会在用户尝试登录后发送令牌响应事件。

return await step_context.begin_dialog(OAuthPrompt.__name__)

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

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?")
        ),
    )

await step_context.context.send_activity(
    "Login was not successful please try again."
)

等待 TokenResponseEvent

启动 OAuth 提示时，它会等待令牌响应事件，目的是从中检索用户的令牌。

Bots\AuthBot.cs

AuthBot 派生自 ActivityHandler，会显式处理令牌响应事件活动。在这里，我们会继续活动对话，这样 OAuth 提示就能处理事件并检索令牌。

protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with Token Response Event Activity.");

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

bots/authBot.js

AuthBot 派生自 ActivityHandler，会显式处理令牌响应事件活动。在这里，我们会继续活动对话，这样 OAuth 提示就能处理事件并检索令牌。

await this.dialog.run(context, this.dialogState);

await next();

AuthBot.java

AuthBot 派生自 Dialog，会显式处理令牌响应事件活动。在这里，我们会继续活动对话，这样 OAuth 提示就能处理事件并检索令牌。

@Override
protected CompletableFuture<Void> onTokenResponseEvent(TurnContext turnContext) {
    LoggerFactory.getLogger(AuthBot.class).info("Running dialog with Token Response Event Activity.");

    // Run the Dialog with the new Token Response Event Activity.
    return Dialog.run(dialog, turnContext, conversationState.createProperty("DialogState"));
}

bots/auth_bot.py

AuthBot 会显式处理令牌响应事件活动。在这里，我们会继续活动对话，这样 OAuth 提示就能处理事件并检索令牌。

async def on_token_response_event(self, turn_context: TurnContext):
    # Run the Dialog with the new Token Response Event Activity.
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

注销用户

最佳做法是让用户显式退出登录，而不是等待连接超时。

Dialogs\LogoutDialog.cs

private async Task<DialogTurnResult> InterruptAsync(DialogContext innerDc, CancellationToken cancellationToken = default(CancellationToken))
{
    if (innerDc.Context.Activity.Type == ActivityTypes.Message)
    {
        var text = innerDc.Context.Activity.Text.ToLowerInvariant();

        if (text == "logout")
        {
            // The UserTokenClient encapsulates the authentication processes.
            var userTokenClient = innerDc.Context.TurnState.Get<UserTokenClient>();
            await userTokenClient.SignOutUserAsync(innerDc.Context.Activity.From.Id, ConnectionName, innerDc.Context.Activity.ChannelId, cancellationToken).ConfigureAwait(false);

            await innerDc.Context.SendActivityAsync(MessageFactory.Text("You have been signed out."), cancellationToken);
            return await innerDc.CancelAllDialogsAsync(cancellationToken);
        }
    }

    return null;
}

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();
        }
    }

LogoutDialog.java

private CompletableFuture<DialogTurnResult> interrupt(DialogContext innerDc) {
    if (innerDc.getContext().getActivity().getType().equals(ActivityTypes.MESSAGE)) {
        String text = innerDc.getContext().getActivity().getText().toLowerCase();

        if (text.equals("logout")) {
            // The bot adapter encapsulates the authentication processes.
            BotFrameworkAdapter botAdapter = (BotFrameworkAdapter) innerDc.getContext().getAdapter();
            botAdapter.signOutUser(
                innerDc.getContext(),
                getConnectionName(),
                innerDc.getContext().getActivity().getFrom().getId())
                    .thenApply(result -> innerDc.getContext().sendActivity(MessageFactory.text("You have been signed out."))
                    .thenApply(sendResult -> null));
            return innerDc.cancelAllDialogs();
        }
    }

    return CompletableFuture.completedFuture(null);
}

dialogs/logout_dialog.py

async def _interrupt(self, inner_dc: DialogContext):
    if inner_dc.context.activity.type == ActivityTypes.message:
        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()

添加 Teams 身份验证

OAuth 在 Teams 中处理的方式与其他通道不同。 Teams 身份验证机器人示例（在 C#、JavaScript、Java 或 Python 中）演示如何正确实现 Teams 的身份验证。

其他阅读材料

其他 Bot Framework 资源包含其他支持资源的链接。
Bot Framework SDK 存储库包含 Bot Builder SDK 相关的存储库、示例、工具和规范的详细信息。

向机器人添加身份验证

网络聊天和 Direct Line 注意事项

先决条件

创建资源

机器人标识信息

若要更新应用服务

若要获取应用或租户 ID

若要生成新密码

Microsoft Entra ID 标识服务

创建 Microsoft Entra ID 标识提供者

使用机器人注册 Microsoft Entra ID 标识提供者

测试您的连接

准备机器人代码

使用 Emulator 测试机器人

测试

身份验证示例

Microsoft Graph 身份验证示例

其他信息

使用 OAuth 提示来登录用户并获取令牌

等待 TokenResponseEvent

注销用户

添加 Teams 身份验证

其他阅读材料

其他资源