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

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

按照使用 Microsoft Entra ID 配置用户身份验证中的说明进行操作。

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

在 Copilot Studio 中打开您的助手，选择页面顶部的设置，然后选择安全性。

选择身份验证磁贴。

选择手动进行身份验证，然后选择要求用户登录。

根据需要，配置所有手动身份验证字段。

选择保存。

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

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

在页面顶部，选择设置，然后选择安全性。

选择身份验证磁贴。

备注

您必须选择手动进行身份验证，才能将用户身份验证添加到自定义主题。

清除要求用户登录复选框。

根据需要，配置所有手动身份验证字段。

选择保存。

选择页面顶部的主题。

选择添加节点 () >高级>身份验证。

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

提示

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

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

警告

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

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

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

警告

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

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

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

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

警告

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

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

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

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

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

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

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

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

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

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

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

警告

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

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

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

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

警告

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

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

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

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

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

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

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

重要提示

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

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

备注

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

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

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

当您的助手配置了 SSO 时，系统将不会提示用户登录。

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

转到要编辑的助手的主题页面。

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

备注

如果您的助手连接到 Dynamics 365 Customer Service，则身份验证节点不能是助手最初问候用户时所遵循的对话路径的一部分；否则，登录卡片将显示两次。 您应该将“身份验证”节点添加到由用户响应触发的另一个主题。

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

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

备注

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

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

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

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

备注

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

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

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

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

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

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