在 Entra ID Microsoft 中配置应用
Microsoft Entra ID 为应用用户提供对机器人或消息扩展应用的访问权限。 可以向登录到 Teams 的应用用户授予对应用的访问权限。
Microsoft Entra 管理中心中的 SSO 配置
机器人和消息扩展应用使用 Bot Framework 与应用用户通信并实现身份验证。
若要为机器人或消息扩展应用配置 SSO,需要:
- 在 entra ID Microsoft中配置机器人资源
- 在 entra ID Microsoft 中配置应用
注意
确保已在 Entra ID Microsoft创建了应用和机器人资源。
- 有关使用 Microsoft Entra ID 创建应用的详细信息,请参阅 在 Entra ID Microsoft注册新应用。
- 有关在 entra ID Microsoft中创建和配置机器人资源的详细信息,请参阅 创建 Teams 对话机器人。
可以通过以下两种方式之一在机器人或消息扩展应用Microsoft Entra ID 中配置机器人资源和应用:
使用机器人资源配置 SSO,并配置Microsoft Entra 应用:首先可以为机器人资源配置 SSO,并为 Microsoft Entra 应用启用 SSO。 你将配置:
对于机器人资源:消息终结点和 OAuth 连接。
注意
使用 Microsoft Entra ID 创建机器人资源时,可以选择用于创建新应用 ID 的选项,或者,如果已在 Entra ID Microsoft 中注册了应用,则可以使用现有应用 ID。
对于Microsoft Entra 应用:应用 ID URI、范围和权限、受信任的客户端 ID、访问令牌版本、客户端密码和重定向 URL。
使用 Microsoft Entra 应用配置 SSO,然后配置机器人资源:首先可以配置 Microsoft Entra 应用,然后在启用 SSO 时在机器人资源中使用此应用 ID。 你将配置:
对于Microsoft Entra 应用:应用 ID URI、访问令牌、受信任的客户端 ID、访问令牌版本、客户端密码和重定向 URL。
对于机器人资源:消息终结点和 OAuth 连接。
注意
使用注册应用时由 Microsoft Entra ID 生成的应用 ID 配置机器人资源。
在 entra ID 中Microsoft启用 SSO
本教程结束时,你将了解如何配置:
- 应用程序 ID
- 机器人 ID
- 访问令牌
- 应用程序 ID URI。
- 范围、权限和已授权客户端 ID
- 客户端密码
- 重定向 URL
- 消息传递终结点和 OAuth 连接
选择以下两种方法之一为机器人资源配置 SSO:
若要在 entra ID Microsoft中为应用启用 SSO,请执行以下操作:
重要
确保在创建机器人资源时,选择用于创建新应用 ID 的选项。 如果已在 Entra 管理中心Microsoft注册了应用,也可以使用现有的应用 ID。
配置消息传送终结点
消息终结点是将消息发送到机器人的位置。 它支持与机器人的通信。
为机器人资源配置消息传送终结点
在 Web 浏览器上打开 Azure 门户。 此时会打开“Azure 机器人Microsoft”页。
在 “搜索 ”框中输入机器人资源的名称,然后选择“ Enter ”将其打开。
选择 “设置>配置”。
此时会显示 “配置” 页。
输入机器人在其中接收应用用户消息的消息传送终结点 URL。
选择“应用”。
消息传送终结点已配置。
你已为机器人资源配置消息传送终结点。 接下来,必须为 Microsoft Entra 应用启用 SSO。
为 Microsoft Entra 应用配置 SSO
必须配置权限和范围、授权客户端应用程序、更新应用清单 (以前称为 Teams 应用清单) ,并为 Microsoft Entra 应用创建客户端密码。 这些配置有助于为机器人应用调用 SSO。
配置访问令牌的范围
配置范围 (权限) 用于将访问令牌发送到 Teams 客户端和授权受信任的客户端应用程序启用 SSO 的选项。
你需要:
- 配置应用程序 ID URI:为应用配置范围 (权限) 选项。 你将公开 Web API 并配置应用程序 ID URI。
- 若要配置 API 范围:定义 API 的范围,以及可以同意某个范围的用户。 只能让管理员为特权较高的权限提供许可。
- 若要配置授权的客户端应用程序:为要预先授权的应用程序创建授权的客户端 ID。 它允许应用用户访问你配置的应用范围(权限),而无需任何进一步的同意。 仅预授权你信任的那些客户端应用程序,因为应用用户将没有机会拒绝同意。
配置应用程序 ID URI
在 Web 浏览器上打开 Azure 门户。
此时会打开“Azure 机器人Microsoft”页。
在 “搜索 ”框中输入机器人资源的名称,然后选择“ Enter ”将其打开。
选择 “设置>配置”。
此时会显示 “配置” 页。
选择“管理”。
此时将显示“Microsoft Entra”应用页。
此页上会显示应用的新应用 ID (客户端 ID) 。 记下并保存此应用 ID。 稍后需要在应用清单中更新它。 如果在创建机器人资源时使用了现有应用的 ID,则该应用的 ID 会显示在此页中。
从左窗格中选择“管理>公开 API”。
随即显示“公开 API”页。
选择“ 添加 ”以生成应用程序 ID URI。
将显示用于设置应用程序 ID URI 的部分。
以此处所述的格式输入应用程序 ID URI。
-
应用程序 ID URI 预填充了应用 ID (GUID) 格式
api://{AppID}
。
重要
敏感信息:应用程序 ID URI 记录为身份验证过程的一部分,不得包含敏感信息。
独立机器人:如果要生成独立机器人,请输入应用程序 ID URI 作为 api://botid-{YourBotId}。 此处,{YourBotId} 是Microsoft Entra 应用程序 ID。
具有多种功能的应用的应用程序 ID URI:如果要生成具有机器人、消息传递扩展和选项卡的应用,请输入应用程序 ID URI 作为
api://fully-qualified-domain-name.com/botid-{YourClientId}
,其中{YourClientId}
是机器人应用 ID。域名的格式:对域名使用小写字母。 请勿使用大写。
例如,若要创建资源名称为“demoapplication”的应用服务或 Web 应用:
如果使用了基本资源名称 URL 将为... 支持格式... demoapplication https://demoapplication.example.net
所有平台 DemoApplication https://DemoApplication.example.net
仅限桌面、Web 和 iOS。 Android 不支持此功能。 使用小写选项 demoapplication 作为基资源名称。
-
应用程序 ID URI 预填充了应用 ID (GUID) 格式
选择“保存”。
浏览器上会显示一条消息,指出应用程序 ID URI 已更新。
应用程序 ID URI 显示在页面上。
记下并保存应用程序 ID URI。 稍后更新应用清单时需要使用它。
配置了应用程序 ID URI。 现在可以为应用定义范围和权限。
配置 API 范围
在此 API 部分定义的“作用域”中选择“+ 添加作用域”。
将显示 “添加范围 ”页。
输入配置范围的详细信息。
输入范围名称。
选择可以对此范围表示同意的用户。 默认选项为 仅限管理员。
输入管理员同意显示名称。
输入管理员同意的说明。
输入 用户同意显示名称。
输入用户同意说明。
为状态选择“启用”选项。
选择“添加作用域”。
注意
在本教程中,可以使用 openid 配置文件
User.Read User.ReadBasic.All
作为范围。 此范围适用于使用 代码示例。 还可以添加更多 Graph 范围和权限。 有关详细信息,请参阅 使用 Microsoft Graph 权限和范围扩展应用。
浏览器上会显示一条消息,指出已添加范围。
注意
定义的新范围显示在页面上。 确保记下并保存已配置的范围。 稍后需要它来更新 OAuth 连接。
范围和权限现已配置。 接下来,必须为 Microsoft Entra 应用配置授权的客户端应用程序。
配置已授权的客户端应用程序
将“公开 API ”页移动到“授权客户端应用程序”部分,然后选择“+ 添加客户端应用程序”。
将显示“添加客户端应用程序”页。
为要为应用的 Web 应用程序授权的应用程序输入相应的Microsoft 365 客户端 ID。
注意
- Teams、Microsoft 365 应用和 Outlook 的移动、桌面和 Web 应用程序的 Microsoft 365 客户端 ID 是必须添加的实际 ID。
- 如果你的应用具有选项卡应用,则需要 Web 或 SPA,因为 Teams 中不能有移动或桌面客户端应用程序。
选择以下客户端 ID 之一:
使用客户端 ID 用于授权... 1fec8e78-bce4-4aaf-ab1b-5451cc387264 Teams 移动或桌面应用程序 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 Teams Web 应用程序 4765445b-32c6-49b0-83e6-1d93765276ca Microsoft 365 Web 应用程序 0ec893e0-5785-4de6-99da-4ed124e5296c Microsoft 365 桌面应用程序 d3590ed6-52b3-4102-aeff-aad2292ab01c Microsoft 365 移动应用程序
Outlook 桌面应用程序bc59ab01-8403-45c6-8796-ac3ef710b3e3 Outlook Web 应用程序 27922004-5251-4030-b22d-91ecd9a37ea4 Outlook 移动应用程序 选择在 授权范围内 为应用创建的应用程序 ID URI,将范围添加到公开的 Web API。
选择“添加应用程序”。
浏览器上会显示一条消息,指出已添加授权的客户端应用。
授权应用的客户端 ID 显示在页面上。
注意
可以授权多个客户端应用程序。 重复此过程的步骤以配置另一个已授权的客户端应用程序。
已成功配置应用范围、权限和客户端应用程序。 确保记下并保存应用程序 ID URI。 接下来,配置访问令牌版本。
配置访问令牌版本
必须在 entra 应用清单中定义应用Microsoft访问令牌版本。
定义访问令牌版本
从左窗格中选择“管理>清单 ”。
此时会显示Microsoft Entra 应用清单。
输入 2 作为
accessTokenAcceptedVersion
属性的值。选择“保存”。
浏览器上会显示一条消息,指出已成功更新应用清单。
你已更新访问令牌版本。 接下来,你将为应用创建客户端密码。
创建客户端密码
客户端密码是应用程序在请求令牌时用于证明其标识的字符串。
为应用创建客户端密码
选择“ 管理>证书 & 机密”。
此时会显示 “证书 & 机密 ”页。
选择“ + 新建客户端密码”。
此时会显示 “添加客户端机密 ”页。
- 输入说明。
- 选择机密的有效期。
选择“添加”。
浏览器上会显示一条消息,指出客户端密码已更新,并且客户端密码显示在页面上。
选择“客户端密码 的值 ”旁边的“复制”按钮。
保存复制的值。 稍后需要使用它来更新代码。
重要
请确保在创建客户端密码后立即复制它的值。 该值仅在创建客户端密码时可见,之后无法查看该值。
你已配置客户端密码。 接下来,必须配置重定向 URL。
配置重定向 URL
身份验证配置取决于要以应用为目标的平台或设备。 可能需要配置重定向 URI、身份验证设置或特定于平台的详细信息。
注意
- 如果机器人应用尚未获得 IT 管理员同意,则应用用户在首次在不同平台上使用你的应用时必须同意。
- 如果在机器人应用上启用了 SSO,则不需要隐式授予。
只要 URL 唯一,就可以为多个平台配置身份验证。
配置重定向 URL
打开在 Azure 门户中注册的应用。
从左窗格中选择“管理>身份验证”。
将显示 平台配置 页。
选择 + 添加平台。
将显示“配置平台”页。
选择要为应用配置的平台。 可以从 Web 或 SPA 中选择平台类型。
此时会显示 “配置 Web ”页。
注意
根据所选平台,配置将有所不同。
输入平台的配置详细信息。
输入重定向 URI。 URI 应是唯一的。
注意
重定向 URI 中提到的 URL 就是一个示例。
输入前通道注销 URL。
选择要Microsoft Entra ID 为应用发送的令牌。
选择“配置”。
平台已配置并显示在“平台配置”页中。
Microsoft Entra 应用配置已完成,现在必须通过配置 OAuth 连接来启用机器人资源的 SSO 支持。
配置 OAuth 连接
要使机器人支持 SSO,必须更新其 OAuth 连接设置。 此过程将机器人与为 Microsoft Entra 应用配置的应用详细信息相关联:
- Microsoft Entra 应用 ID,即客户端 ID
- 租户 ID
- 范围和权限
通过提供应用 (客户端) ID 和客户端密码,Bot Framework 令牌存储将令牌交换为具有定义权限的图形令牌。
更新 OAuth 连接
在 Web 浏览器上打开 Azure 门户。 此时会打开“Azure 机器人Microsoft”页。
在 “搜索 ”框中输入Microsoft Entra 应用的名称,然后打开应用。
选择 “设置>配置”。
此时会显示 “配置” 页。
在 “配置” 页中移动,然后选择“ 添加 OAuth 连接设置”。
此时会显示 “新建连接设置” 页。
输入 Azure 机器人的 OAuth 配置设置。
输入配置设置的名称。
选择服务提供商。
将显示剩余的配置详细信息。
输入 Microsoft Entra 应用的应用 (客户端) ID。
输入为机器人创建的客户端密码。
在 令牌交换 URL 中输入机器人的应用程序 ID URI。
输入租户 ID。
输入在配置范围和权限时定义的范围。
选择“保存”。
选择“应用”。
配置 OAuth 连接后,可以选择“ 测试连接 ”以检查 OAuth 连接是否成功。
如果连接不成功,Microsoft Entra ID 将显示错误。 可以验证所有配置并再次测试。
祝贺你! 已在为机器人应用启用 SSO 所需的 Microsoft Entra ID 中完成了以下应用配置:
- 应用程序 ID
- 机器人 ID
- 访问令牌
- 应用程序 ID URI。
- 范围、权限和已授权客户端 ID
- 客户端密码
- 重定向 URL
- 消息传递终结点和 OAuth 连接
最佳做法
- 将Microsoft Entra 应用注册限制为其服务到服务应用程序的原始目的。
- 为了更好地控制禁用身份验证连接、滚动机密或与其他应用程序重用Microsoft Entra 应用,请创建一个附加的 Microsoft Entra 应用,供任何用户为身份验证提供服务。
如果使用 Microsoft Entra 注册应用进行身份验证,可能会遇到以下问题:
- 如果续订附加到 Microsoft Entra 应用注册的证书,则会影响使用该证书通过其他 Microsoft Entra 服务进行身份验证的用户。
- 它为机器人的所有与身份验证相关的活动创建单一故障点和控制。