Chapter 3: Security and Multi-Tenancy

The MATIH Platform is designed from the ground up as a secure, multi-tenant system. Every layer of the architecture -- from network policies to application code, from data encryption to compliance controls -- enforces isolation between tenants and protects sensitive data. This chapter provides a comprehensive tour of the security model, its implementation, and the operational practices that keep the platform secure.

What You Will Learn

By the end of this chapter, you will understand:

• Authentication mechanisms including JWT token flows, OAuth2 integration, multi-factor authentication (MFA), and API key management
• Authorization via Role-Based Access Control (RBAC) with hierarchical role inheritance, resource-level permissions, and Open Policy Agent (OPA) integration
• Tenant isolation through Kubernetes namespace boundaries, thread-local tenant context propagation, and zero-trust service communication
• Secret management using Kubernetes Secrets, External Secrets Operator (ESO), and cloud key vault integration for Azure, AWS, and GCP
• Encryption at rest and in transit, including AES-256-GCM authenticated encryption with per-tenant key management
• Compliance patterns for SOC 2, HIPAA, and GDPR, including audit logging, data classification, consent management, and data subject request handling

Chapter Structure

Security Architecture at a Glance

The MATIH security model operates at every layer of the stack:

Key Source Files

The security implementation is primarily located in the commons library and the IAM service:

Design Principles

The security architecture is guided by several core principles:

1. Defense in depth. No single layer is trusted to provide complete security. Every boundary enforces its own checks.

2. Zero trust by default. Services do not trust each other implicitly. Every inter-service call carries a signed JWT with scoped permissions.

3. Tenant isolation is non-negotiable. Data belonging to one tenant must never be accessible to another, whether through application bugs, query injection, or infrastructure misconfiguration.

4. Secrets never appear in code. All credentials are injected at runtime through Kubernetes Secrets and External Secrets Operator. No passwords, tokens, or keys are ever committed to version control.

5. Audit everything. Every authentication event, authorization decision, data access, and configuration change is logged to an immutable audit trail.

6. Encryption is mandatory. Data is encrypted in transit with TLS and at rest with AES-256-GCM. Per-tenant encryption keys provide cryptographic isolation.

How This Chapter Connects

This chapter builds on the architecture introduced in Chapter 2 and directly informs the operational chapters that follow. The IAM service described here is explored in greater depth in Chapter 6. The tenant isolation model connects to the tenant lifecycle documented in Chapter 7. The Kubernetes security policies discussed here are part of the broader infrastructure covered in Chapter 17.

Begin with Authentication to understand how users and services identify themselves to the platform.