Documentation Configuration Guide

Multi-Tenant Database Configuration Guide

Overview

The application now supports database-per-tenant architecture, allowing each organization to have its own isolated database while maintaining a central SaaS management database. ---

Configuration Files

1. includes/config.php

Multi-Tenant Settings: ``php // Enable/disable multi-tenant mode define('TENANT_DB_MIGRATION', false); // Set to true to enable // Encryption key for tenant database passwords define('DB_ENCRYPTION_KEY', 'your-secure-key-here'); // Central database configuration (SaaS management) define('CENTRAL_DB_HOST', DB_HOST); define('CENTRAL_DB_USER', DB_USER); define('CENTRAL_DB_PASS', DB_PASS); define('CENTRAL_DB_NAME', DB_NAME); ` Generate Encryption Key: `bash php -r "echo bin2hex(random_bytes(32));" ` ---

Database Architecture

Central SaaS Database

Tables:
  • organizations - Organization registry
  • users - User accounts
  • user_org_mapping - User-to-org relationships
  • subscriptions - Billing and subscriptions
  • org_db_connections - Tenant database connections
  • org_db_connections_audit - Connection change audit trail
Purpose: Manages the SaaS platform itself

---

Tenant Databases

Tables:
  • risk_register - Risk management
  • vulnerabilities - Vulnerability tracking
  • assets - Asset inventory
  • siem_agents - SIEM agents
  • siem_alerts - Security alerts
  • projects - Projects
  • attack_sessions - AutoPentest sessions
  • All other tenant-specific data
Purpose: Isolated data storage per organization

---

Deployment Modes

Mode 1: Legacy (Single Shared Database)

Configuration: `php define('TENANT_DB_MIGRATION', false); ` Behavior:
  • All organizations share one database
  • Data separated by org_id column
  • Backward compatible with existing code
Use Case: Current production setup

---

Mode 2: Multi-Tenant (Database Per Organization)

Configuration: `php define('TENANT_DB_MIGRATION', true); ` Behavior:
  • Each organization has isolated database
  • Central DB for SaaS management
  • Automatic connection routing
Use Case: Enhanced security, customer-owned databases

---

Connection Management

Automatic Routing

When TENANT_DB_MIGRATION = true: `php // $conn automatically routes to: // - Tenant DB if org context exists // - Central DB if no org context // Explicit connections: $tenantConn = getTenantConnection(); // Current org's database $centralConn = getCentralConnection(); // SaaS management database `

Helper Functions

`php // Execute query on tenant database $result = queryTenant("SELECT * FROM risk_register"); // Execute query on central database $result = queryCentral("SELECT * FROM organizations"); // Switch organization context switchOrgContext($newOrgId); ` ---

Tenant Database Setup

Quick Start

`bash

Interactive setup wizard

php tenant-db-setup/setup_wizard.php

Test connection

php tenant-db-setup/test_connection.php --org-id=1 `

Manual Setup

`bash

1. Provision database

php tenant-db-setup/setup_wizard.php --scenario=managed --org-id=1

2. Test connection

php tenant-db-setup/test_connection.php --org-id=1 --verbose

3. Enable multi-tenant mode

Edit includes/config.php:

define('TENANT_DB_MIGRATION', true); ` ---

Security

Password Encryption

All tenant database passwords are encrypted using AES-256-GCM before storage. Encryption Process:
  • Generate random IV (12 bytes)
  • Encrypt password with AES-256-GCM
  • Store: base64(encrypted_data::IV::tag)
    • Decryption:
    • Automatic via TenantDatabaseManager
    • Requires DB_ENCRYPTION_KEY

    SSL/TLS Support

    For customer databases requiring SSL:

    `php // In org_db_connections table: db_ssl_enabled = 1 db_ssl_ca = '/path/to/ca-cert.pem' `

    ---

    Migration Path

    Phase 1: Foundation (Current)

    • ✅ Database schema created
    • ✅ Connection manager implemented
    • ✅ Helper functions added
    • ✅ Deployment tools ready
    • ✅ Backward compatibility maintained

    Phase 2: Testing

    • Test with pilot organizations
    • Verify data isolation
    • Performance benchmarking
    • Rollback testing

    Phase 3: Gradual Rollout

    • Enable for new organizations first
    • Migrate existing orgs in batches
    • Monitor system health
    • Maintain fallback capability
    ---

    Troubleshooting

    Connection Fails

    Check:
  • Encryption key configured
  • Tenant DB connection registered
  • Firewall allows connection
  • Credentials correct
    • Test:     `bash php tenant-db-setup/test_connection.php --org-id=1 --verbose `

    Performance Issues

    Check:
  • Connection pooling enabled
  • Query optimization
  • Network latency (for remote DBs)
    • Monitor:     `php $stats = TenantDatabaseManager::getStats(); print_r($stats); `

    Rollback to Legacy Mode

    Emergency Rollback:     `php // In includes/config.php: define('TENANT_DB_MIGRATION', false); ` Application immediately reverts to shared database mode. ---

    Best Practices

    1. Always Use Helper Functions

    Good:     `php $result = queryTenant("SELECT * FROM risk_register"); ` Avoid: `php $result = $conn->query("SELECT * FROM risk_register WHERE org_id = $orgId"); `

    2. Explicit Connection Selection

    For Central DB queries:     `php $orgs = queryCentral("SELECT * FROM organizations"); ` For Tenant DB queries: `php $risks = queryTenant("SELECT * FROM risk_register"); `

    3. Test Before Enabling

    Always test tenant database setup before enabling multi-tenant mode:     `bash php tenant-db-setup/test_connection.php --all-orgs ` ---

    Support

    For issues or questions:
  • Check tenant-db-setup/README.md
  • Review multi_tenant_db_separation_plan.md
  • Test connections with test_connection.php
  • Check logs in logs/tenant-db-setup.log`