Skip to main content

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.