向主题添加用户身份验证，以便允许客户直接在对话中登录。 然后，您可以使用用户变量个性化对话，或代表用户访问后端系统。
在您的主题中使用身份验证之前，您需要使用 Microsoft Entra ID 配置用户身份验证。
按照使用 Microsoft Entra ID 配置用户身份验证中的说明进行操作。
使用“登录系统”主题添加用户身份验证
当您创建助手时，Copilot Studio 会自动添加一个名为登录的系统主题。 若要使用，您必须将您的助手身份验证设置为手动，并且要求用户登录。 当客户开始与助手对话时，登录主题会触发，并提示用户登录。 您可以酌情针对您的助手自定义登录主题。
重要提示
建议登录主题仅用于提供 Copilot Studio 提供的身份验证方法。 不应该对其进行修改来调用任何其他操作或流，或者其他身份验证方法。
在 Copilot Studio 中打开您的助手，选择页面顶部的设置，然后选择安全性。
选择身份验证。
选择手动进行身份验证，然后选择要求用户登录。
根据需要配置所有手动身份验证字段。
选择保存。
向自定义主题添加用户身份验证
登录主题在对话开始对用户进行身份验证。 若要允许用户以后登录，可以将身份验证节点添加到任何自定义主题中。
当客户输入用户名和密码时，系统可能会提示他们输入验证代码。 登录后，即使他们到达另一个 Authenticate 节点，也不会再次提示他们。
在页面顶部，选择设置，然后选择安全性。
选择身份验证磁贴。
备注
您必须选择手动进行身份验证，才能将用户身份验证添加到自定义主题。
清除要求用户登录复选框。
根据需要配置所有手动身份验证字段。
选择保存。
选择页面顶部的主题。
选择添加节点 (
) >高级>身份验证。
使用配置了您的身份提供程序的用户测试您的主题 。
提示
针对登录成功和失败创建登录路径很重要。 登录可能由于多种原因而失败，包括标识提供者的登录体验错误。
身份验证变量
为 Copilot 配置用户身份验证时，可以在主题中使用身份验证变量。 下表根据您选择的身份验证选项比较这些变量的可用性：
有关变量的更多信息，请参阅 使用变量。
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 是一个 choice 类型的变量，指示用户何时必须登录。 它有两个可能的值：
身份验证变量
如果您的 Copilot 配置了 Authenticate with Microsoft （使用 进行身份验证）或 Manual（手动 身份验证）选项，则您的主题中有一组可用的身份验证变量。 有关如何在助手中配置身份验证的更多信息，请参阅在 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 不保证填充 and User.Id 变量，并且可能是空字符串，具体取决于身份提供程序中的用户配置。 通过标识提供程序的用户进行测试，以确保您的主题可以正确运行，即使这些变量是空的。
IsLoggedIn 变量
该 User.IsLoggedIn 变量指示用户是已登录（由于登录或已登录，也称为登录成功路径）还是未登录（这将导致登录失败路径）。
User.IsLoggedIn 是一个布尔变量，其中包含用户的登录状态。 可使用此变量在主题中创建分支逻辑来检查成功登录（例如，在添加身份验证节点时提供的模板中），或仅在用户已登录时实时地获取用户信息。
User.AccessToken 变量
User.AccessToken 变量中包含用户登录后获取的用户令牌。 可以将此变量传递到 Power Automate 流，以使其连接到后端 API 并获取用户的信息，或代表用户执行操作。
警告
务必将 User.AccessToken 变量仅传递到可信源。 其中包含用户身份验证信息，如果受到威胁，可能伤害用户。
请勿在消息节点内或您不信任的流中使用 User.AccessToken。
测试身份验证变量
默认情况下， 测试机器人 窗格使用当前登录用户的账户来填充 User.DisplayName and User.Id 变量。 但是，在测试使用身份验证的主题时，您可能希望使用这些变量的其他值（甚至是空值）。
例如，您可能希望测试如何使用特殊字符，或者如果变量为空，将会发生什么情况。
下表列出了用于填充这些变量的命令。 这些命令仅适用于“测试机器人” 窗格；您不能在部署到通道的已发布 Copilot 中使用它们。
在“ 测试机器人 ”窗格中输入所需的命令，就像您通常与 Copilot 聊天一样。 如果成功，您将收到助手发送的一条确认消息。 如果助手不使用身份验证，您将收到一个错误。
如果您重置 测试机器人 窗格（或者您对主题进行了更改，导致 测试机器人 自动重置），则需要再次发送命令。
| 变量 |
自定义值命令 |
空（空白）值命令 |
User.DisplayName |
/debug set bot.UserDisplayName "Value" |
/debug set bot.UserDisplayName "" |
User.Id |
不可用 |
/debug set bot.UserID "" |
重要提示
出于安全原因，您不能使用自定义值（空值或空白值除外）填充 User.Id 变量。
使用“使用 Microsoft 进行身份验证”时的身份验证
如果您的身份验证选项设置为 Authenticate with Microsoft（使用 进行身份验证），则无需向主题显式添加身份验证。 在此配置中，Microsoft Teams 中的任何用户都将通过其 Teams 凭据自动登录，而无需使用身份验证卡显式登录。 如果您的身份验证选项设置为 Manual，则必须添加 Authenticate 节点（即使对于 Teams 渠道也是如此）。
备注
如果您的身份验证选项设置为 Authenticate with Microsoft（使用 进行身份验证），则您无法选择向主题显式添加身份验证。
向主题添加用户身份验证
Authenticate （身份验证 ） 节点提示用户使用登录卡片登录。 用户登录后，即使他们到达另一个 Authenticate 节点，也不会再次提示他们。
用户在提示中输入用户名和密码（由标识提供者托管）后，系统可能会提示其输入验证代码，具体取决于渠道。 某些通道（例如 Microsoft Teams）不需要用户提供验证代码。
当您的助手配置了 SSO 时，系统将不会提示用户登录。
要将 Authenticate 节点添加到您的 主题中：
转到要编辑的助手的主题页面。
打开要向其添加身份验证模板的主题。
备注
如果您的助手连接到 Dynamics 365 Customer Service，则身份验证节点不能是助手最初问候用户时所遵循的对话路径的一部分；否则，登录卡片将显示两次。 相反，您应该将 Authenticate （身份验证 ） 节点添加到 由用户回复触发的另一个主题中。
选择添加节点 (+) 添加一个消息节点。 输入助手应该说出来指示要提供登录体验的内容。
在消息节点下，选择添加节点 (+)，选择调用操作，然后选择身份验证。
备注
只有在对话树（叶节点形式）结尾的操作选取器中才会提供身份验证节点。 不能将其添加到对话中央。 添加后，可以在其下添加其他节点。
新节点会自动显示：父 Authenticate 节点，后跟成功路径和失败路径的节点。
在没有 Authenticate 节点的情况下使用 User.AccessToken
即使您 User.IsLoggedIn 不使用 Call an action User.AccessToken 菜单项提供的 模板，和 变量也可用。 如果在未先让用户通过 User.AccessToken Authenticate 节点的情况下传递 变量，系统将提示用户在该步骤中登录。
如果您始终希望用户登录，或者您的用户是从其他主题重定向，则传递 User.AccessToken 变量可能很有用。 我们建议您使用调用操作条目提供的模板处理用户无法登录的情况。
备注
如果用户在对话中注销，则当主题到达使用该 User.AccessToken 变量的节点时，系统将提示他们再次登录。
成功路径
成功路径等同于 User.IsLoggedIn = True 用户成功登录（或已登录）的位置和说明。
如果您有使用变量的 User.AccessToken 逻辑（例如，使用流连接到后端系统以检索用户的信息），则它应位于此路径下。
失败路径
失败路径等于除 IsLoggedIn = True 外的任何情况。 在大多数情况下，失败路径的发生是因为用户无法登录、使用了错误的密码或取消了登录体验。
添加您可能想要用来处理这种情况的所有逻辑。 例如，我们提供了用于重试或升级到人工代理的选项。 针对您的特定场景和使用情况自定义失败路径的操作。
测试主题
确保使用标识提供者中所配置的真实用户来测试您的主题。 确保同时执行登录成功和失败路径，这样，如果用户无法登录或身份提供商的登录体验出现错误，就不会出现意外。