drone-detector/docs/MULTI_TENANT_AUTH_SETUP.md

Multi-Tenant Authentication Setup Guide

Overview

This guide explains how to configure your UAV Detection System for multi-tenant authentication with support for various identity providers including Active Directory, SAML, OAuth, and LDAP.

🏗️ Architecture

Tenant Isolation

• Subdomain-based: customer1.yourapp.com, customer2.yourapp.com
• Header-based: X-Tenant-ID: customer1
• JWT-based: Token contains tenant information

Supported Authentication Providers

1. Local JWT (default)
2. SAML 2.0 (Active Directory/ADFS)
3. OAuth 2.0/OpenID Connect (Azure AD, Google, etc.)
4. LDAP (Direct Active Directory)
5. Custom SSO

📦 Required Dependencies

Add these to your package.json:

{
  "dependencies": {
    "passport": "^0.6.0",
    "passport-saml": "^3.2.4",
    "passport-oauth2": "^1.7.0",
    "passport-openidconnect": "^0.1.1",
    "ldapjs": "^3.0.3",
    "express-session": "^1.17.3"
  }
}

🛠️ Installation

1. Install Dependencies

npm install passport passport-saml passport-oauth2 passport-openidconnect ldapjs express-session

2. Database Migration

# Create tenant table and update user table
npm run migrate

3. Environment Variables

# Multi-tenant configuration
BASE_URL=https://yourapp.com
DOMAIN_NAME=yourapp.com
SESSION_SECRET=your-session-secret-key

# Default tenant (backward compatibility)
DEFAULT_TENANT_ID=default

4. Update Server Configuration

In server/index.js, add the auth routes:

// Add multi-tenant auth routes
app.use('/auth', require('./routes/auth'));
app.use('/api/tenants', require('./routes/tenants'));

// Update existing auth middleware
const MultiTenantAuth = require('./middleware/multi-tenant-auth');
const multiAuth = new MultiTenantAuth();

// Replace existing authenticateToken with multi-tenant version
app.use('/api', (req, res, next) => {
  multiAuth.authenticate(req, res, next);
});

🔧 Configuration Examples

1. Active Directory SAML Integration

// Tenant configuration for SAML
const tenantConfig = {
  name: "Acme Corporation",
  slug: "acme",
  auth_provider: "saml",
  auth_config: {
    sso_url: "https://adfs.acme.com/adfs/ls/",
    certificate: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    issuer: "urn:acme:uav-detection",
    logout_url: "https://adfs.acme.com/adfs/ls/?wa=wsignout1.0"
  },
  role_mapping: {
    "Domain Admins": "admin",
    "UAV-Operators": "operator",
    "UAV-Viewers": "viewer",
    "default": "viewer"
  }
};

2. Azure AD OAuth Integration

// Tenant configuration for OAuth (Azure AD)
const tenantConfig = {
  name: "TechCorp",
  slug: "techcorp",
  auth_provider: "oauth",
  auth_config: {
    client_id: "your-azure-app-id",
    client_secret: "your-azure-app-secret",
    authorization_url: "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize",
    token_url: "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token",
    userinfo_url: "https://graph.microsoft.com/v1.0/me",
    scopes: ["openid", "profile", "email", "User.Read"]
  },
  user_mapping: {
    username: ["preferred_username", "userPrincipalName"],
    email: ["mail", "email"],
    firstName: ["givenName"],
    lastName: ["surname"]
  }
};

3. Direct LDAP Integration

// Tenant configuration for LDAP
const tenantConfig = {
  name: "Enterprise Corp",
  slug: "enterprise",
  auth_provider: "ldap",
  auth_config: {
    url: "ldaps://dc.enterprise.com:636",
    base_dn: "dc=enterprise,dc=com",
    bind_dn: "cn=service-account,ou=service-accounts,dc=enterprise,dc=com",
    bind_password: "service-account-password",
    user_search_filter: "(sAMAccountName={username})",
    domain: "ENTERPRISE"
  }
};

🚀 API Usage

Create Tenant

POST /api/tenants
{
  "name": "Customer Company",
  "slug": "customer",
  "auth_provider": "saml",
  "auth_config": { ... },
  "subscription_type": "premium"
}

Login Flow

// 1. Get tenant auth config
GET /auth/config/customer

// 2. For SSO providers, redirect to:
GET /auth/saml/customer/login
GET /auth/oauth/customer/login

// 3. For local/LDAP, use:
POST /auth/login
{
  "username": "user@customer.com",
  "password": "password"
}

Frontend Integration

// Determine authentication method
const authConfig = await fetch(`/auth/config/${tenantId}`);

if (authConfig.provider === 'saml') {
  // Redirect to SAML login
  window.location.href = `/auth/saml/${tenantId}/login`;
} else {
  // Show login form for local/LDAP
  showLoginForm();
}

🔐 Security Considerations

1. Certificate Management

• Store SAML certificates securely
• Rotate certificates regularly
• Validate certificate chains

2. Tenant Isolation

• Ensure users can only access their tenant's data
• Validate tenant context in all API calls
• Implement tenant-specific rate limiting

3. Configuration Security

• Encrypt sensitive configuration data
• Use environment variables for secrets
• Implement configuration validation

📋 Deployment Scenarios

SaaS Deployment

# Nginx configuration for subdomain routing
server {
    server_name *.yourapp.com;
    
    location / {
        proxy_pass http://app-server;
        proxy_set_header Host $host;
        proxy_set_header X-Tenant-ID $subdomain;
    }
}

On-Premise Deployment

# Docker Compose for on-premise
version: '3.8'
services:
  app:
    environment:
      - DEFAULT_TENANT_ID=onprem
      - AUTH_PROVIDER=ldap
      - LDAP_URL=ldap://company-dc:389

🧪 Testing

Test Authentication Configuration

# Test LDAP connection
curl -X POST /auth/test/customer \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer admin-token"

# Test SAML metadata
curl /auth/saml/customer/metadata

User Creation Flow

1. User authenticates with external provider
2. System maps external attributes to internal user
3. User record created/updated with tenant association
4. JWT issued with tenant context

🔄 Migration Strategy

Existing Customers

1. Create default tenant for existing users
2. Gradually migrate to tenant-specific authentication
3. Maintain backward compatibility during transition

Data Migration

-- Create default tenant
INSERT INTO tenants (name, slug, auth_provider) 
VALUES ('Default', 'default', 'local');

-- Associate existing users with default tenant
UPDATE users SET tenant_id = (
  SELECT id FROM tenants WHERE slug = 'default'
) WHERE tenant_id IS NULL;

📞 Support

Common Issues

1. SAML Certificate Errors: Verify certificate format and validity
2. LDAP Connection Failures: Check network connectivity and credentials
3. OAuth Scope Issues: Ensure required scopes are granted
4. Tenant Not Found: Verify tenant slug and domain configuration

Monitoring

• Log authentication attempts and failures
• Monitor tenant-specific metrics
• Alert on authentication service health

This architecture provides a scalable foundation for both SaaS and on-premise deployments while maintaining security and user experience.