向助手添加最终用户身份验证

重要提示

继在生成式人工智能的重大投资和跨 Microsoft Copilot 的增强集成之后，Power Virtual Agents 功能和特性现已成为 Microsoft Copilot Studio 的一部分。

在我们更新文档和培训内容时，一些文章和截图可能会参考 Power Virtual Agents。

可以直接在助手对话内启用用户身份验证。 用户身份验证意味着您可以在变量中获取用户的基本属性（如名称和 ID），还可以提示用户使用身份验证节点登录、检索该用户的用户令牌，然后使用该令牌从后端系统检索用户的信息。

备注

在 Web 应用和 Microsoft Teams 中创建的助手将身份验证预先配置为使用仅用于 Teams 和 Power Apps 身份验证。

您还可以配置单一登录 (SSO)，让您的用户无需手动登录。 有关详细信息，请参阅为 Web 配置 SSO。

先决条件

• 使用变量
• 配置最终用户身份验证。

Web 应用程序

向主题添加用户身份验证，以便允许客户直接在对话中登录。 然后，您可以使用用户变量个性化对话，或代表用户访问后端系统。

使用 Microsoft Entra ID 配置手动身份验证

在您的主题中使用身份验证之前，您需要使用 Microsoft Entra ID 配置用户身份验证。

1. 按照使用 Microsoft Entra ID 配置用户身份验证中的说明进行操作。
2. 返回到本文。

使用“登录系统”主题添加用户身份验证

当您创建助手时，Microsoft Copilot Studio 会自动添加一个名为登录的系统主题。 若要使用，您必须将您的助手身份验证设置为手动，并且要求用户登录。 当客户开始与助手对话时，登录主题会触发，并提示用户登录。 您可以酌情针对您的助手自定义登录主题。

1. 在导航菜单中的设置下面，选择安全性。

2. 选择身份验证磁贴。

3. 选择手动（对于自定义网站），然后选择要求用户登录。

   

   

向自定义主题添加用户身份验证

登录主题会在对话开始时对用户进行身份验证。 若要允许用户以后登录，可以将身份验证节点添加到任何自定义主题中。

当客户输入其用户名和密码时，可能会提示他们输入验证码。 用户登录后，将不会再次提示他们，即使他们到达另一个身份验证节点也不例外。

1. 在导航菜单中的设置下面，选择安全性。

2. 选择身份验证磁贴。

3. 关闭要求用户登录。

4. 在导航菜单中，选择主题，然后打开您要向其中添加身份验证的主题。

5. 选择添加节点 (+)，再选择调用操作，然后选择身份验证。

6. 使用配置有标识提供者的用户测试主题。

提示

针对登录成功和失败创建登录路径很重要。 登录可能由于多种原因而失败，包括标识提供者的登录体验错误。

身份验证变量

为助手配置用户身份验证后，您可以在主题中使用身份验证变量。 下表根据您选择的身份验证选项比较这些变量的可用性：

身份验证变量	无身份验证	仅适用于 Teams 和 Power Apps	手动
User.DisplayName	不可用	空闲	空闲
User.FirstName	不可用	空闲	空闲
User.LastName	不可用	空闲	空闲
User.PrincipalName	不可用	空闲	空闲
User.Email	不可用	空闲	空闲
User.Id	不可用	空闲	空闲
User.IsLoggedIn	不可用	空闲	空闲
User.AccessToken	不可用	不可用	空闲
SignInReason	不可用	空闲	空闲

User.DisplayName

警告

不保证此变量包含值。 通过标识提供者的用户进行测试，以确保您的主题可以正确运行。

User.DisplayName 变量包含存储在标识提供者中的显示名称。 请使用此变量来问候或引用最终用户，而无需他们明确告知助手他们的姓名，让对话更加个性化。

只要在配置手动身份验证时定义了 profile 范围，Microsoft Copilot Studio 就会根据标识提供者提供的 name 声明自动设置 User.DisplayName 的值。 有关范围的更多信息，请参阅使用 Microsoft Entra ID 配置用户身份验证。

User.Id

警告

不保证此变量包含值。 通过标识提供者的用户进行测试，以确保您的主题可以正确运行。

