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

适用于：所有 API 管理层级

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

场景概述

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

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

先决条件

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

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

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

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

• 要代表用户或组访问的后端 OAuth 2.0 API。 例如， GitHub 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 管理中配置凭据提供程序

在此步骤中，为后端 OAuth 2.0 API 创建一个凭据提供程序，以便代表用户或用户组进行访问。 例如，遵循以下步骤，创建 GitHub API 的凭据提供程序。 简单步骤如下：

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

步骤 4：配置连接

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

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 值（示例： eyJ0...） 。 在下一步中，在策略配置中传递此值。

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

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

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

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

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

4. 在get-authorization-contextinbound节中配置策略，设置为 identity-typejwt. 同时配置两个 set-header 策略，以使用在 get-authorization-context 策略中获取的令牌设置 Authorization 标头，并为 GitHub API 配置必需的 User-Agent 标头。

   <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" />
            <set-header name="Authorization" exists-action="override">
               <value>@("Bearer " + ((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</value>
           </set-header>
           <set-header name="User-Agent" exists-action="override">
               <value>API Management</value>
           </set-header>
           [...]
       </inbound> 
   </policies>
   

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

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

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

步骤 7：测试 API

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

2. 选择发送。

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

相关内容

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