在 Azure API 管理中使用 Microsoft Entra ID 授权开发人员帐户

  • 项目

本文将指导如何进行以下操作：

  • 为 Microsoft Entra ID 中的用户启用对开发人员门户的访问权限。
  • 通过添加包含用户的外部组管理 Microsoft Entra 用户组。

有关保护开发人员门户选项的概述，请参阅保护对 API 管理开发人员门户的访问。

重要

  • 本文已更新使用 Microsoft 身份验证库 (MSAL) 配置 Microsoft Entra 应用的步骤。
  • 如果以前使用 Azure AD 身份验证库 (ADAL) 为用户登录配置了 Microsoft Entra 应用，建议迁移到 MSAL。

先决条件

可以使用本地 Azure CLI。

  • 如果需要，请安装 Azure CLI 来运行 CLI 参考命令。

  • 本地 Azure CLI，请了解如何安装 Azure CLI。 如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。 有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。

    • 通过使用 az login 命令登录到 Azure CLI。 若要完成身份验证过程，请遵循终端中显示的步骤。 有关其他登录选项，请参阅使用 Azure CLI 登录。

    • 出现提示时，请在首次使用时安装 Azure CLI 扩展。 有关扩展详细信息，请参阅使用 Azure CLI 的扩展。

    • 运行 az version 以查找安装的版本和依赖库。 若要升级到最新版本，请运行 az upgrade。

可用性

重要

此功能在 API 管理的“高级”、“标准”和“开发人员”层中可用。

转到你的 API 管理实例

  1. 在 Azure 门户中搜索并选择“API 管理服务” 。

    Select API Management services

  2. 在“API 管理”服务页上，选择你的 API 管理实例。

    Select your API Management instance

使用 Microsoft Entra ID 启用用户登录 - 门户

为了简化配置，API 管理可以为开发人员门户的用户自动启用 Microsoft Entra 应用程序和标识提供者。 你也可以手动启用 Microsoft Entra 应用程序和标识提供者。

自动启用 Microsoft Entra 应用程序和标识提供者

  1. 在 API 管理实例的左侧菜单中的“开发人员门户”下，选择“门户概述”。

  2. 在“门户概述”页上，向下滚动到“启用 Microsoft Entra ID 用户登录”。

  3. 选择“启用 Microsoft Entra ID”。

  4. 在“启用 Microsoft Entra ID”页上，选择“启用 Microsoft Entra ID”。

  5. 选择关闭。

    Screenshot of enabling Microsoft Entra ID in the developer portal overview page.

启用 Microsoft Entra 提供程序后：

  • 指定 Microsoft Entra 实例中的用户可以使用 Microsoft Entra 帐户登录到开发人员门户。
  • 可以在门户中的“开发人员门户”>“标识”页上管理 Microsoft Entra 配置。
  • （可选）通过选择“标识”>“设置”来配置其他登录设置。 例如，你可能希望将匿名用户重定向到登录页。
  • 在进行配置更改后重新发布开发人员门户。

手动启用 Microsoft Entra 应用程序和标识提供者

  1. 在 API 管理实例的左侧菜单中的“开发人员门户”下，选择“标识”。

  2. 选择顶部的“+添加”，在右侧打开“添加标识提供者”窗格 。

  3. 在“类型”下，从下拉菜单中选择“Microsoft Entra ID”。 选择后，可以输入其他所需信息。

    • 在“客户端库”下拉列表中，选择“MSAL”。
    • 若要添加“客户端 ID”和“客户端密码”，请参阅本文后面的步骤。

  4. 保存“重定向 URL”供稍后使用。

    Screenshot of adding identity provider in Azure portal.

    注意

    有两个重定向 URL：

    • 重定向 URL 指向最新的 API 管理开发人员门户。
    • 重定向 URL（已弃用的门户）指向已弃用的 API 管理开发人员门户。

    建议使用最新的开发人员门户重定向 URL。

  5. 在浏览器上的新标签页中打开 Azure 门户。

  6. 导航到“应用注册”以在 Active Directory 中注册应用。

  7. 选择“新注册”。 在“注册应用程序”页上，将值设置如下：

    • 将“名称”设置为有意义的名称，例如“developer-portal”
    • 将“支持的帐户类型”设置为“任何组织目录中的帐户”。
    • 在“重定向 URI”中，选择“单页应用程序(SPA)”，然后粘贴上一步保存的重定向 URL。
    • 选择“注册” 。

  8. 注册应用程序之后，从“概述”页复制“应用程序(客户端) ID” 。

  9. 切换到包含你的 API 管理实例的浏览器标签页。

  10. 在“添加标识提供者”窗口中，将“应用程序(客户端) ID”值粘贴到“客户端 ID”框中。

  11. 切换到包含“应用注册”的浏览器标签卡。

  12. 选择适当的应用注册。

  13. 在边侧菜单的“管理”部分下，选择“证书和机密”。

  14. 在“证书和机密”页中，选择“客户端机密”下的“新建客户端机密”按钮。

    • 输入“说明”。
    • 为“过期”选择任一选项。
    • 选择“添加” 。

  15. 在离开页面之前复制客户端的“机密”值。 稍后需要用到此值。

  16. 在边侧菜单中的“管理”下，选择“身份验证” 。

    1. 在“隐式授权和混合流”部分，选中“ID 令牌”复选框。
    2. 选择“保存”。

  17. 在侧菜单中的“管理”下，选择“令牌配置”>“+ 添加可选声明”。

    1. 在“令牌类型”中，选择“ID”。
    2. 选择（勾选）以下声明：email、family_name、given_name。
    3. 选择 添加 。 如果出现提示，请选择“启用 Microsoft Graph电子邮件、配置文件权限”。

  18. 切换到包含你的 API 管理实例的浏览器标签页。

  19. 将机密粘贴到“添加标识提供者”窗格的“客户端机密”字段中 。

    重要

    在密钥过期之前更新“客户端机密”。

  20. 在“添加标识提供者”窗格的“允许的租户”字段中，指定要向其授予 API 管理服务实例 API 访问权限的 Microsoft Entra 实例的域。

    • 可使用换行符、空格或逗号分隔多个域。

    注意

    可在“允许的租户”部分中指定多个域。 全局管理员必须先向应用程序授予对目录数据的访问权限，然后用户才能从非原始应用注册域登录。 若要授予权限，全局管理员应：

    1. 转到 https://<URL of your developer portal>/aadadminconsent（例如 https://contoso.portal.azure-api.cn/aadadminconsent）。
    2. 输入全局管理员要向其授予访问权限的 Microsoft Entra 租户的域名。
    3. 选择“提交”。

  21. 指定所需配置后，选择“添加”。

  22. 重新发布开发人员门户以使 Microsoft Entra 配置生效。 在左侧菜单中的“开发人员门户”下，选择“门户概述”>“发布”。

