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