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

授权概述

API 管理授权(预览版)简化了管理 OAuth 2.0 后端服务的授权令牌的过程。 通过配置任何受支持的标识提供者并使用标准化的 OAuth 2.0 流创建授权,API 管理可以检索和刷新要在 API 管理内部使用的或发回到客户端的访问令牌。 借助此功能,可以使用或不使用订阅密钥公开 API,向后端服务的授权将使用 OAuth 2.0。

可通过此功能实现的一些示例方案包括:

  • 使用 Power Apps 或 Power Automate 的平民/低代码开发人员可以轻松连接到使用 OAuth 2.0 的 SaaS 提供商。
  • 无人值守方案(例如使用计时器触发器的 Azure 函数)可以利用此功能通过 OAuth 2.0 连接到后端 API。
  • 企业公司的营销团队可以使用相同的授权来与使用 OAuth 2.0 的社交媒体平台进行交互。
  • 在后端服务需要 OAuth 2.0 流的逻辑应用中将 API 管理中的 API 公开为自定义连接器。
  • 代表多个客户端使用 Dropbox 等服务或受 OAuth 2.0 流保护的任何其他服务的方案。
  • 在 API 管理中使用合成 GraphQL 连接到需要 OAuth 2.0 授权的不同服务。
  • 使用服务到服务授权的企业应用程序集成 (EAI) 模式可以针对使用 OAuth 2.0 的后端 API 使用客户端凭据授予类型。
  • 只想要检索访问令牌的单页应用程序,该令牌将在客户端的 SDK 中针对使用 OAuth 2.0 的 API 使用。

该功能由管理和运行时两个部分组成:

  • 管理部分负责配置标识提供者,为标识提供者启用同意流,并管理对授权的访问。

  • 运行时部分使用 get-authorization-context 策略来提取和存储访问令牌与刷新令牌。 当调用进入 API 管理并执行 get-authorization-context 策略时,它首先将验证现有授权令牌是否有效。 如果授权令牌已过期,则使用刷新令牌尝试从配置的标识提供者获取新的授权令牌和刷新令牌。 如果对后端提供程序的调用成功,则使用新的授权令牌,并且授权令牌和刷新令牌都以加密形式存储。

    在策略执行期间,对令牌的访问也会使用访问策略进行验证。

Screenshot showing identity providers that can be used for OAuth 2.0 authorizations in API Management.屏幕截图显示了在 API 管理中用作 Auth 2.0 授权的标识提供者。

要求

  • 必须为 API 管理实例启用托管系统分配的标识。
  • API 管理实例必须在端口 443 (HTTPS) 与 Internet 建立出站连接。

限制

公共预览版存在以下限制:

  • 以下区域不支持授权功能:swedencentral、australiacentral、australiacentral2、jioindiacentral。
  • 可在 GitHub 存储库中找到支持的标识提供者。
  • 为每个 API 管理实例配置的授权提供者数上限:1,000
  • 为每个授权提供者配置的授权数上限:10,000
  • 为每个授权配置的访问策略数上限:100
  • 每个授权的每分钟请求数上限:100
  • 不支持具有代码质询的授权代码 PKCE 流。
  • 自托管网关不支持授权功能。
  • 目前没有可用的 API 文档。 请参阅 GitHub 存储库及其包含的示例。

授权提供者

授权提供者配置包括使用的标识提供者和授权类型。 每个标识提供者需要不同的配置。

  • 一个授权提供者配置只能包含一种授权类型。
  • 一个授权提供者配置可以包含多个授权。
  • 可以在 GitHub 存储库中找到支持的公共预览版标识提供者。

借助通用 OAuth 2.0 提供者,可以使用支持 OAuth 2.0 流标准的其他标识提供者。

授权

若要使用授权提供者,至少需要一个授权。 配置授权的过程因使用的授权类型而异。 每个授权提供者配置仅支持一种授权类型。 例如,如果要将 Azure AD 配置为使用这两种授权类型,则需要两个授权提供者配置。

授权代码授权类型

授权代码授权类型绑定到用户上下文,这意味着用户需要同意授权。 只要刷新令牌有效,API 管理就可以检索新的访问令牌和刷新令牌。 如果刷新令牌失效,用户需要重新授权。 所有标识提供者都支持授权代码。 详细了解授权代码授权类型

客户端凭据授权类型

客户端凭据授权类型不会绑定到用户,通常在应用程序到应用程序方案中使用。 客户端凭据授权类型不需要同意,并且授权不会失效。 详细了解客户端凭据授权类型

访问策略

