向主题添加最终用户身份验证

您可以直接在代理对话中启用用户身份验证。 您可以将用户的基本属性（如姓名和 ID）分配给变量。 您还可以提示用户使用主题中的身份验证节点登录，该节点检索用户令牌，然后使用该令牌从后端系统检索用户信息。

备注

在和 Copilot Studio 中创建 Microsoft Teams 的代理会自动配置为 Microsoft Entra ID 身份验证。

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

先决条件

• 使用变量
• 在 Copilot Studio 中配置用户身份验证

Web 应用程序

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

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

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

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

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

当您创建代理时， Copilot Studio 会自动添加一个名为 log in 的系统主题。 要使用它，您必须将代理的身份验证设置为手动并要求用户登录。 当客户使用代理开始对话时， 将触发 login in 主题并提示用户登录。 您可以根据您的代理自定义 登录 主题。

重要提示

建议登录主题仅用于提供 Copilot Studio 提供的身份验证方法。 不应该对其进行修改来调用任何其他操作或流，或者其他身份验证方法。

1. 打开你的代理 Copilot Studio，选择 页面顶部的设置 ，然后选择 安全。

2. 选择身份验证。

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

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

5. 选择保存。

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

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

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

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

2. 选择身份验证磁贴。

   备注

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

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

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

5. 选择保存。

6. 选择页面顶部的主题。

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

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

提示

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

身份验证变量

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

有关变量的更多信息，请参阅使用变量。

身份验证变量	不进行身份验证	向 Microsoft 进行身份验证	手动进行身份验证
User.DisplayName	不可用	有空	有空
User.FirstName	不可用	有空	有空
User.LastName	不可用	有空	有空
User.PrincipalName	不可用	有空	有空
User.Email	不可用	有空	有空
User.Id	不可用	有空	有空
User.IsLoggedIn	不可用	有空	有空
User.AccessToken	不可用	不可用	有空
SignInReason	不可用	有空	有空

User.DisplayName

警告

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

User.DisplayName 变量包含存储在标识提供程序中的显示名称。 使用此变量来问候或引用用户，而无需将他们的名字显式地提供给代理，从而使对话更加个性化。

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

User.Id

警告

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

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

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

User.IsLoggedIn

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

User.AccessToken

警告

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

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

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

SignInReason

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

• SignInRequired 指示用户必须在开始对话时使用登录系统主题登录。 必须开启 Require users to log in （要求用户登录）。

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

经典

身份验证变量

如果您的代理配置了 Authenticate with Microsoft （使用 # 进行身份验证）或 Manual authentication（手动 身份验证）选项，则您的主题中可以使用一组身份验证变量。 有关如何在代理中配置身份验证的更多信息，请参阅 配置用户身份验证。 Copilot Studio

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

身份验证变量	不进行身份验证	向 Microsoft 进行身份验证	手动
User.DisplayName	❌	✔️	✔️
User.Id	❌	✔️	✔️
User.IsLoggedIn	❌	❌	✔️
User.AccessToken	❌	❌	✔️

UserDisplayName 变量

User.DisplayName 变量包含存储在标识提供程序中的用户显示名称。 您可以使用此变量来问候或引用最终用户，而无需他们明确地将其告诉代理，从而使其更加个性化。

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

UserID 变量

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

警告

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

IsLoggedIn 变量

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

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

User.AccessToken 变量

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

警告

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

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

测试身份验证变量

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

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

下表列出了将填充这些变量的命令。 这些命令仅适用于 测试机器人 pane;您不能在部署到通道的已发布代理中使用它们。

在 测试机器人 窗格中输入所需的命令，就像您通常与代理聊天一样。 如果成功，您将收到来自代理的确认消息。 如果您的代理不使用身份验证，您将收到错误。

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

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

重要提示

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

使用“向 Microsoft 进行身份验证”时的身份验证

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

备注

如果您的身份验证选项设置为向 Microsoft 进行身份验证，您不能选择在主题中明确添加身份验证。

向主题添加用户身份验证

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

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

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

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

1. 转到 要编辑的代理的 Topics（主题 ）页面。

2. 打开要添加身份验证模板的主题。

   备注

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

3. 选择添加节点 (+) 添加一个消息节点。 输入代理应表示即将发生登录体验的内容。

   

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

   

   备注

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

   新节点会自动出现：父身份验证节点，后面是成功路径和失败路径的节点。

无身份验证节点的情况下使用 User.AccessToken

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

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

备注

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

成功路径

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

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

失败路径

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

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

测试主题

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

相关内容

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