閱讀英文

共用方式為

使用 Microsoft Entra 应用程序安全地访问产品和 API

  • 2025/08/07

可用性

重要

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

API 管理现在支持通过客户端凭据流，使用内置的 OAuth 2.0 应用程序访问产品 API。 此功能允许 API 管理器注册Microsoft Entra ID 应用程序，从而通过 OAuth 2.0 授权简化开发人员的安全 API 访问。

注意

应用程序目前处于有限预览状态。 如果要注册，请填写此表单。

使用此功能：

  • API 管理器设置产品属性以启用基于应用程序的访问。
  • API 管理器在 Microsoft Entra ID 中注册客户端应用程序，以限制对特定产品的访问。
  • 开发人员可以使用 API 管理开发人员门户访问客户端应用程序凭据。
  • 使用 OAuth 2.0 客户端凭据流，开发人员或应用获取可在 API 请求中包含的令牌
  • API 管理网关验证 API 请求中提供的令牌，以授权访问产品的 API。

先决条件

  • 在 高级、 标准、 基本层或 开发人员 层中部署的 API 管理实例。 如果需要部署实例，请参阅 “创建 API 管理服务实例”。

  • API 管理实例中至少有一个产品，其中至少分配了一个 API。

    • 产品应处于 已发布 状态，以便开发人员可以通过开发人员门户访问该产品。
    • 若要进行测试，可以使用添加到它的默认 Starter 产品和 Echo API。
    • 如果要创建产品，请参阅 “创建并发布产品”。

  • Microsoft Entra 租户中有足够的权限来分配“应用程序管理员”角色，这至少需要 “特权角色管理员”角色。

  • （可选）在 API 管理实例中添加一个或多个 用户 。

配置托管标识

  1. 在 API 管理实例中为 API 管理启用系统分配的托管标识。

  2. 在 Microsoft Entra ID 中向标识分配“应用程序管理员”RBAC 角色。 若要分配角色，请执行以下操作：

    1. 登录到 门户 并导航到 Microsoft Entra ID。
    2. 在左侧菜单中，选择“ 管理>角色”和“管理员”。
    3. 选择 应用程序管理员。
    4. 在左侧菜单中，选择“ 管理>工作分配>+ 添加分配”。
    5. 在 “添加分配 ”页中，按名称（API 管理实例的名称）搜索 API 管理实例的托管标识。 选择托管标识，然后选择“ 添加”。

为产品启用基于应用程序的访问

按照以下步骤为产品启用 基于应用程序的访问 。 产品必须在后续步骤中启用此设置才能与客户端应用程序相关联。

以下示例使用 Starter 产品，但选择至少分配了一个 API 的任何已发布产品。

  1. 通过以下自定义 URL 登录以访问应用功能：https://portal.azure.cn/?feature.customPortal=false&Microsoft_Azure_ApiManagement=applications
  2. 导航到 API 管理实例。
  3. 在左侧菜单中的 API 下，选择“ 产品”。
  4. 选择要配置的产品，例如 初学者 产品。
  5. 在左侧菜单中的“ 产品”下，选择“ 属性”。
  6. 在 “基于应用程序的访问 ”部分中，启用 OAuth 2.0 令牌（最安全） 设置。
  7. （可选）启用 订阅密钥 设置。 如果同时启用基于应用程序的访问和订阅要求，API 管理网关可以接受 OAuth 2.0 令牌或订阅密钥来访问产品的 API。
  8. 选择“保存”。

在门户中启用基于应用程序的访问的屏幕截图。

提示

还可以在创建新产品时启用 OAuth 2.0 令牌 设置。

启用基于应用程序的访问会在 Microsoft Entra ID 中创建后端企业应用程序来表示产品。 后端应用程序 ID 显示在产品的 “属性” 页中。

门户中产品的应用程序设置的屏幕截图。

注意

创建客户端应用程序以访问产品时，此应用程序 ID 设置为 “受众 ”值。 在生成令牌以调用产品 API 时也使用此值。

（可选）查看Microsoft Entra ID 中的产品应用程序设置

（可选）查看在 Microsoft Entra ID 中创建的后端企业应用程序的设置，以表示产品。

应用程序按以下格式命名： APIMProductApplication<产品名称>。 例如，如果产品名称为 Starter，则应用程序名称为 APIMProductApplicationStarter。 应用程序定义了 应用角色 。

查看 应用注册中的应用程序设置：

  1. 登录到 门户 并导航到 Microsoft Entra ID>管理>应用注册。
  2. 选择“ 所有应用程序”。
  3. 搜索并选择 API 管理创建的应用程序。
  4. 在左侧菜单中的“ 管理”下，选择 “应用角色”。
  5. 确认由 Azure API 管理设置的应用程序角色，如以下屏幕截图所示：

门户中应用角色的屏幕截图。

注册客户端应用程序以访问产品

现在注册限制对一个或多个产品的访问的客户端应用程序。

  • 产品必须启用 基于应用程序的访问 才能与客户端应用程序相关联。
  • 每个客户端应用程序在 API 管理实例中都有一个用户（所有者）。 只有所有者才能通过应用程序访问产品 API。
  • 产品可以与多个客户端应用程序相关联。

