对消费者进行身份验证

简介

Agent Router 会在边缘对每个推理请求进行身份验证,并将调用方的身份传递给下游策略。身份验证通过 Envoy Gateway SecurityPolicy 资源进行配置,该资源会附加到由 AIGatewayRoute 生成的 HTTPRoute。识别调用方后,系统会将选定的声明复制到请求标头中,供令牌配额和使用量计量用作每个租户的键。

这样,系统便可将每个消费者的凭证(例如 SSO(单点登录)令牌或 API key)转换为配额和计量机制可用的身份。这是通过共享网关提供多租户模型服务的基础。

使用场景

  • 开发人员从平台 Identity Provider 获取 JWT(JSON Web Token),并使用该令牌调用网关,以便网关执行按用户划分的令牌配额。
  • CI 任务提供服务账号令牌,使自动化流量归属于团队,而非个人。
  • 无法进行交互式登录的机器消费者提供静态 API key,该密钥映射到已知租户。

前提条件

  1. 已安装 Alauda AI Platform Gateway。它由 Alauda AI Platform 通过 AmlCluster default 中的 envoyAIGateway 组件进行管理;请参阅安装 Alauda AI Platform和 Alauda AI Platform Gateway 简介。
  2. 已有一个 AIGatewayRoute 将请求路由到一个或多个后端。
  3. 对于 OIDC/JWT 路径:需要一个 JWKS 端点可访问的 OIDC issuer。平台内置的 Identity Provider Dex 是默认选项;其他任何 OIDC issuer(Keycloak、Auth0、Okta、GitHub OIDC、企业 Entra ID 租户)也均可使用,只要网关能够访问其 /.well-known/openid-configuration 和 JWKS URL。
  4. 对于 API key 路径:需要具备集群权限,以便在网关的命名空间中创建 Secret 对象。
NOTE

请在专用命名空间(例如 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,并将其声明映射到身份标头:

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:网关接受的令牌受众。如果在共享 IdP 上省略此项,系统会接受同一 issuer 的任何有效令牌,包括为其他客户端签发的令牌;这些令牌仍会解析为 x-user-id 并消耗配额。请将其设置为网关令牌所对应的客户端 ID;如果你的 issuer 未设置可区分的 aud,请为网关注册专用客户端。
  • claimToHeaders:身份与策略之间的桥梁。生成的标头(x-user-id、x-user-group、x-user-namespace)将作为令牌配额的选择器键,以及使用量计量和费用分摊的标签值。
NOTE

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

TIP

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

使用 API key 进行身份验证

NOTE

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

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 绑定到路由:

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。每个数据映射键都是客户端标识符,每个值都是 API key 原文。添加消费者只需 kubectl patch 一个条目;撤销时只需删除一个键。
  • extractFrom:Envoy 从何处读取所提供的密钥。筛选器会进行字面字符串比较,因此建议使用专用标头,例如 X-API-Key。如果重复使用 Authorization,则必须存储带有 Bearer 前缀的值,这会导致它与同一网关上的 OIDC 路径难以配合。
  • forwardClientIDHeader:将匹配的客户端标识符传递给上游和后续筛选器的标头。请使用与 OIDC claimToHeaders 目标相同的名称(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 比大多数资源的路径深一级:

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"}]}'

错误或缺失的密钥会导致网关返回 401 Unauthorized,请求不会到达任何后端。

了解更多

后续步骤

传播身份标头后,配置配置令牌配额,以强制执行每个租户的令牌预算。