User.Id 变量包含存储在标识提供者中的 userID。 使用 Power Automate 流中的此变量调用将 UserID 作为值的 API。

Microsoft Copilot Studio 将根据标识提供者提供的 sub 声明自动设置 User.DisplayName 的值。

User.IsLoggedIn

User.IsLoggedIn 是一个存储用户的登录状态的布尔型变量。 true 的值指示用户已登录。 可使用此变量在主题中创建分支逻辑来检查成功登录，或仅在用户已登录时获取用户信息。

User.AccessToken

警告

务必将 User.AccessToken 变量仅传递到可信源。 其中包含用户身份验证信息，如果受到威胁，可能伤害用户。

User.AccessToken 变量中包含用户登录后获取的用户令牌。 可以将此变量传递到 Power Automate 流，以使其连接到后端 API 并获取用户信息，或代表用户执行操作。

请勿在消息节点内或您不信任的流中使用 User.AccessToken。

SignInReason

SignInReason是一个选择类型变量，指示用户何时必须登录。 它有两个可能的值：

• SignInRequired 指示用户必须在开始对话时使用登录系统主题登录。 要求用户登录必须打开。

• Initializer 表示如果用户尚未登录，并且他们在对话中达到使用身份验证变量的时刻，则会提示他们登录。

经典

身份验证变量

如果您的机器人配置有仅用于 Teams 和 Power Apps 或手动身份验证选项，您的主题中将有一组身份验证变量。 查看身份验证配置文档，了解有关如何在机器人中配置身份验证的详细信息。

下表按身份验证配置选项比较身份验证变量的可用性：

身份验证变量	无身份验证	仅适用于 Teams 和 Power Apps	手动
UserDisplayName	❌	✔️	✔️
UserID	❌	✔️	✔️
IsLoggedIn	❌	❌	✔️
AuthToken	❌	❌	✔️

UserDisplayName 变量

UserDisplayName 变量包含存储在标识提供程序中的用户显示名称。 您可以使用此变量来问候或引用最终用户，而无需他们明确告知机器人，让体验更加个性化。

此字段值从 Microsoft Entra ID name 声明中获得。 对于 OAuth 提供程序，这是存储在 name 声明中的值。 Microsoft Copilot Studio 会自动将此字段提取到变量中，以确保您在身份验证范围设置中包含 profile。

UserID 变量

UserID 变量包含存储在标识提供程序中的用户的 ID。 此值可以由 Power Automate 流用来调用作为值获取 UserID 的 API。 此字段值从 Microsoft Entra ID sub 声明中获得。 对于 OAuth 提供程序，这是存储在 sub 声明中的值。 Microsoft Copilot Studio 会自动将此字段提取到变量中。

警告

UserDisplayName 和 UserID 变量不能保证一定被填充，根据标识提供程序中的用户配置，它们可能是空字符串。 通过标识提供程序的用户进行测试，以确保您的主题可以正确运行，即使这些变量是空的。

IsLoggedIn 变量

IsLoggedIn 变量指示用户是已登录（其原因是正在登录或已在登录，也称为登录成功路径）还是未登录（这将产生登录失败路径）。

IsLoggedIn 是其中包含用户的登录状态的布尔值类型变量。 可使用此变量在主题中创建分支逻辑来检查成功登录（例如，在添加身份验证节点时提供的模板中），或仅在用户已登录时实时地获取用户信息。

AuthToken 变量

AuthToken 变量中包含用户登录后获取的用户令牌。 可以将此变量传递到 Power Automate 流，以使其连接到后端 API 并获取用户的信息，或代表用户执行操作。

警告

务必将 AuthToken 变量仅传递到可信源。 其中包含用户身份验证信息，如果受到威胁，可能伤害用户。

请勿在消息节点内或您不信任的流中使用 AuthToken。

测试身份验证变量

默认情况下，测试机器人窗格将使用当前登录用户的帐户填充 UserDisplayName 和 UserID 变量。 但是，在测试使用身份验证的主题时，您可能希望使用这些变量的其他值（甚至是空值）。

例如，您可能希望测试如何使用特殊字符，或者如果变量为空，将会发生什么情况。

这仅适用于测试机器人窗格；您不能在部署到渠道的已发布机器人中使用此部分中介绍的命令。

