配置凭据管理器 - 对后端 API 的用户委托访问权限

适用于：所有 API 管理层级

本文指导你完成配置和使用托管连接的概要步骤，该连接授予 Microsoft Entra 用户或组对后端 OAuth 2.0 API 的委托权限。 对于客户端应用（或机器人）需要代表经过身份验证的用户（例如检查电子邮件或下单）访问后端保护的在线资源时，请按照以下步骤作。

场景概述

在此方案中，将配置一个托管 连接 ，使客户端应用（或机器人）能够代表 Microsoft Entra 用户或组访问后端 API。 例如，你可能具有访问后端 GitHub API 的静态 Web 应用，并且想要访问特定于已登录用户的数据。 下图演示了方案。

• 用户必须授权应用程序代表他们访问安全资源，并且为了授权应用程序，用户必须对其身份进行验证。
• 为了代表用户执行作，应用调用外部后端服务，例如 Microsoft Graph 或 GitHub。
• 每个外部服务都有一种保护这些调用的方法;例如，具有唯一标识用户的用户令牌。
• 若要保护对外部服务的调用，应用必须要求用户登录，以便它可以获取用户的令牌。
• 作为配置的一部分，凭据提供程序是在 API 管理实例中使用凭据管理器注册的。 它包含有关要使用的标识提供者的信息，以及有效的 OAuth 客户端 ID 和机密、要启用的 OAuth 范围以及该标识提供者所需的其他连接元数据。
• 此外，还会创建并用于帮助登录用户并获取用户令牌的连接，以便可以对其进行管理。

先决条件

• 访问你有权在其中创建应用注册并授予对应用权限的管理员同意的 Microsoft Entra 租户。 了解详细信息

  如果要创建自己的开发人员租户，可以注册 Microsoft 365 开发人员计划。

• 要向其委托权限的租户中的一个或多个用户或组。

• 正在运行的 API 管理实例。 如果需要， 请创建 Azure API 管理实例。

• 要代表用户或组访问的后端 OAuth 2.0 API。

• 如果选择在本地使用 Azure PowerShell：
  • 安装最新版本的 Az PowerShell 模块。
  • 使用 Connect-AzAccount cmdlet 连接到 Azure 帐户。
• 如果选择使用 Azure Cloud Shell：
  • 有关详细信息，请参阅 Azure Cloud Shell 概述。

步骤 1：预配 Azure API 管理数据平面服务主体

需要预配 Azure API 管理数据平面服务主体来向用户或组授予必要的委派权限。 使用以下步骤通过 Azure PowerShell 预配服务主体。

1. 登录到 Azure PowerShell。

2. 如果尚未安装 AzureAD 模块，请使用以下命令安装它：

   Install-Module -Name AzureAD -Scope CurrentUser -Repository PSGallery -Force
   

3. 使用以下命令连接到租户：

   Connect-AzureAD -TenantId "<YOUR_TENANT_ID>"
   

4. 如果系统提示，请使用租户的管理员帐户凭据登录。

5. 使用以下命令配置 Azure API 管理数据平面服务主体：

   New-AzureADServicePrincipal -AppId c8623e40-e6ab-4d2b-b123-2ca193542c65 -DisplayName "Azure API Management Data Plane"
   

步骤 2：创建Microsoft Entra 应用注册

为用户委派创建Microsoft Entra ID 应用程序，并向其授予读取 API 管理中的连接的适当权限。

1. 使用租户中具有足够权限的帐户登录到 Azure 门户 。
2. 在 Azure 服务下，搜索 Microsoft Entra ID。
3. 在左侧菜单中，选择“ 管理>应用注册”，然后选择“ + 新建注册”。
4. 在 “注册应用程序 ”页上，输入应用程序注册设置：
   1. 在 “名称”中，输入一个有意义的名称，该名称将显示给应用的用户，例如 UserPermissions。
   2. 在支持的帐户类型中，选择适合你的情形的选项，例如，仅限此组织目录中的帐户（单租户）。
   3. 将 重定向 URI 设置为 Web 并输入 https://www.postman-echo.com/get。
   4. 选择“注册”。
5. 在左侧菜单中，选择“ 管理>API 权限”，然后选择“ + 添加权限”。
   1. 选择 我的组织使用的 API 选项卡，键入 Azure API 管理数据平面，然后选择它。
   2. 在 “权限”下，选择 Authorizations.Read，然后选择“ 添加权限”。
6. 在左侧菜单中，选择“ 概述”。 在 “概述 ”页上，找到 应用程序（客户端）ID 值并记录该值，以便在后续步骤中使用。
7. 在左侧菜单中，选择“ 管理>证书和机密”，然后选择“ + 新建客户端密码”。
   1. 输入“说明”。
   2. 为 “过期”选择一个选项。
   3. 选择 并添加。
   4. 在离开页面之前复制客户端密码 的值 。 后面的步骤需要用到。

