在 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 中配置机器人资源和应用:

  • 使用机器人资源配置 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。

配置消息传送终结点

消息终结点是将消息发送到机器人的位置。 它支持与机器人的通信。

为机器人资源配置消息传送终结点

  1. 在 Web 浏览器上打开 Azure 门户。 此时会打开“Azure 机器人Microsoft”页。

  2. “搜索 ”框中输入机器人资源的名称,然后选择“ Enter ”将其打开。

  3. 选择 “设置>配置”。

    屏幕截图显示了“机器人配置”菜单。

    此时会显示 “配置” 页。

  4. 输入机器人在其中接收应用用户消息的消息传送终结点 URL。

    屏幕截图显示了用于添加机器人与用户交互的 URL 的消息传递终结点选项。

  5. 选择“应用”。

    消息传送终结点已配置。

你已为机器人资源配置消息传送终结点。 接下来,必须为 Microsoft Entra 应用启用 SSO。

为 Microsoft Entra 应用配置 SSO

必须配置权限和范围、授权客户端应用程序、更新应用清单 (以前称为 Teams 应用清单) ,并为 Microsoft Entra 应用创建客户端密码。 这些配置有助于为机器人应用调用 SSO。

配置访问令牌的范围

配置范围 (权限) 用于将访问令牌发送到 Teams 客户端和授权受信任的客户端应用程序启用 SSO 的选项。

你需要:

  • 配置应用程序 ID URI:为应用配置范围 (权限) 选项。 你将公开 Web API 并配置应用程序 ID URI。
  • 若要配置 API 范围:定义 API 的范围,以及可以同意某个范围的用户。 只能让管理员为特权较高的权限提供许可。
  • 若要配置授权的客户端应用程序:为要预先授权的应用程序创建授权的客户端 ID。 它允许应用用户访问你配置的应用范围(权限),而无需任何进一步的同意。 仅预授权你信任的那些客户端应用程序,因为应用用户将没有机会拒绝同意。

配置应用程序 ID URI

  1. 在 Web 浏览器上打开 Azure 门户

    此时会打开“Azure 机器人Microsoft”页。

  2. “搜索 ”框中输入机器人资源的名称,然后选择“ Enter ”将其打开。

  3. 选择 “设置>配置”。

    屏幕截图显示“设置”下的“机器人配置”菜单。

    此时会显示 “配置” 页。

  4. 选择“管理”。

    显示机器人资源配置的屏幕截图。

    此时将显示“Microsoft Entra”应用页。

    此页上会显示应用的新应用 ID (客户端 ID) 。 记下并保存此应用 ID。 稍后需要在应用清单中更新它。 如果在创建机器人资源时使用了现有应用的 ID,则该应用的 ID 会显示在此页中。

    屏幕截图显示了“机器人应用”页,其中突出显示了“应用程序客户端 ID”。

  5. 从左窗格中选择“管理>公开 API”。

    随即显示“公开 API”页。

  6. 选择“ 添加 ”以生成应用程序 ID URI。

    屏幕截图显示了“应用程序 ID URI”的“设置”选项。

    将显示用于设置应用程序 ID URI 的部分。

  7. 以此处所述的格式输入应用程序 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 作为基资源名称。

  8. 选择“保存”

    浏览器上会显示一条消息,指出应用程序 ID URI 已更新。

    屏幕截图显示“应用程序 ID URI 已更新”消息。

    应用程序 ID URI 显示在页面上。

    屏幕截图显示更新的应用程序 ID URI。

  9. 记下并保存应用程序 ID URI。 稍后更新应用清单时需要使用它。

配置了应用程序 ID URI。 现在可以为应用定义范围和权限。