注册客户端应用程序：

  1. 通过以下自定义 URL 登录以访问应用功能：https://portal.azure.cn/?feature.customPortal=false&Microsoft_Azure_ApiManagement=applications

  2. 导航到 API 管理实例。

  3. 在左侧菜单中的 “API”下，选择“ 应用程序>+ 注册应用程序”。

  4. 在 “注册应用程序 ”页中，输入以下应用程序设置：

    • 名称：输入应用程序的名称。
    • 所有者：从 API 管理实例中的用户下拉列表中选择应用程序的所有者。
    • 授予对所选产品的访问权限：在 API 管理实例中选择以前为 基于应用程序的访问启用的一个或多个产品。
    • 说明：（可选）输入说明。

    门户中应用程序设置的屏幕截图。

  5. 选择“注册”。

应用程序将添加到 “应用程序” 页上的应用程序列表中。 选择应用程序以查看客户端 ID 等详细信息。 需要此 ID 才能生成用于调用产品 API 的令牌。

提示

  • 创建应用程序后，可以选择将其与其他产品相关联。 在 “应用程序 ”页上选择该应用程序，然后选择“ 详细信息>产品>+ 添加产品”。
  • 还可以通过从 “产品 ”页编辑产品来创建或关联应用程序。

生成客户端密码

必须为客户端应用程序生成客户端密码才能使用 OAuth 2.0 客户端凭据流。 机密有效期为一年，但可以随时重新生成。

  1. 在 “应用程序 ”页上，选择创建的应用程序。

  2. 在应用程序的 “概述 ”页上的 “客户端机密”旁边，选择“ 添加机密”。

  3. 在“ 新建客户端机密 ”页上，选择“ 生成”。

    生成并显示在 “客户端机密 ”字段中的客户端密码。 请确保复制机密值并安全地存储它。 关闭页面后，将无法再次检索它。

  4. 选择 关闭。

（可选）查看Microsoft Entra ID 中的客户端应用程序设置

（可选）在 Microsoft Entra ID 中查看客户端应用程序的设置。

应用程序按以下格式命名： APIMApplication<产品名称>。 例如，如果产品名称为 Starter，则应用程序名称类似于 APIMApplicationStarter。

查看 应用注册中的应用程序设置：

  1. 登录到 门户 并导航到 Microsoft Entra ID>管理>应用注册。

  2. 选择“ 所有应用程序”。

  3. 搜索并选择 API 管理创建的客户端应用程序。

  4. 在左侧菜单中的“ 管理”下，选择 API 权限。

  5. 确认应用程序有权访问后端产品应用程序或应用程序。

    例如，如果客户端应用程序授予对 Starter 产品的访问权限，则应用程序具有 Product.Starter.All 权限来访问 APIMProductApplicationStarter 应用程序。

    门户中的 API 权限的屏幕截图。

在开发人员门户中获取应用程序设置

用户可以登录到开发人员门户，查看他们拥有的客户端应用程序。

  1. 使用设置为客户端应用程序所有者的用户帐户登录到开发人员门户（https://<your-apim-instance-name>.developer.azure-api.cn）。

  2. 在顶部导航菜单中，选择“ 应用程序”。

  3. 用户拥有的应用程序将显示在列表中。

  4. 选择应用程序以查看其详细信息，例如 客户端 ID、 客户端机密和 范围。 生成令牌以调用产品 API 时需要这些值。

    开发人员门户中客户端应用程序的屏幕截图。

创建令牌并使用 API 调用

为产品启用基于应用程序的访问并注册客户端应用程序后，开发人员或应用可以生成令牌来调用产品的 API。 请求的标头中必须包含令牌 Authorization 。

例如，开发人员或应用可以运行以下 Azure PowerShell 脚本来调用客户端应用程序以生成令牌，然后使用令牌在 API 管理中调用产品 API。

警告

以下脚本仅用于测试目的。 在生产环境中，使用安全方法存储和检索客户端密码。

调用客户端应用程序以生成令牌

# Replace placeholder values with your own values.

$clientId = "00001111-aaaa-2222-bbbb-3333cccc4444" # Client (application) ID of client application
$clientSecret = "******" # Retrieve secret of client application in developer portal
$scopeOfOtherApp = "api://55556666-ffff-7777-aaaa-8888bbbb9999/.default" # Value of Audience in product properties
$tenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Directory (tenant) ID in Microsoft Entra ID

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = $scopeOfOtherApp
}
$response = Invoke-RestMethod -Method Post -Uri "https://login.partner.microsoftonline.cn/$tenantId/oauth2/v2.0/token" -ContentType "application/x-www-form-urlencoded" -Body $body
$token = $response.access_token

使用令牌调用产品 API

在上一步中生成的令牌用于调用产品 API。 令牌在请求的授权标头中传递。 API 管理实例验证令牌并授权访问 API。

以下脚本显示对回响 API 的示例调用。

# Gatewate endpoint to call. Update with URI of API operation you want to call.
$uri = "https://<gateway-hostname>/echo/resource?param1=sample"
$headers = @{
   "Authorization" = "Bearer $token"  # $token is the token generated in the previous script.
}
$body = @{
    "hello" = "world"
} | ConvertTo-Json -Depth 5

$getresponse = Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/x-www-form-urlencoded" -Headers $headers -Body $body
Write-Host "Response:"
$getresponse | ConvertTo-Json -Depth 5

故障排除

在门户中注册应用程序时出现内部服务器错误

如果无法列出应用程序，或者在门户中注册应用程序时收到内部服务器错误，请检查以下内容：

相关内容