通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure API 管理中的订阅

  • 项目

适用于：所有 API 管理层级

在 Azure API 管理中，订阅是 API 使用者访问通过 API 管理实例发布的 API 时最常用的方式。 本文概述了此概念。

注意

API 管理订阅专门用于通过 API 管理使用订阅密钥来调用 API。 它与 Azure 订阅不同。

什么是订阅？

通过借助 API 管理发布 API，你可以使用订阅密钥轻松保护 API 访问。 需要使用已发布的 API 的开发人员在调用那些 API 时必须在 HTTP 请求中包括有效的订阅密钥。 如果没有有效的订阅密钥，这些调用：

  • 会立即被 API 管理网关拒绝。
  • 不会被转发到后端服务。

若要访问 API，开发者需要订阅和订阅密钥。 订阅是一个命名容器，对应于一对订阅密钥。

此外，

  • 开发者无需 API 发布者批准即可获取订阅。
  • API 发布者可以直接为 API 使用者创建订阅。

提示

API 管理还支持使用其他机制来保护对 API 的访问，包括以下示例：

管理订阅密钥

定期重新生成密钥是常见的安全预防措施。 与大多数需要订阅密钥的 Azure 服务一样，API 管理会成对生成密钥。 使用该服务的每个应用程序都可以从密钥 A 切换到密钥 B，并在中断最少的情况下重新生成密钥 A，反之亦然 。

可以通过调用 Azure API Management 订阅 - 创建或更新 Azure REST API 来设置特定密钥而不是重新生成密钥。 具体而言，需要在 HTTP 请求正文中设置 properties.primaryKey 和/或 properties.secondaryKey。

注意

  • API 管理不提供内置功能来管理订阅密钥的生命周期，例如设置过期日期或自动轮换密钥。 可以使用 Azure PowerShell 或 Azure SDK 等工具开发工作流以自动执行这些流程。
  • 为了强制对 API 进行限时访问，API 发布者可以使用带有订阅密钥的策略，或者使用提供内置过期的机制，例如基于令牌的身份验证。

订阅范围

订阅可以与各种范围相关联：产品、所有 API 或单个 API。

产品的订阅

一直以来，API 管理中的订阅是与某一个产品范围关联的。 开发人员：

  • 在开发人员门户上找到产品列表。
  • 提交对要使用的产品的订阅请求。
  • 使用这些订阅中的密钥（自动批准或由 API 发布者批准）访问产品中的所有 API。

目前，开发人员门户只在“用户配置文件”部分显示产品范围订阅。

产品订阅

订阅所有 API 或单个 API

你还可以创建密钥，以授予对以下任一项的访问权限：

  • 某一个 API，或
  • API 管理实例中的所有 API。

在这些情况下，无需先创建产品并为它添加 API。

“所有访问权限”订阅

每个 API 管理实例附带一个内置的全访问权限订阅，可授予对所有 API 的访问权限。 使用此限定服务范围的订阅，服务所有者可以直接在测试控制台中测试和调试 API。

警告

“所有访问权限”订阅允许访问 API 管理实例中的每个 API，并且只能由授权用户使用。 请勿将此订阅用于例程 API 访问或在客户端应用中嵌入“所有访问权限”订阅密钥。

注意

如果使用 API 范围的订阅、所有 API 订阅或内置全访问订阅，则产品范围内配置的策略不会应用于来自该订阅的请求。

独立订阅

API 管理还允许未与某个开发人员帐户关联的独立订阅。 此功能在类似于多个开发人员或团队共享订阅的方案中非常有用。

在不分配所有者的情况下创建订阅会将其创建为独立订阅。 若要向开发人员和团队的其余人员授予对独立订阅密钥的访问权限，请执行以下任一操作：

  • 手动共享订阅密钥。
  • 使用自定义系统使订阅密钥可供团队使用。

在 Azure 门户中创建和管理订阅

API 发布者可以直接在 Azure 门户中创建订阅。

在门户中创建订阅时，订阅处于“活动”状态，这意味着订阅者可以使用有效的订阅密钥调用关联的 API。 可以根据需要更改订阅的状态。 例如，可以暂停、取消或删除任何订阅（包括内置的全访问权限订阅），以阻止 API 访问。

使用订阅密钥

订阅者可以通过以下两种方式之一使用 API 管理订阅密钥：

  • 将 Ocp-Apim-Subscription-Key HTTP 标头添加到请求，并传递有效订阅密钥的值。

  • 在 URL 中包含 subscription-key 查询参数和有效值。 仅当标头不存在时，才会检查该查询参数。

提示

Ocp-Apim-Subscription-Key 是订阅密钥标头的默认名称，subscription-key 是查询参数的默认名称。 如果需要，可以在每个 API 的设置中修改这些名称。 例如，在门户中，在 API 的“设置”选项卡上更新这些名称。

注意

包含在请求头或查询参数中时，订阅密钥默认传递到后端，并可能在后端监视日志或其他系统中公开。 如果这被视为敏感数据，则可以在 inbound 部分的末尾配置策略以移除订阅密钥头 (set-header) 或查询参数 (set-query-parameter)。

启用或禁用 API 或产品访问的订阅要求

