AI API 网关的无密钥上游身份验证：工作负载身份联合模式

当提供商可以对工作负载本身进行身份验证时，生产网关工作线程不应携带长期有效的上游 API 密钥。更安全的模式是用现有的云、Kubernetes、CI 或 SPIFFE 身份交换短期提供商凭据，正确缓存该凭据，并将其限制在最小的有用授权边界。

困难的部分不是代币交换。它可以处理不均匀的提供商支持、并发刷新、身份映射、控制平面异常、中断和迁移，而不会创建到广泛特权共享密钥的隐藏回退。

从身份验证功能开始，而不是全局无密钥设置

事实：身份验证支持因提供商和操作而异。 OpenAI 和 Anthropic 支持 API 工作负载的工作负载身份联合。 Azure OpenAI 支持 Microsoft Entra ID 和托管标识。 Google Cloud 支持外部工作负载的附加服务帐户、应用程序默认凭据和工作负载联合身份验证。不过，运行时推理和管理 API 不一定接受相同的凭据类型。

例如，OpenAI 工作负载身份令牌当前无法调用管理API 端点。 A gateway therefore cannot safely represent authentication as one provider-level field such as auth_mode: federated.

建议：构建以提供商帐户、端点系列、环境和操作类为键的能力矩阵：

将此矩阵存储为版本化配置。当配置的身份无法满足所需的认证能力时，路由接纳应拒绝该操作。 This belongs in an AI API control plane for developer teams, not in undocumented environment variables on individual workers.

在路由适配器和提供商适配器之间放置凭据代理

提供商适配器不应获取元数据凭据、构建断言或独立管理令牌刷新。引入具有单一接口的凭证代理：

Credential acquire(CredentialRequest request)

CredentialRequest {
  provider_account_id
  workload_identity_id
  operation_class
  target_service_account
  audience
  scopes
}

Credential {
  value
  expires_at
  authorization_context
  provenance
}

凭据值很敏感，必须保留在内存或批准的临时缓存中。授权上下文记录由令牌表示的提供者项目、服务帐户、范围、角色或部署限制。出处标识其获取方式，例如 oidc_exchange、managed_identity、adc 或 break_glass.

该合约保持路由提供商中立，同时保留授权检查和遥测所需的详细信息。它还可以防止团队的多模型API网关将每个不记名令牌视为可互换的。

使用特定于提供商的获取适配器

每个获取适配器应仅执行其提供商要求的步骤：

• 从本地身份源获取外部断言，例如 Kubernetes 预测的服务帐户令牌、云元数据服务或 SPIFFE 工作负载API。
• 请求提供程序或配置的联合规则所需的确切受众。
• 当提供程序要求交换令牌时交换断言。
• 返回生成的凭据和权威过期时间时间。
• 将故障分类为本地身份、交换、授权、配置或提供商可用性错误。

Vertex AI 的 OpenAI 兼容端点是一个有用的分离示例：应用程序可以通过应用程序默认凭据获取 Google 访问令牌，并提供该令牌作为 OpenAI 客户端的凭据。协议适配器保持OpenAI兼容，而凭据获取保持Google特定。

使令牌缓存能够感知授权

事实：联合凭据的有效期是短暂的。 OpenAI 工作负载身份访问令牌的持续时间不超过一小时，不能比外部主题令牌或经过验证的证书的寿命更长，并且在不刷新令牌的情况下颁发。工作负载必须在过期之前重复交换。

缓存键必须包含可以更改结果权限的每个维度：

cache_key = hash(
  provider_account_id,
  workload_identity_id,
  target_service_account,
  audience,
  normalized_scopes,
  operation_class
)

省略目标帐户、受众群体或范围可能会导致工作人员在错误的授权上下文中重复使用有效令牌。这比缓存未命中更危险。

在到期前使用安全裕度和随机抖动进行刷新。一项实用的政策是：

refresh_at = expires_at
             - max(configured_margin, token_lifetime * 0.10)
             - random_jitter

确切的余量应考虑时钟偏差、交换延迟、重试时间和最长的预期请求。不要仅在与 expires_at.

通过单次刷新防止交换风暴

当许多请求遇到相同的即将过期令牌时，只有一次执行应执行交换。其他调用方应在现有凭据保留在允许的窗口内时继续使用该凭据，或者短暂等待共享刷新结果。

使用每个缓存键单次锁定。在多进程或多节点部署中，决定每个工作线程是否可以维护自己的缓存，或者是否必须分布式刷新协调。本地缓存更简单，但会增加交换量。分布式缓存减少了交换，但扩大了敏感令牌边界，并且需要加密传输、严格的访问控制和谨慎的逐出。

建议： 首选进程内缓存，除非提供商限制或队列规模表明需要共享令牌服务。首先协调每个进程内的刷新，然后测量交换量。