启用 Microsoft Entra 提供程序后：

  • 指定 Microsoft Entra 实例中的用户可以使用 Microsoft Entra 帐户登录到开发人员门户。
  • 可以在门户中的“开发人员门户”>“标识”页上管理 Microsoft Entra 配置。
  • （可选）通过选择“标识”>“设置”来配置其他登录设置。 例如，你可能希望将匿名用户重定向到登录页。
  • 在进行配置更改后重新发布开发人员门户。

迁移到 MSAL

如果以前使用 ADAL 为用户登录配置了 Microsoft Entra 应用，则可以使用门户将应用迁移到 MSAL，并在 API 管理中更新标识提供者。

更新 Microsoft Entra 应用以实现 MSAL 兼容性

有关步骤，请参阅将重定向 URI 切换为单页应用程序类型。

更新标识提供者配置

  1. 在 API 管理实例的左侧菜单中的“开发人员门户”下，选择“标识”。
  2. 从列表中选择“Microsoft Entra ID”。
  3. 在“客户端库”下拉列表中，选择“MSAL”。
  4. 选择“更新”。
  5. 重新发布开发人员门户。

添加外部 Microsoft Entra 组

为 Microsoft Entra 租户中的用户启用访问权限后，你可以：

  • 将 Microsoft Entra 组添加到 API 管理中。
  • 使用 Microsoft Entra 组控制产品可见性。
  1. 导航到你在上一部分注册的应用程序的“应用注册”页。
  2. 选择“API 权限”。
  3. 为 Microsoft 图形 API 添加以下最低应用程序权限：
    • User.Read.All 应用程序权限 � 有了该权限，API 管理可以读取用户的组成员身份，以便在用户登录时执行组同步。
    • Group.Read.All 应用程序权限 � 借助该权限，当管理员尝试使用门户中的“组”边栏选项卡将组添加到 API 管理时，API 管理可以读取 Microsoft Entra 组。
  4. 选择“为 {tenantname} 授予管理员同意”，以便为此目录中的所有用户授予访问权限。

现在可以从 API 管理实例的“组”选项卡添加外部 Microsoft Entra 组。

  1. 在边侧菜单中的“开发人员门户”下，选择“组” 。

  2. 选择“添加 Microsoft Entra 组”按钮。

    Screenshot showing Add Microsoft Entra group button in the portal.

  3. 从下拉菜单中选择“租户”。

  4. 搜索并选择要添加的组。

  5. 按“选择”按钮。

添加外部 Microsoft Entra 组后，可以查看和配置其属性：

  1. 从“组”选项卡中选择该组的名称。
  2. 编辑该组的“名称”和“说明”信息 。

配置的 Microsoft Entra 实例中的用户现在可以：

  • 登录到开发人员门户。
  • 查看和订阅他们可以看到的任何组。

注意

在 Microsoft 标识平台中的权限和同意一文中详细了解“委托”权限类型和“应用程序”权限类型之间的差异 。

将 Microsoft Entra 组与 API 管理同步

Microsoft Entra 中配置的组必须与 API 管理同步，以便你可以将其添加到实例。 如果组未自动同步，请执行下列操作之一以手动同步组信息：

  • 退出登录并再次登录到 Microsoft Entra ID。 此活动通常会触发组的同步。
  • 确保在 API 管理中的配置设置中以相同的方式（使用租户 ID 或域名之一）指定 Microsoft Entra 登录租户。 在开发人员门户的 Microsoft Entra ID 标识提供者中，且在将 Microsoft Entra 组添加到 API 管理时指定登录租户。

开发人员门户：添加 Microsoft Entra 帐户身份验证

在开发人员门户中，可以使用默认开发人员门户内容的登录页上包含的“登录按钮: OAuth”小组件通过 Microsoft Entra ID 进行登录。

Screenshot showing OAuth widget in developer portal.

尽管当新用户使用 Microsoft Entra ID 登录时会自动创建一个新帐户，还是请考虑向注册页添加同一个小组件。 “注册表单：OAuth”小组件表示用于注册 OAuth 的表单。

重要

需要重新发布门户才能使 Microsoft Entra ID 更改生效。

相关内容