访问策略确定哪些标识可以使用访问策略相关的授权。 支持的标识为托管标识、用户标识和服务主体。 标识必须与 API 管理租户属于同一租户。

  • 托管标识 - 正在使用的 API 管理实例的系统分配或用户分配的标识。
  • 用户标识 - 与 API 管理实例位于同一租户中的用户。
  • 服务主体 - 与 API 管理实例位于同一 Azure AD 租户中的应用程序。

授权创建流程

下图显示了使用授权代码授权类型在 API 管理中创建授权的流程。 对于公共预览版,没有可用的 API 文档。

授权创建流程

  1. 客户端发送请求以创建授权提供者。
  2. 创建授权提供者,并发回响应。
  3. 客户端发送请求以创建授权。
  4. 创建授权,并发回响应,其中包含授权未“连接”信息。
  5. 客户端发送请求来检索登录 URL,以便在标识提供者上启动 OAuth 2.0 同意。 该请求包含要在最后一个步骤中使用的重定向后 URL。
  6. 返回的响应包含一个登录 URL,应使用该 URL 来启动同意流。
  7. 客户端使用上一步骤中提供的登录 URL 打开浏览器。 浏览器重定向到标识提供者 OAuth 2.0 同意流。
  8. 批准同意后,浏览器使用授权代码重定向到在标识提供者上配置的重定向 URL。
  9. API 管理使用授权代码来提取访问令牌和刷新令牌。
  10. API 管理接收令牌并将其加密。
  11. API 管理重定向到步骤 5 中提供的 URL。

运行时的流程

下图显示了根据配置的授权提取和存储授权令牌与刷新令牌的流程。 检索到令牌后,向后端 API 发出调用。

图表显示了创建运行时的过程流。

  1. 客户端向 API 管理实例发送请求。
  2. 策略 get-authorization-context 检查访问令牌对于当前授权是否有效。
  3. 如果访问令牌已过期但刷新令牌有效,则 API 管理会尝试从配置的标识提供者提取新的访问令牌和刷新令牌。
  4. 标识提供者返回访问令牌和刷新令牌,这些令牌已加密并已保存到 API 管理。
  5. 检索令牌后,使用 set-header 策略将访问令牌作为授权标头附加到发往后端 API 的传出请求。
  6. 向 API 管理返回响应。
  7. 向客户端返回响应。

错误处理。

如果获取授权上下文导致出错,则结果将取决于属性 ignore-error 在策略 get-authorization-context 中的配置方式。 如果值设置为 false(默认),将返回包含 500 Internal Server Error 的错误。 如果值设置为 true,则忽略错误,并使用设置为 null 的上下文变量继续执行。

如果值设置为 false 并在策略中配置了 on-error 节,则在属性 context.LastError 中提供错误。 使用 on-error 节可以调整发回给客户端的错误。 可以使用标准 Azure 警报捕获 API 管理中的错误。 详细了解如何处理策略中的错误

授权常见问题解答

如何提供反馈以及影响此功能的路线图?

请使用表单提供反馈。

令牌如何存储在 API 管理中?

访问令牌和其他机密(例如客户端机密)通过信封加密进行加密,并存储在内部多租户存储中。 数据通过 AES-128 使用某个密钥进行加密,该密钥对于每项数据是唯一的;这些密钥通过存储在 Azure 密钥保管库中的、每月轮换的主证书进行非对称加密。

访问令牌何时刷新?

在运行时执行策略 get-authorization-context 时,API 管理将检查存储的访问令牌是否有效。 如果令牌已过期或即将过期,API 管理将使用刷新令牌从配置的标识提供者提取新的访问令牌和刷新令牌。 如果刷新令牌已过期,则会引发错误,并且需要重新授权才能使授权起作用。

如果标识提供者上的客户端机密过期,会发生什么情况?

在运行时,API 管理将无法提取新令牌,并且会发生错误。

  • 如果授权类型是授权代码,则需要在授权提供者级别更新客户端机密。

  • 如果授权类型是客户端凭据,则需要在授权级别更新客户端机密。

VNet 中运行的 API 管理是否支持此功能?

是,只要 API 管理网关在端口 443 上建立了出站 Internet 连接即可。

删除授权提供者时会发生什么情况?

所有基础授权和访问策略也会一并删除。

API 管理是否缓存访问令牌?

API 管理会将访问令牌缓存到令牌过期时间之前的 3 分钟为止。

支持哪些授权类型?

对于公共预览版,Azure AD 标识提供者支持授权代码和客户端凭据。

其他标识提供者支持授权代码。 在公共预览版之后,将添加更多标识提供者和授权类型。

后续步骤