将身份绑定到确切的工作负载声明

联合将信任从存储的密钥转移到身份声明。因此，宽松的映射可能与泄露的共享凭据一样危险。

验证颁发者和目标受众，然后将映射绑定到不可变或严格控制的声明。对于 Kubernetes，请包含命名空间和服务帐户，而不是信任集群中的任何工作负载。对于 CI，限制存储库、工作流程、环境和受保护的分支或部署上下文。对于云身份，映射特定的工作负载主体而不是整个租户或组织。

为生产、暂存、后台作业和管理自动化创建单独的上游服务帐户或托管身份。将每个身份限制为其所需的模型、项目、工作区、部署和API操作。

事实： OpenAI 可以使用 API 权限限制工作负载身份映射。 Anthropic 将交换的凭据与服务帐户关联，并警告联合的安全性取决于上游身份配置。托管身份和云 IAM 同样取决于范围正确的角色分配。

将运行时凭据与管理凭据分开

推理工作线程绝不能仅仅因为某些控制平面任务仍然需要组织管理令牌而继承组织管理令牌。将系统分为两个安全边界：

• 运行时平面：处理模型请求，并仅接收范围为推理的联合或托管凭据。
• 控制平面：通过具有单独存储的凭据和更强的审批控制的独立作业执行项目、工作区、结算或服务帐户管理。

管理凭据不应包含运行时环境变量、Pod 规范、调试包或令牌缓存的路径。在用于配置更改的同一仅附加审核系统中记录它们的使用情况。

失败已关闭，无需临时进行恢复

建议： 不要自动使用共享静态密钥替换失败的联合交换。自动回退可以绕过已撤销的映射、隐藏不正确的受众或恢复身份管理员故意删除的访问权限。

返回分类的上游身份验证错误，停止向受影响的提供商帐户进行分派，并仅当租户和工作负载允许该替代方案时才允许正常路由策略选择另一个提供商。模型回退和凭据回退是不同的决定。

对于严重的身份提供商中断，碎玻璃密钥可能仍然是合理的。使其在正常操作中保持禁用或不可访问。激活应需要经过身份验证的批准，具有固定的有效期，限制受影响的提供商帐户和操作，并对使用它发出的每个请求发出警报。其出处必须出现在请求遥测中。

一次迁移一个路由池

1. 清点运行时和管理凭据。确定哪些进程可以读取每个进程。
2. 创建专用工作负载身份和范围狭窄的提供商服务帐户。
3. 配置精确的颁发者、受众、主题和权限映射。
4. 添加预检检查，以获取令牌并调用低影响的允许端点。
5. 仅使用联合来创建小型路由池。测试期间请勿启用自动密钥回退。
6. 将身份验证失败、交换延迟、令牌期限和提供商授权结果与现有路径进行比较。
7. 逐渐增加流量并观察至少一个完整的令牌刷新周期。
8. 从运行时访问中删除旧密钥，然后在定义的观察期后将其撤销。

按提供商帐户和环境重复此过程。全局切换使得很难区分身份映射错误和提供商特定的令牌行为。

检测和测试故障模式

记录令牌交换延迟、刷新尝试、刷新失败、凭据期限、颁发者、映射主体、提供商帐户、操作类和身份验证错误类别。切勿记录访问令牌、外部断言、客户端密钥或完整的授权标头。

在联合成为唯一的生产路径之前，测试：

• 工作线程、身份提供商和提供商令牌服务之间的时钟偏差。
• 元数据服务器或工作负载身份端点不可用。
• 过期断言和不正确的受众。
• 角色删除和联合规则禁用。
• 令牌交换限制和临时提供商错误。
• 高峰流量下的并发刷新。
• 签名密钥轮换，而旧令牌仍然有效。

对于 OIDC 颁发者轮换，请发布新旧签名密钥，并为验证者缓存和颁发的令牌提供足够的重叠。 OpenAI 记录发现和远程 JWKS 数据的 600 秒缓存，并在令牌引用未知密钥 ID 时进行 JWKS 刷新。不要假设每个验证者的行为都相同；用活的金丝雀测试轮换。

采用无密钥运行时身份验证作为有界迁移

目标不是声称网关不包含任何机密。它将从大量运行时工作线程中删除长期存在的提供程序密钥，并将不可避免的管理凭据限制在较小的控制平面边界内。

从功能矩阵开始，通过一个接口代理凭据，按授权上下文缓存，使用精确的身份映射，并在交换错误时失败关闭。仅在观察到成功的刷新、撤销、中断和签名密钥轮换测试后才能完成迁移。这会生成一个无密钥运行时路径，其可用性和授权行为是可以理解的，而不是假设的。

相关阅读

• 在路由生产流量之前验证提供程序凭据