Skip to main content

0007: API Gateway Security Policy

Date: 2025-08-04

Status: Accepted

Context​

The API Gateway is the primary security enforcement point for all synchronous traffic entering the Citadel platform. It must have a clear, robust, and standard-based strategy for authenticating all incoming requests, whether they originate from an end-user's browser or a backend machine client (service-to-service communication).

Decision​

We will adopt a unified security policy based on the OAuth 2.0 Resource Server pattern.

  1. Token-Based Authentication: The gateway will secure all protected routes by requiring a valid JSON Web Token (JWT) to be passed in the Authorization: Bearer <token> HTTP header.

  2. JWKS for Validation: The gateway will validate the signature of incoming JWTs by fetching the public key set from the IAM Service's public OIDC JWKS (JSON Web Key Set) endpoint. The URL for this endpoint will be configurable.

  3. Unified Mechanism: This single validation mechanism will handle JWTs issued for different client types:

    • End-User Tokens: Issued by the IAM Service to authenticated users (e.g., via an Authorization Code Flow).
    • Service-to-Service (S2S) Tokens: Issued by the IAM Service to machine clients (e.g., via a Client Credentials Flow).

The gateway's responsibility is limited to validating the token's signature, expiration, and issuer. It will then pass the validated token claims (e.g., sub, tenant_id, roles) to the upstream service for fine-grained authorization.

Consequences​

Positive:​

  • Standardization: This approach adheres to well-established industry standards (OAuth 2.0, OIDC, JWT), making the system easier to understand and integrate with.
  • Decoupling: The gateway does not need to know the IAM Service's private signing keys. It only needs the public URL of the JWKS endpoint, which promotes loose coupling and better security.
  • Simplicity: A single, unified mechanism for validating all token types simplifies the gateway's configuration and logic.

Negative:​

  • JWKS Endpoint Dependency: The IAM Service's JWKS endpoint becomes a critical dependency for the gateway. If this endpoint is unavailable, the gateway cannot validate new tokens.
  • Mitigation: The gateway implementation must aggressively cache the JWKS response according to the cache-control headers to minimize latency and improve resilience against temporary IAM Service outages.