0060: User Directory Security Model

Date: 2025-12-22

Status: Accepted

Context

With the adoption of the Localhost Adapter Pattern (ADR-0059), the user-directory-service communicates with its adapters over HTTP. We need to define the security model for this inter-process communication.

While "Zero Trust" is a core principle of Citadel, applying it blindly to localhost traffic within a single Pod can introduce unnecessary latency and operational complexity (certificate management) without significantly reducing the attack surface.

Decision

We will adopt a Configurable Trust Model that defaults to trusting the Pod boundary but allows for stricter security where required.

1. Trust Boundary: By default, we treat the Kubernetes Pod (or the host machine in non-containerized deployments) as the trust boundary. Traffic over localhost (loopback interface) is considered trusted.

2. Default Mode: Implicit Trust:

   • In the default configuration, the main service communicates with sidecar adapters via plain HTTP over localhost.
   • No additional authentication headers or TLS encryption are required for these internal calls.
   • Justification: Access to localhost implies the attacker already has shell access to the container/pod, at which point network-level auth provides minimal additional protection.

3. Configurable Zero Trust: To support high-security environments or deployments where adapters might run on different hosts (breaking the sidecar pattern), the service will support a SECURITY_MODE configuration:

   • api_key Mode:

     • The main service and adapters are configured with a shared secret (e.g., INTERNAL_API_KEY).
     • The main service includes this key in an X-Internal-Auth-Key header for every request.
     • Adapters validate this header and reject requests without it.

   • mtls Mode:

     • The main service and adapters are configured with client and server certificates signed by a common internal CA.
     • Mutual TLS (mTLS) is enforced for all connections.
     • This provides both strong authentication and encryption-in-transit, satisfying strict compliance requirements (e.g., FIPS, PCI-DSS).

Consequences

Positive

• Performance: The default mode avoids the CPU overhead of TLS handshakes and cryptographic operations for high-volume internal traffic.
• Simplicity: Developers do not need to manage certificates or secrets for local development.
• Flexibility: The platform can still be deployed in "Paranoid Mode" (mTLS) for customers with strict security requirements without changing the application code.

Negative

• Deviation from Pure Zero Trust: The default mode technically violates strict Zero Trust principles ("never trust, always verify").
• Configuration Complexity: Supporting three different security modes adds complexity to the application configuration and startup logic.