关于 API 凭据和凭据管理器

适用于：所有 API 管理层级

为帮助管理对后端 API 的访问，API 管理实例加入了凭据管理器。 使用凭据管理器从 API 管理实例管理、存储和控制对 API 凭据的访问。

OAuth 2.0 API 的托管连接

使用凭据管理器，可以大大简化跨使用 OAuth 2.0 的一个或多个后端或 SaaS 服务对用户、组和服务主体进行身份验证和授权的过程。 使用 API 管理的凭据管理器，轻松配置 OAuth 2.0、同意、获取令牌、在凭据存储中缓存令牌和刷新令牌，而无需编写单行代码。 使用访问策略将身份验证委托给 API 管理实例、服务主体、用户或组。 有关 OAuth 2.0 的背景信息，请参阅 Microsoft 标识平台和 OAuth 2.0 授权代码流。

此功能使 API 能够在有或没有订阅密钥的情况下公开，对后端服务使用 OAuth 2.0 授权，并通过服务集成降低了升级、实施和维护安全功能的开发成本。

示例用例：

使用 API 管理中托管的 OAuth 连接，客户可以轻松地连接到使用 OAuth 2.0 的 SaaS 提供程序或后端服务。 下面是一些示例：

• 通过附加存储的授权令牌和代理请求，轻松连接到 SaaS 后端

• 通过对 Azure 应用服务 Web 应用或 Azure Functions 后端的请求代理附加授权令牌，其稍后可以应用转换逻辑将请求发送到 SaaS 后端

• 通过对 GraphQL 联合后台的代理请求附加多个访问令牌，来轻松执行联合

• 公开检索令牌端点，获取缓存的令牌，并代表用户从任何计算中调用 SaaS 后端，例如控制台应用或 Kubernetes 守护程序。 将最喜欢的 SaaS SDK 合并到支持的语言中。

• 连接到多个 SaaS 后端时的 Azure Functions 无人参与方案。

• Durable Functions 距离具有 SaaS 连接的逻辑应用又近了一步。

• 使用 OAuth 2.0 连接，API 管理中的每个 API 都可以充当逻辑应用自定义连接器。

凭据管理器如何运作？

凭据管理器中的令牌凭据由两个部分组成：管理和运行时。

• 凭据管理器中的管理负责为 OAuth 2.0 令牌设置和配置凭据提供程序，为标识提供者启用同意流，以及设置一个或多个连接供凭据提供程序访问凭据。 有关详细信息，请参阅连接管理。

• 运行时部分使用 get-authorization-context 策略提取和存储连接的访问和刷新令牌。 当调用进入 API 管理并执行 get-authorization-context 策略时，它首先将验证现有授权令牌是否有效。 如果授权令牌已过期，API 管理将使用 OAuth 2.0 流刷新标识提供者中存储的令牌。 然后使用访问令牌来授权对后端服务的访问。 有关详细信息，请参阅连接运行时。

何时使用凭据管理器？

下面是使用凭据管理器的三种方案。

配置方案

配置凭据提供程序和连接后，API 管理器可以测试连接。 API 管理器将测试后端 OAuth API 配置为使用实例的托管标识的 get-authorization-context 策略。 然后，API 管理器可以调用测试 API 来测试连接。

无人参与的方案

默认情况下，在创建连接时，将为 API 管理实例的托管标识预配置访问策略和连接。 若要使用此类连接，不同的用户可以登录到客户端应用程序（例如静态 Web 应用），然后调用通过 API 管理公开的后端 API。 为进行此调用，使用 get-authorization-context 策略应用连接。 由于 API 调用使用与用户上下文无关的预配置连接，因此相同的数据将返回给所有用户。

有人参与的（用户委托）方案

若要为客户端应用程序（例如静态 Web 应用）的用户启用简化的身份验证体验，该调用需要用户上下文的后端 SaaS API，你可以代表 Microsoft Entra 用户或组标识启用对连接的访问。 在这种情况下，配置的用户只需登录并提供一次同意，随后 API 管理实例将创建并管理其连接。 当 API 管理获取要转发到外部服务的传入调用时，它会将访问令牌从连接附加到请求。 当 API 请求和响应面向个人（例如，检索用户特定的配置文件信息）时，这是理想的选择。

如何配置凭据管理器？

要求

• 必须为 API 管理实例启用托管系统分配的标识。

• API 管理实例必须在端口 443 (HTTPS) 与 Internet 建立出站连接。

可用性

• 所有 API 管理服务层

• 自托管网关中不支持

• 主权云或以下区域不支持：australiacentral、australiacentral2、indiacentral

分步示例

• 配置凭据管理器 - GitHub API
• 配置凭据管理器 - Microsoft Graph API
• 配置凭据管理器 - 用户委托的访问

安全注意事项

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

限制

常见问题解答 (FAQ)

访问令牌何时刷新？

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

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

在运行时，API 管理无法获取新的令牌，并且出现错误。

• 如果连接类型为授权代码，则需要在凭据提供程序级别更新客户端密码。

• 如果连接类型为客户端凭据，则需要在连接级别更新客户端密码。

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

是的，只要端口 443 上的出站连接已启用到 AzureConnectors 服务标记即可。 有关更多信息，请参阅虚拟网络配置参考。

删除凭据提供程序时会发生什么情况？

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

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

在经典和 v2 服务层中，API 管理实例会将访问令牌缓存到令牌过期时间之前的 3 分钟为止。 如果访问令牌距离过期时间不到 3 分钟，则缓存的时间将持续到访问令牌过期为止。

访问令牌不会缓存在消耗层中。

相关内容

• 为连接配置凭据提供程序
• 为 Microsoft Graph API 或 GitHub API 配置和使用连接
• 为用户委托的访问配置连接
• 为凭据提供程序配置多个连接