重要
此功能在 API 管理的“高级”、“标准”、“基本”和“开发人员”层中可用 。
API 管理现在支持通过客户端凭据流,使用内置的 OAuth 2.0 应用程序访问产品 API。 此功能允许 API 管理器注册Microsoft Entra ID 应用程序,从而通过 OAuth 2.0 授权简化开发人员的安全 API 访问。
注意
应用程序目前处于有限预览状态。 如果要注册,请填写此表单。
使用此功能:
- API 管理器设置产品属性以启用基于应用程序的访问。
- API 管理器在 Microsoft Entra ID 中注册客户端应用程序,以限制对特定产品的访问。
- 使用 OAuth 2.0 客户端凭据流,开发人员或应用获取可在 API 请求中包含的令牌
- API 管理网关验证 API 请求中提供的令牌,以授权访问产品的 API。
在 高级、 标准、 基本层或 开发人员 层中部署的 API 管理实例。 如果需要部署实例,请参阅 “创建 API 管理服务实例”。
API 管理实例中至少有一个产品,其中至少分配了一个 API。
- 产品应处于 已发布 状态,以便开发人员可以通过开发人员门户访问该产品。
- 若要进行测试,可以使用添加到它的默认 Starter 产品和 Echo API。
- 如果要创建产品,请参阅 “创建并发布产品”。
Microsoft Entra 租户中有足够的权限来分配“应用程序管理员”角色,这至少需要 “特权角色管理员”角色。
(可选)在 API 管理实例中添加一个或多个 用户 。
- 如果选择在本地使用 Azure PowerShell:
- 安装最新版本的 Az PowerShell 模块。
- 使用 Connect-AzAccount -Environment AzureChinaCloud cmdlet 连接到 Azure 帐户。
在 API 管理实例中为 API 管理启用系统分配的托管标识。
在 Microsoft Entra ID 中向标识分配“应用程序管理员”RBAC 角色。 若要分配角色,请执行以下操作:
- 登录到 门户 并导航到 Microsoft Entra ID。
- 在左侧菜单中,选择“ 管理>角色”和“管理员”。
- 选择 应用程序管理员。
- 在左侧菜单中,选择“ 管理>工作分配>+ 添加分配”。
- 在 “添加分配 ”页中,按名称(API 管理实例的名称)搜索 API 管理实例的托管标识。 选择托管标识,然后选择“ 添加”。
按照以下步骤为产品启用 基于应用程序的访问 。 产品必须在后续步骤中启用此设置才能与客户端应用程序相关联。
以下示例使用 Starter 产品,但选择至少分配了一个 API 的任何已发布产品。
- 登录到 门户 并导航到 API 管理实例。
- 在左侧菜单中的 API 下,选择“ 产品”。
- 选择要配置的产品,例如 初学者 产品。
- 在左侧菜单中的“ 产品”下,选择“ 属性”。
- 在 “基于应用程序的访问 ”部分中,启用 OAuth 2.0 令牌(最安全) 设置。
- (可选)启用 订阅密钥 设置。 如果同时启用基于应用程序的访问和订阅要求,API 管理网关可以接受 OAuth 2.0 令牌或订阅密钥来访问产品的 API。
- 选择“保存”。
提示
还可以在创建新产品时启用 OAuth 2.0 令牌 设置。
启用基于应用程序的访问会在 Microsoft Entra ID 中创建后端企业应用程序来表示产品。 后端应用程序 ID 显示在产品的 “属性” 页中。
注意
创建客户端应用程序以访问产品时,此应用程序 ID 设置为 “受众 ”值。 在生成令牌以调用产品 API 时也使用此值。
(可选)查看在 Microsoft Entra ID 中创建的后端企业应用程序的设置,以表示产品。
应用程序按以下格式命名: APIMProductApplication<产品名称>。 例如,如果产品名称为 Starter,则应用程序名称为 APIMProductApplicationStarter。 应用程序定义了 应用角色 。
查看 应用注册中的应用程序设置:
- 登录到 门户 并导航到 Microsoft Entra ID>管理>应用注册。
- 选择“ 所有应用程序”。
- 搜索并选择 API 管理创建的应用程序。
- 在左侧菜单中的“ 管理”下,选择 “应用角色”。
- 确认由 Azure API 管理设置的应用程序角色,如以下屏幕截图所示:
现在注册限制对一个或多个产品的访问的客户端应用程序。
- 产品必须启用 基于应用程序的访问 才能与客户端应用程序相关联。
- 每个客户端应用程序在 API 管理实例中都有一个用户(所有者)。 所有者可以通过应用程序访问产品 API。
- 产品可以与多个客户端应用程序相关联。
登录到 门户 并导航到 API 管理实例。
在左侧菜单中的 “API”下,选择“ 应用程序>+ 注册应用程序”。
在 “注册应用程序 ”页中,输入以下应用程序设置:
- 名称:输入应用程序的名称。
- 所有者:从 API 管理实例中的用户下拉列表中选择应用程序的所有者。
- 授予对所选产品的访问权限:在 API 管理实例中选择以前为 基于应用程序的访问启用的一个或多个产品。
- 说明:(可选)输入说明。
选择“注册”。
应用程序将添加到 “应用程序” 页上的应用程序列表中。 选择应用程序以查看客户端 ID 等详细信息。 需要此 ID 才能生成用于调用产品 API 的令牌。
提示
- 创建应用程序后,可以选择将其与其他产品相关联。 在 “应用程序 ”页上选择该应用程序,然后选择“ 详细信息>产品>+ 添加产品”。
- 还可以通过从 “产品 ”页编辑产品来创建或关联应用程序。
必须为客户端应用程序生成客户端密码才能使用 OAuth 2.0 客户端凭据流。 机密有效期为一年,但可以随时重新生成。
在 “应用程序 ”页上,选择创建的应用程序。
在应用程序的 “概述 ”页上的 “客户端机密”旁边,选择“ 添加机密”。
在“ 新建客户端机密 ”页上,选择“ 生成”。
生成并显示在 “客户端机密 ”字段中的客户端密码。 请确保复制机密值并安全地存储它。 关闭页面后,将无法再次检索它。
选择 关闭。
(可选)在 Microsoft Entra ID 中查看客户端应用程序的设置。
应用程序按以下格式命名: APIMApplication<产品名称>。 例如,如果产品名称为 Starter,则应用程序名称类似于 APIMApplicationStarter。
查看 应用注册中的应用程序设置:
登录到 门户 并导航到 Microsoft Entra ID>管理>应用注册。
选择“ 所有应用程序”。
搜索并选择 API 管理创建的客户端应用程序。
在左侧菜单中的“ 管理”下,选择 API 权限。
确认应用程序有权访问后端产品应用程序或应用程序。
例如,如果客户端应用程序授予对 Starter 产品的访问权限,则应用程序具有 Product.Starter.All 权限来访问 APIMProductApplicationStarter 应用程序。
为产品启用基于应用程序的访问并注册客户端应用程序后,开发人员或应用可以生成令牌来调用产品的 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 的示例调用。
# 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