对消费者进行身份验证
简介
Envoy AI Gateway 会在边缘对每个推理请求进行身份验证,并将调用者的身份传播到下游策略。身份验证通过 Envoy Gateway 的 SecurityPolicy 资源进行配置,该资源会附加到由 AIGatewayRoute 生成的 HTTPRoute。在识别出调用者后,选定的声明会被复制到请求头中,令牌配额和用量计量将其作为租户级 key 进行消费。
这将诸如 SSO(Single Sign-On)令牌或 API key 之类的单个消费者凭证转换为一个可供配额和计量策略作用的身份。这是共享 gateway 上多租户模型服务的基础。
使用场景
- 开发人员从平台身份提供方获取 JWT(JSON Web Token),并使用该令牌调用 gateway,从而由 gateway 按用户执行令牌配额限制。
- CI 作业提供服务账号令牌,使自动化流量归因到团队而非个人。
- 无法执行交互式登录的机器消费者提供静态 API key,并将其映射到已知租户。
前提条件
- 已安装 Envoy AI Gateway。请参阅 安装 Envoy AI Gateway。
AIGatewayRoute已经将请求路由到一个或多个后端。- 对于 OIDC/JWT 路径:需要一个可访问 JWKS 端点的 OIDC issuer。平台内置的身份提供方 Dex 是默认选项;只要 gateway 能够访问其
/.well-known/openid-configuration和 JWKS URL,任何其他 OIDC issuer(Keycloak、Auth0、Okta、GitHub OIDC、企业 Entra ID 租户)也可以使用。 - 对于 API-key 路径:需要具有在 gateway 命名空间中创建
Secret对象的集群权限。
请在专用命名空间中创建 Gateway 和 AIGatewayRoute(例如 maas-system),而不是在 Envoy Gateway 控制平面命名空间 envoy-gateway-system 中。放置在控制平面命名空间中的 gateway 可能不会将 AI Gateway 请求处理 filter 和 SecurityPolicy 应用到其 listener 上,这会悄悄破坏路由和策略执行。请参阅 Envoy AI Gateway。
步骤
使用 OIDC 或 JWT 进行身份验证
验证由 OIDC issuer 签发的令牌。平台内置的 Dex 是默认 issuer;它还可以代理外部身份源,例如 LDAP 或其他 OIDC provider,从而使其用户获取平台令牌。这些 connector 在平台 IdP(Identity Provider)管理中进行配置。关于平台 IdP 配置,请参阅 Identity Providers。
任何具有可访问 JWKS 端点的 OIDC issuer 都可以使用。当消费者不是平台用户时,请将下面的 issuer 和 remoteJWKS.uri 替换为你选择的 issuer——例如企业 Keycloak realm 或 SaaS IdP——这样 gateway 就可以接受其令牌,而无需平台账户。
将 gateway 指向 OIDC issuer,并将其声明映射到身份请求头:
<platform-address>:平台访问地址。Dex 会在/dex发布其 issuer,并在/dex/keys发布其 JWKS。<aigatewayroute-name>:由你的AIGatewayRoute生成的HTTPRoute名称。audiences:gateway 接受的令牌 audience。对于共享 IdP,如果省略该项,则会接受来自同一 issuer 的任何有效令牌——包括为其他客户端签发的令牌——这些令牌同样会解析为x-user-id并消耗配额。请将其设置为 gateway 令牌所签发给的客户端 ID;如果你的 issuer 没有设置可区分的aud,请为 gateway 注册一个专用客户端。claimToHeaders:身份与策略之间的桥梁。输出的请求头(x-user-id、x-user-group、x-user-namespace)将成为令牌配额的选择器 key,以及用量计量和 chargeback 的标签值。
claimToHeaders 仅支持标量声明(string、int、double、bool);不支持数组类型声明,且不会填充到请求头中。标准 OIDC groups 声明通常是数组——若要将其用作 x-user-group/department,请从 IdP connector 中暴露一个单值声明(例如 primary-group 或专用的 department 声明)并进行映射。如果 x-user-group 为空,则按部门进行的计量、配额和 tier 会静默回退为不分组。
namespace 不是标准 OIDC 声明:必须在上游 IdP connector 中添加,默认情况下不存在。x-user-namespace 是 Metering Token Usage 使用的按命名空间 chargeback key;仅在按命名空间或租户计费时映射它。若要将策略基于平台默认不输出的其他属性(例如 subscription tier),请在 connector 中添加该声明,并通过额外的 claimToHeaders 条目进行映射。
若要在不中断流量的情况下逐步发布,先设置 jwt.optional: true 并进行观察。当所有消费者都提供有效令牌后再将其移除。
使用 API key 进行身份验证
如果 Gateway 创建在 Envoy Gateway 控制平面命名空间 envoy-gateway-system 中,则 apiKeyAuth(与模型路由一样)不会被强制执行:SecurityPolicy 会报告 Accepted=True,但错误或缺失的 key 仍会返回 200,且不会注入 x-user-id。这与上面的前提条件说明中所述的控制平面 listener 跳过问题相同——不是 Envoy Gateway 的版本 bug。修复方法是在专用命名空间中创建 Gateway 和 AIGatewayRoute(推荐),或者将 Envoy AI Gateway 升级到缩小了 listener 跳过范围的版本(v0.6.0 / Alauda release-0.6.0-alauda)。手动编写一个修改 listener filter chain 的 EnvoyPatchPolicy 可以作为临时权宜之计,但它依赖具体版本,且较为脆弱——它取决于正在运行的 Envoy 构建的精确 filter 布局——不建议用于生产环境。
对于无法执行 OIDC 流程的机器消费者,请改为验证静态 API key。这里没有签发服务:集群管理员为每个消费者生成一个随机字符串,将其存储在 Secret 中,并通过带外方式共享。gateway 的数据平面会通过在该 Secret 中查找所提供的值来验证每个请求。
为每个消费者生成一个 key,并将它们存储在同一个 Opaque Secret 中。每个 data map key 都是下游策略看到的客户端标识符;每个 value 都是消费者提供的API key:
使用 SecurityPolicy 将 Secret 绑定到 route:
credentialRefs:一个或多个保存凭证的 OpaqueSecret。每个 data map key 都是客户端标识符,每个 value 都是字面量 API key。添加消费者只需对其中一项执行kubectl patch;撤销则只需删除一个 key。extractFrom:Envoy 从何处读取所提供的 key。该 filter 执行字面字符串比较,因此建议使用专用请求头,例如X-API-Key。若重用Authorization,则需要将 value 与其Bearer前缀一起存储,这会与同一 gateway 上的 OIDC 路径产生严重冲突。forwardClientIDHeader:将匹配到的客户端标识符传递给上游及后续 filter 的请求头。请使用与 OIDCclaimToHeaders目标相同的名称(x-user-id),以便令牌配额和用量计量在两种身份验证路径中看到一致的 key。sanitize:防止原始 API key 泄露到模型后端或被记录到下游日志中。
如果 gateway 必须保留在 envoy-gateway-system 中,apiKeyAuth 强制执行会受到上述相同的控制平面 listener 跳过问题影响,且任何按 route 的 SecurityPolicy 更改都无法修复它。支持的解决方案是将 Gateway 和 AIGatewayRoute 移动到专用命名空间(首选),或者将 Envoy AI Gateway 升级到缩小 listener 跳过范围的版本(v0.6.0 / Alauda release-0.6.0-alauda)。手工构建并修改 listener filter chain 的 EnvoyPatchPolicy 可以作为临时补救措施,但它具有版本依赖且较脆弱——它依赖于当前运行的 Envoy build 的精确 filter 布局——不建议用于生产环境。
验证
确认策略已被接受。SecurityPolicy 状态是 ancestor-scoped,因此 jsonpath 比大多数资源要多查一层:
当策略已编排完成时,该命令会返回 True。
对于 OIDC 路径,发送带有有效令牌的请求,并确认上游服务接收到了 x-user-id、x-user-group 和 x-user-email 请求头。
对于 API-key 路径,发送匹配的 X-API-Key,并确认上游看到的 x-user-id 被设置为匹配到的客户端标识符:
错误或缺失的 key 会在请求到达任何后端之前,由 gateway 返回 401 Unauthorized。
了解更多
后续步骤
在身份请求头传播之后,请配置 配置令牌配额 以强制执行按租户的令牌预算。