下表列出了将填充这些变量的命令。 在测试机器人窗格中输入命令，就像您在正常情况下与机器人聊天一样。 如果成功，您将收到机器人发送的一条确认消息。 如果机器人不使用身份验证，您将收到一个错误。

如果重置测试机器人窗格（或者对导致测试机器人自动重置的主题进行更改），您将需要再次发送命令。

变量	自定义值命令	空（空白）值命令
UserDisplayName	/debug set bot.UserDisplayName "Value"	/debug set bot.UserDisplayName ""
UserID	不可用	/debug set bot.UserID ""

重要提示

由于安全原因，不能使用自定义值（空值或空白值除外）填充 UserID 变量。

使用“仅用于 Teams 和 Power Apps”配置时的身份验证

如果您的身份验证选项设置为仅用于 Teams 和 Power Apps，则无需向主题显式添加身份验证。 在此配置中，Microsoft Teams 中的任何用户都将通过其 Teams 凭据自动登录，而无需使用身份验证卡显式登录。 如果您的身份验证选项设置为“手动”，那么您需要添加身份验证节点（即使是 Teams 渠道）。

备注

如果您的身份验证选项设置为仅用于 Teams 和 Power Apps，将没有向主题显式添加身份验证的选项。

向主题添加用户身份验证

身份验证节点将提示用户使用登录卡登录。 如果用户已经登录，不会再次提示他们，即使他们到达另一个“身份验证”节点。

用户在提示中输入用户名和密码（由标识提供者托管）后，可能会提示其输入验证码，具体取决于渠道。 某些渠道（如 Microsoft Teams）不需要用户输入验证码。

当您的机器人配置了 SSO 时，将不会提示用户登录。

要将“身份验证”节点添加到您的主题：

1. 转到要编辑的机器人的主题页。

2. 打开要向其添加身份验证模板的主题的创作区域。

   备注

   如果您的机器人已连接到 Dynamics 365 Customer Service，“身份验证”节点不能成为机器人在最初问候用户时采取的对话路径的一部分；否则登录卡将显示两次。 您应该将“身份验证”节点添加到由用户响应触发的另一个主题。

3. 选择添加节点 (+) 添加一个消息节点。 输入机器人应该说出来指示要提供登录体验的内容。

   

4. 在消息节点下，选择添加节点 (+)，选择调用操作，然后选择身份验证。

   

   备注

   只有在对话树（叶节点形式）结尾的操作选取器中才会提供身份验证节点。 不能将其添加到对话中央。 添加后，可以在其下添加其他节点。

5. 选择后，将自动添加一些新节点。 这些节点包括父身份验证节点，后跟成功路径和失败路径的节点。

   

无身份验证节点的情况下使用 AuthToken

即使不使用调用操作菜单条目提供的模板，也可以使用 IsLoggedIn 和 AuthToken 变量。 如果不先让用户经过身份验证节点就传递 AuthToken 变量，将提示用户在该步骤登录。

如果您始终希望用户登录，或者正在从另一个主题重定向用户，则传递 AuthToken 变量可能很有用。 我们建议您使用调用操作条目提供的模板处理用户无法登录的情况。

备注

如果用户在对话半途注销，然后主题到达使用 AuthToken 变量的节点，将提示用户再次登录。

成功路径

成功路径登录用户成功登录（或已登录）时的 IsLoggedIn = True 和帐户。

如果已经在采用使用 AuthToken变量的逻辑（例如，为了使用流连接到后端系统以检索用户的信息），其应该在此路径下。

失败路径

失败路径等于除 IsLoggedIn = True 外的任何情况。 在大多数情况下，出现失败路径的原因是用户无法登录、使用了错误的密码或取消了登录体验。

添加您可能想要用来处理这种情况的所有逻辑。 例如，我们提供了用于重试或升级到人工代理的选项。 针对您的特定场景和使用情况自定义失败路径的操作。

测试主题

确保使用标识提供者中所配置的真实用户来测试您的主题。 确保体验登录成功路径和登录失败路径，这样如果用户登录失败或标识提供者的登录体验出错，就不会感到奇怪。

相关主题

您还可以配置单一登录 (SSO)，让您的用户无需手动登录。 有关详细信息，请参阅为 Web 配置 SSO。