API Gateway Authentication Patterns

solution: | Auth Methods at Gateway:

1. JWT Validation (most common)

   • Gateway verifies signature (JWKS), expiry, claims (aud, iss, scope)
   • JWKS caching: fetch periodically, cache by kid
   • Claims injection: X-User-ID, X-User-Roles, X-Scopes headers to upstream
   • Revocation: short expiry (15min) + refresh token; or token introspection endpoint

2. API Key (simple, partner integrations)

   • Gateway validates key against store (Redis, DB)
   • Rate limiting: per-key quotas
   • Rotation: key versioning, overlap period
   • Scopes: key tied to permissions

3. OAuth2 Introspection (RFC 7662)

   • Gateway calls auth server /introspect for opaque tokens
   • Caching: cache introspection result (TTL 30-60s)
   • Use: legacy opaque tokens, centralized auth server

4. mTLS (zero-trust, service-to-service)

   • Gateway terminates mTLS, verifies client cert
   • SPIFFE/SPIRE: workload identity, automatic cert rotation
   • Header injection: X-Client-SPIFFE-ID for upstream authz

5. OIDC / Social Login (end-user)

   • Gateway initiates OIDC flow, stores session (cookie/token)
   • Session: encrypted cookie or token store
   • Logout: RP-initiated, back-channel logout

Patterns:

• Gateway validates, services trust: Gateway injects X-User-ID, X-Roles; services read headers (zero-trust: services also verify gateway mTLS)
• Gateway validates, services re-validate: defense in depth (services also check JWT)
• Gateway passes token: services validate themselves (simpler gateway, more service logic)

Performance:

• JWKS caching: 5-15 min TTL, background refresh
• Introspection caching: 30-60s TTL
• Header injection: minimal overhead

Token Propagation:

• Pass-through: forward Authorization header (services validate)
• Exchange: gateway validates, issues internal JWT for service-to-service
• mTLS: gateway terminates, re-encrypts with internal CA

Tools: Kong, Envoy, AWS API Gateway, Apigee, Kong, Traefik, NGINX Plus, ORY Oathkeeper. whenToUse:

• "Multiple services needing auth"
• "Multiple auth methods (JWT, API key, mTLS)"
• "Centralized auth policy enforcement" whenNotToUse:
• "Single service (auth in service fine)"
• "Team not ready for gateway ownership"
• "Ultra-low latency (extra hop)" pros:
• "Centralized: policy in one place"
• "Services simplified: read headers, not validate tokens"
• "Flexible: multiple auth methods, easy to add"
• "Observability: all auth decisions logged at gateway" cons:
• "Gateway = auth SPOF (HA required)"
• "Header injection: services must trust gateway"
• "Token propagation: complexity vs security"
• "Gateway config = auth policy (deploy for policy change)" costProfile: infra: "Medium — gateway cluster, JWKS cache" operational: "Medium — cert rotation, policy updates" cognitive: "Medium — auth flows, token propagation" operationalBurden: "medium" maturity: "established" tradeoffAxes:
• "validate at gateway vs pass-through: security vs simplicity"
• "JWT vs opaque token: self-contained vs introspection"
• "mTLS vs JWT: service-to-service vs end-user" failureModes:
• JWKS fetch fails: cache expiry → all auth fails
• Clock skew: token expiry validation fails
• Gateway down: all auth fails (mitigate: HA)
• Header injection spoofing: if gateway not mTLS verified
• Introspection cache stale: revoked token still accepted realWorldExamples:
• system: "Kong JWT Plugin" sourceUrl: "https://docs.konghq.com/hub/kong-inc/jwt/"
• system: "Envoy JWT Filter" sourceUrl: "https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter"
• system: "AWS API Gateway Authorizers" sourceUrl: "https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html"
• system: "ORY Oathkeeper" sourceUrl: "https://www.ory.sh/oathkeeper/"
• system: "Kong mTLS" sourceUrl: "https://docs.konghq.com/hub/kong-inc/mtls-auth/" alternatives: ["service-level-auth", "sidecar-proxy", "oauth2-proxy", "sidecar-auth"] relatedPatterns: ["api-gateway", "jwt", "mTLS", "oauth2", "zero-trust", "service-mesh", "spiffe"] competencyDomains: ["security-compliance", "distribution-communication", "reliability-ops", "deployment", "economics-evolution"]

---