步骤 3：在 API 管理中配置凭据提供程序

1. 登录到 Azure 门户 并转到 API 管理实例。
2. 在左侧菜单中，选择 API>凭据管理器，然后选择“ + 创建”。
3. 在 “创建凭据提供程序 ”页上，输入 API 凭据提供程序的设置。 对于此方案，在 “授权”类型中，必须选择 “授权代码”。 有关详细信息，请参阅 在凭据管理器中配置凭据提供程序。
4. 选择 创建。
5. 出现提示时，请查看显示的 OAuth 重定向 URL，然后选择“ 是 ”以确认它是否与在应用注册中输入的 URL 匹配。

步骤 4：配置连接

创建凭据提供程序后，可以添加与该提供程序的连接。 在 “连接 ”选项卡上，完成连接的步骤：

1. 输入 连接名称，然后选择“ 保存”。
2. 在 “步骤 2：登录到连接”下，选择 “登录 ”按钮。 按照那里规定的步骤授权访问，然后返回 API 管理。
3. 在 步骤 3：确定谁有权访问此连接（访问策略），选择“ + 添加”。 根据委派方案，选择 “用户 ”或 “组”。
4. 在 “选择项 ”窗口中，按以下顺序进行选择：
   1. 首先，搜索一个或多个用户（或用户组），然后添加并勾选选择框。
   2. 然后，在显示的列表中，搜索在上一部分中创建的应用注册。
   3. 然后单击 “选择”。
5. 选择“Complete”（完成）。

新连接显示在连接列表中，并显示 “已连接”状态。 如果要为凭据提供程序创建另一个连接，请完成前面的步骤。

步骤 5：获取Microsoft Entra ID 访问令牌

若要启用对后端 API 的用户委托访问权限，必须在运行时在 get-authorization-context 策略中提供委托用户或组的访问令牌。 通常，使用 Microsoft身份验证库 （MSAL）以编程方式在客户端应用中完成此作。 本部分提供创建访问令牌以进行测试的手动步骤。

1. 在浏览器中粘贴以下 URL，将 <tenant-id> 和 <client-id> 的值替换为 Microsoft Entra 应用注册中的值：

   https://login.microsoftonline.com/<tenant-id>/oauth2/authorize?client_id=<client-id>&response_type=code&redirect_uri=https://www.postman-echo.com/get&response_mode=query&resource=https://azure-api.net/authorization-manager&state=1234`
   

2. 出现提示时，请登录。 在响应正文中，复制提供的code的值（示例："0.AXYAh2yl…"）。

3. 将以下 POST 请求发送到令牌终结点，将 <tenant-id> 替换为你的租户 ID，并包含应用注册中指示的标头和正文参数以及你在上一步中复制的代码。

   POST https://login.microsoftonline.com/<tenant-id>/oauth2/token HTTP/1.1
   

   Header

   Content-Type: application/x-www-form-urlencoded

   正文

   grant_type: "authorization_code"
   client_id: <client-id>
   client_secret: <client-secret>
   redirect_uri: <redirect-url> 
   code: <code>   ## The code you copied in the previous step
   

4. 在响应正文中，复制提供的 access_token 值（示例： eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjZqQmZ1...） 。 在下一步中，你将在策略配置中传递此值。

步骤 6：为后端 API 配置 get-authorization-context 策略

为要代表用户或组访问的后端 API 配置 get-authorization-context 策略。 出于测试目的，可以使用在上一部分中获取的用户的 Microsoft Entra ID 访问令牌配置策略。

1. 登录到 Azure 门户 并转到 API 管理实例。

2. 在左侧菜单中，选择 API>API ，然后选择 OAuth 2.0 后端 API。

3. 选择“所有操作”。 在“入站处理”部分中，选择“（</>）（代码编辑器）图标。

4. 在inbound部分中配置get-authorization-context策略，设置identity-type为jwt。

   <policies>
       <inbound>
           [...]
           <get-authorization-context provider-id="<credential-provider-id>" authorization-id="<connection-id>" context-variable-name="auth-context" identity-type="jwt" identity="<access-token>" ignore-error="false" />
           [...]
       </inbound> 
   </policies>
   

在前面的策略定义中，替换：

• <credential-provider-id> 和 <connection-id> 分别对应于您在前面步骤中配置的凭据提供程序和连接的名称。

• 将 <access-token> 替换为在前面的步骤中生成的 Microsoft Entra ID 访问令牌。

步骤 7：测试 API

1. 在测试选项卡上，选择一个已配置的操作。

2. 选择发送。

   成功的响应从后端 API 返回用户数据。

相关内容

• 详细了解 身份验证和授权策略。
• 详细了解 Microsoft Entra ID 中的 范围和权限 。