配置 API 范围

  1. 在此 API 部分定义的“作用域”中选择“+ 添加作用域”。

    屏幕截图突出显示了“添加范围”选项。

    将显示 “添加范围 ”页。

  2. 输入配置范围的详细信息。

    显示如何在 Azure 中添加范围详细信息的屏幕截图。

    1. 输入范围名称。

    2. 选择可以对此范围表示同意的用户。 默认选项为 仅限管理员

    3. 输入管理员同意显示名称

    4. 输入管理员同意的说明。

    5. 输入 用户同意显示名称

    6. 输入用户同意说明。

    7. 为状态选择“启用”选项。

    8. 选择“添加作用域”。

      注意

      在本教程中,可以使用 openid 配置文件 User.Read User.ReadBasic.All 作为范围。 此范围适用于使用 代码示例。 还可以添加更多 Graph 范围和权限。 有关详细信息,请参阅 使用 Microsoft Graph 权限和范围扩展应用

    浏览器上会显示一条消息,指出已添加范围。

    屏幕截图显示“已添加范围”消息。

    注意

    定义的新范围显示在页面上。 确保记下并保存已配置的范围。 稍后需要它来更新 OAuth 连接。

范围和权限现已配置。 接下来,必须为 Microsoft Entra 应用配置授权的客户端应用程序。

配置已授权的客户端应用程序

  1. 将“公开 API ”页移动到“授权客户端应用程序”部分,然后选择“+ 添加客户端应用程序”。

    屏幕截图显示了“已授权的客户端应用程序”下突出显示的“添加客户端应用程序”选项。

    将显示“添加客户端应用程序”页。

  2. 为要为应用的 Web 应用程序授权的应用程序输入相应的Microsoft 365 客户端 ID。

    屏幕截图显示添加的客户端 ID。

    注意

    • Teams、Microsoft 365 应用和 Outlook 的移动、桌面和 Web 应用程序的 Microsoft 365 客户端 ID 是必须添加的实际 ID。
    • 如果你的应用具有选项卡应用,则需要 Web 或 SPA,因为 Teams 中不能有移动或桌面客户端应用程序。
  3. 选择以下客户端 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 移动应用程序
  4. 选择在 授权范围内 为应用创建的应用程序 ID URI,将范围添加到公开的 Web API。

  5. 选择“添加应用程序”

    浏览器上会显示一条消息,指出已添加授权的客户端应用。

    屏幕截图显示“客户端 ID 已添加”消息。

    授权应用的客户端 ID 显示在页面上。

    屏幕截图显示在“授权的客户端应用程序”屏幕下新添加的“客户端 ID”。

    注意

    可以授权多个客户端应用程序。 重复此过程的步骤以配置另一个已授权的客户端应用程序。

已成功配置应用范围、权限和客户端应用程序。 确保记下并保存应用程序 ID URI。 接下来,配置访问令牌版本。

配置访问令牌版本

必须在 entra 应用清单中定义应用Microsoft访问令牌版本。

定义访问令牌版本

  1. 从左窗格中选择“管理>清单 ”。

    屏幕截图显示Microsoft Entra 管理中心清单。

    此时会显示Microsoft Entra 应用清单。

  2. 输入 2 作为 accessTokenAcceptedVersion 属性的值。

    屏幕截图显示接受访问令牌版本的值。

  3. 选择“保存”

    浏览器上会显示一条消息,指出已成功更新应用清单。

    屏幕截图显示清单已更新消息。

你已更新访问令牌版本。 接下来,你将为应用创建客户端密码。

创建客户端密码

客户端密码是应用程序在请求令牌时用于证明其标识的字符串。

为应用创建客户端密码

  1. 选择“ 管理>证书 & 机密”。

    屏幕截图显示了“证书和机密”菜单选项。

    此时会显示 “证书 & 机密 ”页。

  2. 选择“ + 新建客户端密码”。

    屏幕截图显示突出显示的“新建客户端密码”选项以添加新客户端密码。

    此时会显示 “添加客户端机密 ”页。

    屏幕截图显示了用于提供所需详细信息的“添加客户端密码”页。

    1. 输入说明。
    2. 选择机密的有效期。
  3. 选择“添加”。

    浏览器上会显示一条消息,指出客户端密码已更新,并且客户端密码显示在页面上。

    屏幕截图显示“客户端机密已添加”消息。

  4. 选择“客户端密码 的值 ”旁边的“复制”按钮。

  5. 保存复制的值。 稍后需要使用它来更新代码。

    重要

    请确保在创建客户端密码后立即复制它的值。 该值仅在创建客户端密码时可见,之后无法查看该值。