默认情况下，创建 API 时，需要订阅密钥才可进行 API 访问。 同样，创建产品时，默认情况下，需要订阅密钥才能访问添加到产品的任何 API。 在特定情形下，API 发布者可能会希望以不要求订阅的方式向公众发布产品或特定的 API。 虽然发布者可能会选择启用对某些 API 的无安全保护（匿名）的访问，但我们还是建议配置另一种机制来保护客户端访问。

注意

在配置不需要订阅的产品或 API 时，请小心。 此配置可能过于宽松，并且可能会使 API 更容易受到某些 API 安全威胁的影响。

注意

打开的产品已禁用“需要订阅”设置，这意味着用户不需要订阅。 因此，打开的产品不会显示在开发人员门户的“产品”页上。

可以在创建 API 或产品时或以后禁用订阅要求。

若要使用门户禁用订阅要求，请执行以下操作：

  • 禁用产品要求 - 在产品的“设置”页上禁用“需要订阅”
  • 禁用 API 要求 - 在 API 的“设置”页上禁用“需要订阅”。

在禁用订阅要求后，可在没有订阅密钥的情况下访问所选的一个或多个 API。

API 管理在有或没有订阅密钥的情况下如何处理请求

带有订阅密钥的 API 请求

在 API 管理收到来自客户端的带有订阅密钥的 API 请求时，它会根据以下规则来处理该请求：

  1. 首先，检查它是否是与活动订阅关联的有效密钥，可以是：

    • 范围限定为该 API 的订阅
    • 范围限定为分配给 API 的产品的订阅
    • 范围限定为所有 API 的订阅
    • 服务范围的订阅（内置的所有访问订阅）

    如果在适当范围内为活动订阅提供了有效密钥，则允许访问。 根据该范围内的策略定义配置来应用策略。

  2. 如果密钥无效，但存在包含 API 但不需要订阅的产品（开放式产品），则忽略密钥并作为没有订阅密钥的 API 请求进行处理（请参阅下文）。

  3. 否则，访问被拒绝（401 拒绝访问错误）。

没有订阅密钥的 API 请求

在 API 管理收到没有订阅密钥的来自客户端的 API 请求时，它会根据以下规则来处理该请求：

  1. 首先检查是否存在包含该 API 但不需要订阅的产品（开放式产品）。 如果该开放式产品存在，则在 API、策略以及为该开放式产品配置的访问规则的上下文中处理该请求。 一个 API 最多可与一个开放产品相关联。
  2. 如果未找到包含该 API 的开放式产品，则会检查该 API 是否需要订阅。 如果不需要订阅，则在该 API 和操作的上下文中处理该请求。
  3. 如果未找到配置的产品或 API，则访问会被拒绝（401 拒绝访问错误）。

摘要表

下表总结了在不同方案中，网关如何处理带有或没有订阅密钥的 API 请求。 记录了可能启用意外匿名 API 访问的配置。

分配给 API 的所有产品都需要订阅 API 需要订阅 带有订阅密钥的 API 调用 没有订阅密钥的 API 调用 典型方案
✔️ ✔️ 允许访问：

• 产品范围的密钥
• API 范围的密钥
• 所有 API 范围的密钥
• 服务范围的密钥

访问被拒绝：

• 范围未限定为适用的产品或 API 的其他密钥		 访问被拒绝 使用产品范围或 API 范围的订阅进行的受保护 API 访问
✔️ ❌ 允许访问：

• 产品范围的密钥
• API 范围的密钥
• 所有 API 范围的密钥
• 服务范围的密钥
• 范围未限定为适用的产品或 API 的其他密钥		 允许访问（API 上下文） • 使用产品范围的订阅进行的受保护 API 访问

• 匿名访问 API。 如果不应进行匿名访问，请配置 API 级策略以强制实施身份验证和授权。
❌1 ✔️ 允许访问：

• 产品范围的密钥
• API 范围的密钥
• 所有 API 范围的密钥
• 服务范围的密钥

访问被拒绝：

• 范围未限定为适用的产品或 API 的其他密钥		 允许访问（开放产品上下文） • 使用 API 范围的订阅进行的受保护 API 访问

• 匿名访问 API。 如果不应进行匿名访问，请使用产品策略进行配置以强制进行身份验证和授权
❌1 ❌ 允许访问：

• 产品范围的密钥
• API 范围的密钥
• 所有 API 范围的密钥
• 服务范围的密钥
• 范围未限定为适用的产品或 API 的其他密钥		 允许访问（开放产品上下文） 匿名访问 API。 如果不应进行匿名访问，请使用产品策略进行配置以强制进行身份验证和授权

1 有一个开放产品与 API 相关联。

注意事项

  • 无论产品是否已发布，产品上下文中的 API 访问都是相同的。 取消发布产品会使其在开发人员门户中隐藏，但不会使新的或现有的订阅密钥失效。
  • 如果 API 不需要订阅身份验证，则包含订阅密钥的任何 API 请求都被视为与没有订阅密钥的请求相同。 订阅密钥会被忽略。
  • API 访问“上下文”是指在特定范围内（例如 API 或产品）应用的策略和访问控制。

后续步骤

获取有关 API 管理的详细信息：

  • 了解 API 管理策略在不同的范围是如何应用的。
  • 了解 API 管理中的其他概念。
  • 按教程操作，详细了解 API 管理。
  • 查看常见问题解答页，了解常见问题。