#Authenticating Consumers

#Authenticate with OIDC or JWT

Validate tokens issued by an OIDC issuer. The platform's built-in Dex is the default issuer; it can also broker external identity sources, such as LDAP or another OIDC provider, so their users obtain platform tokens. Those connectors are configured in platform IdP (Identity Provider) management. For platform IdP configuration, see Identity Providers.

Any OIDC issuer with a reachable JWKS endpoint can be used. Replace the issuer and remoteJWKS.uri below with the issuer of your choice when consumers are not platform users — for example, an enterprise Keycloak realm or a SaaS IdP — so the gateway accepts their tokens without requiring a platform account.

Point the gateway at the OIDC issuer and map its claims to identity headers:

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
        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    # platform groups, used for per-department aggregation and tiers
            header: x-user-group
          - claim: email
            header: x-user-email

• <platform-address>: the platform access address. Dex publishes its issuer at /dex and its JWKS at /dex/keys.
• <aigatewayroute-name>: the name of the HTTPRoute generated by your AIGatewayRoute.
• claimToHeaders: the bridge between identity and policy. The emitted headers (x-user-id, x-user-group) become the selector keys for token quotas and the label values for usage metering.

#Authenticate with an API key

For machine consumers that cannot perform an OIDC flow, validate a static API key instead. There is no issuance service: the cluster administrator generates a random string per consumer, stores it in a Secret, and shares it out of band. The gateway's data plane validates each request by looking the presented value up in that Secret.

Generate one key per consumer and store them in a single Opaque Secret. Each data-map key is the client identifier that downstream policies see; each value is the API key the consumer presents:

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)"

Bind the Secret to the route with a SecurityPolicy:

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: one or more Opaque Secrets holding the credentials. Each data-map key is the client identifier, each value is the literal API key. Adding a consumer is a kubectl patch of one entry; revoking is a single key deletion.
• extractFrom: where Envoy reads the presented key from. The filter does a literal-string compare, so prefer a dedicated header such as X-API-Key. Reusing Authorization requires storing the value with its Bearer prefix, which mixes badly with the OIDC path on the same gateway.
• forwardClientIDHeader: the header that carries the matched client identifier to the upstream and to later filters. Use the same name as the OIDC claimToHeaders target (x-user-id) so token quotas and usage metering see one consistent key across both auth paths.
• sanitize: prevents the raw API key from leaking to the model backend or being logged downstream.

Workaround for the EG ≤ v1.5.x enforcement gap (see the warning above). Apply this EnvoyPatchPolicy once per Gateway to enable the api_key_auth filter at the listener level. The patch is verified end-to-end on EG v1.5.0: with it in place, wrong/missing keys return 401 and forwardClientIDHeader injection works as documented. Remove it once you upgrade to a fixed EG release.

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyPatchPolicy
metadata:
  name: enable-apikey-auth
  namespace: envoy-gateway-system   # same namespace as the Gateway
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: <gateway-name>
  type: JSONPatch
  jsonPatches:
  - type: type.googleapis.com/envoy.config.listener.v3.Listener
    name: <gateway-namespace>/<gateway-name>/<listener-name>   # e.g. envoy-gateway-system/ai-gw/http
    operation:
      op: replace
      path: /default_filter_chain/filters/0/typed_config/http_filters/0/disabled
      value: false

Confirm the patch took effect:

kubectl get envoypatchpolicy enable-apikey-auth -n envoy-gateway-system \
  -o jsonpath='{.status.ancestors[*].conditions[?(@.type=="Programmed")].status}'
# expect: True