你已配置客户端密码。 接下来,必须配置重定向 URL。

配置重定向 URL

身份验证配置取决于要以应用为目标的平台或设备。 可能需要配置重定向 URI、身份验证设置或特定于平台的详细信息。

注意

  • 如果机器人应用尚未获得 IT 管理员同意,则应用用户在首次在不同平台上使用你的应用时必须同意。
  • 如果在机器人应用上启用了 SSO,则不需要隐式授予。

只要 URL 唯一,就可以为多个平台配置身份验证。

配置重定向 URL

  1. 打开在 Azure 门户中注册的应用。

  2. 从左窗格中选择“管理>身份验证”。

    屏幕截图显示“管理”下的“身份验证”选项。

    将显示 平台配置 页。

  3. 选择 + 添加平台

    屏幕截图显示了“身份验证”下的“添加平台”选项。

    将显示“配置平台”页。

  4. 选择要为应用配置的平台。 可以从 Web 或 SPA 中选择平台类型。

    屏幕截图显示了 Web 平台的选择。

    此时会显示 “配置 Web ”页。

    注意

    根据所选平台,配置将有所不同。

  5. 输入平台的配置详细信息。

    屏幕截图显示“配置网页以提供输入”。

    1. 输入重定向 URI。 URI 应是唯一的。

      注意

      重定向 URI 中提到的 URL 就是一个示例。

    2. 输入前通道注销 URL。

    3. 选择要Microsoft Entra ID 为应用发送的令牌。

  6. 选择“配置”。

    平台已配置并显示在“平台配置”页中。

Microsoft Entra 应用配置已完成,现在必须通过配置 OAuth 连接来启用机器人资源的 SSO 支持。

配置 OAuth 连接

要使机器人支持 SSO,必须更新其 OAuth 连接设置。 此过程将机器人与为 Microsoft Entra 应用配置的应用详细信息相关联:

  • Microsoft Entra 应用 ID,即客户端 ID
  • 租户 ID
  • 范围和权限

通过提供应用 (客户端) ID 和客户端密码,Bot Framework 令牌存储将令牌交换为具有定义权限的图形令牌。

更新 OAuth 连接

  1. 在 Web 浏览器上打开 Azure 门户。 此时会打开“Azure 机器人Microsoft”页。

  2. “搜索 ”框中输入Microsoft Entra 应用的名称,然后打开应用。

  3. 选择 “设置>配置”。

    屏幕截图显示了为机器人应用配置 OAUth 设置。

    此时会显示 “配置” 页。

  4. “配置” 页中移动,然后选择“ 添加 OAuth 连接设置”。

    屏幕截图突出显示了“添加 OAuth 连接设置”选项。

    此时会显示 “新建连接设置” 页。

  5. 输入 Azure 机器人的 OAuth 配置设置。

    屏幕截图显示了用于提供详细信息的“新建连接设置”。

    1. 输入配置设置的名称。

    2. 选择服务提供商。

      将显示剩余的配置详细信息。

      屏幕截图显示了“新建连接设置”的其他字段。

    3. 输入 Microsoft Entra 应用的应用 (客户端) ID。

    4. 输入为机器人创建的客户端密码。

    5. 令牌交换 URL 中输入机器人的应用程序 ID URI。

    6. 输入租户 ID。

    7. 输入在配置范围和权限时定义的范围。

  6. 选择“保存”

  7. 选择“应用”。

    配置 OAuth 连接后,可以选择“ 测试连接 ”以检查 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 服务进行身份验证的用户。
  • 它为机器人的所有与身份验证相关的活动创建单一故障点和控制。

后续步骤