对消费者进行身份验证

简介

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,并将其映射到已知租户。

前提条件

  1. 已安装 Envoy AI Gateway。请参阅 安装 Envoy AI Gateway。
  2. AIGatewayRoute 已经将请求路由到一个或多个后端。
  3. 对于 OIDC/JWT 路径:需要一个可访问 JWKS 端点的 OIDC issuer。平台内置的身份提供方 Dex 是默认选项;只要 gateway 能够访问其 /.well-known/openid-configuration 和 JWKS URL,任何其他 OIDC issuer(Keycloak、Auth0、Okta、GitHub OIDC、企业 Entra ID 租户)也可以使用。
  4. 对于 API-key 路径:需要具有在 gateway 命名空间中创建 Secret 对象的集群权限。
NOTE

请在专用命名空间中创建 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,并将其声明映射到身份请求头:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: maas-oidc-auth
  namespace: <your-namespace>
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: <aigatewayroute-name>  # HTTPRoute generated by your AIGatewayRoute
  jwt:
    providers:
      - name: platform-idp
        issuer: https://<platform-address>/dex
        audiences:
          - <gateway-client-id>   # reject tokens minted for other clients of the same issuer
        remoteJWKS:
          uri: https://<platform-address>/dex/keys
        claimToHeaders:
          - claim: sub      # caller identity, used as the per-user quota and metering key
            header: x-user-id
          - claim: groups    # single-valued group/department claim (see note: array claims are unsupported)
            header: x-user-group
          - claim: namespace  # custom scalar claim for per-namespace chargeback; absent by default (see note)
            header: x-user-namespace
          - claim: email
            header: x-user-email
  • <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 的标签值。
NOTE

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 条目进行映射。

TIP

若要在不中断流量的情况下逐步发布,先设置 jwt.optional: true 并进行观察。当所有消费者都提供有效令牌后再将其移除。

使用 API key 进行身份验证

NOTE

如果 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:

kubectl -n <your-namespace> create secret generic maas-api-keys \
  --from-literal=alice="$(openssl rand -hex 32)" \
  --from-literal=ci-runner="$(openssl rand -hex 32)"

使用 SecurityPolicy 将 Secret 绑定到 route:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: maas-apikey-auth
  namespace: <your-namespace>
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: <aigatewayroute-name>  # HTTPRoute generated by your AIGatewayRoute
  apiKeyAuth:
    credentialRefs:
      - name: maas-api-keys     # Secret whose data keys are the client identifiers
    extractFrom:
      - headers:
          - X-API-Key           # dedicated header avoids the "Bearer " prefix problem of Authorization
    forwardClientIDHeader: x-user-id  # matched client identifier is injected as this header for downstream policies
    sanitize: true              # strip the raw API key from the request before it reaches the model backend
  • credentialRefs:一个或多个保存凭证的 Opaque Secret。每个 data map key 都是客户端标识符,每个 value 都是字面量 API key。添加消费者只需对其中一项执行 kubectl patch;撤销则只需删除一个 key。
  • extractFrom:Envoy 从何处读取所提供的 key。该 filter 执行字面字符串比较,因此建议使用专用请求头,例如 X-API-Key。若重用 Authorization,则需要将 value 与其 Bearer 前缀一起存储,这会与同一 gateway 上的 OIDC 路径产生严重冲突。
  • forwardClientIDHeader:将匹配到的客户端标识符传递给上游及后续 filter 的请求头。请使用与 OIDC claimToHeaders 目标相同的名称(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 比大多数资源要多查一层:

kubectl get securitypolicy <policy-name> -n <your-namespace> \
  -o jsonpath='{.status.ancestors[*].conditions[?(@.type=="Accepted")].status}'

当策略已编排完成时,该命令会返回 True。

对于 OIDC 路径,发送带有有效令牌的请求,并确认上游服务接收到了 x-user-id、x-user-group 和 x-user-email 请求头。

对于 API-key 路径,发送匹配的 X-API-Key,并确认上游看到的 x-user-id 被设置为匹配到的客户端标识符:

curl -sS -H "X-API-Key: <alice-key>" \
  https://<gateway-host>/v1/chat/completions \
  -d '{"model":"<model>","messages":[{"role":"user","content":"ping"}]}'

错误或缺失的 key 会在请求到达任何后端之前,由 gateway 返回 401 Unauthorized。

了解更多

后续步骤

在身份请求头传播之后,请配置 配置令牌配额 以强制执行按租户的令牌预算。