Epic: Authentication

[shaneutt]

Auth primitives in the proxy layer for cloud-native deployments. Covers inline (JWT), external (ext_authz), API key, and client certificate authentication patterns.

JWT Authentication

• Signature verification: RS256, ES256, HS256
• JWKS endpoint support with caching and key rotation
• Configurable claims validation: iss, aud, exp, nbf
• Claims extraction into request headers and FilterContext
• Multiple token sources: Authorization header, cookie, query parameter
• 401 with WWW-Authenticate on failure
• Default to required/strict (no security footgun)

External Authorization (ext_authz)

• gRPC and HTTP callout to external auth service
• Envoy ext_authz protocol compatibility
• Configurable fail-open vs fail-closed (default fail-closed)
• Caching of auth decisions with configurable TTL
• Forward selected request headers to auth service
• Inject auth response headers into upstream request

OAuth2 / OIDC

• Token introspection endpoint support
• OIDC discovery via .well-known/openid-configuration
• Token exchange for upstream service calls
• Refresh token handling

Client Certificate Authentication

• CN (Common Name) extraction from client certificate subject
• SAN (Subject Alternative Name) extraction: DNS, URI, IP
• Inject extracted identity fields into FilterContext
• Promote certificate fields to request headers for routing and authorization

API Key Validation

• Extract API key from configurable header (e.g. X-API-Key) or query parameter
• Lookup backend: in-memory map or KV store registry
• Constant-time comparison to prevent timing attacks
• Optional: map API key to tenant identity in FilterContext

Pipeline Integration

• Auth filters run early in the pipeline, before routing and rate limiting
• Auth identity available in FilterContext for downstream filters (rate limiting, routing, access logging)
• Composable: JWT + ext_authz + API key filters can coexist in the same pipeline
• Interaction with multi-tenancy: auth identity feeds tenant identification

Auth Failure Responses

• 401 Unauthorized: missing or invalid credentials
• 403 Forbidden: valid credentials but insufficient permissions
• WWW-Authenticate header formats: Bearer, Bearer realm="..." error="invalid_token", Basic
• Configurable error response body (JSON)

Auth Token Management

• Injection of authentication tokens (egress or e/w)
• Source discrimination (e.g. network and/or bearer token)
• Token management to 3rd party services (e.g. Anthropic, Mistral)