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

适用于：所有 API 管理层级

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

场景概述

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

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

先决条件

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

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

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

• 运行 Azure 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。
5. 在左侧菜单中，依次选择“API 权限”、“+ 添加权限”。
   1. 选择“我的组织使用的 API”选项卡，键入“Azure API 管理数据平面”，然后选择它。
   2. 在“权限”下，选择 Authorizations.Read，然后选择“添加权限”。
6. 在左侧菜单中，选择“概述”。 在“概述”页上，找到“应用程序(客户端) ID”值，并记下该值以便在后面的步骤中使用。
7. 在左侧菜单中，选择“证书和机密”，然后选择“+ 新建客户端密码”。
   1. 输入“说明”。
   2. 为“到期时间”选择一个选项。
   3. 选择添加。
   4. 在离开页面之前复制客户端密码值。 后面的步骤需要用到。

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

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

步骤 4：配置连接

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

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

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

步骤 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
   

   页眉

   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. 登录到门户，并转到你的 API 管理实例。

2. 在左侧菜单中，选择“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. 选择Send。

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

相关内容

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