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`:

```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
```bash
npm install passport passport-saml passport-oauth2 passport-openidconnect ldapjs express-session
```

### 2. Database Migration
```bash
# Create tenant table and update user table
npm run migrate
```

### 3. Environment Variables
```env
# 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:

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
// 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
```javascript
POST /api/tenants
{
  "name": "Customer Company",
  "slug": "customer",
  "auth_provider": "saml",
  "auth_config": { ... },
  "subscription_type": "premium"
}
```

### Login Flow
```javascript
// 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
```javascript
// 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
# 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
```yaml
# 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
```bash
# 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
```sql
-- 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.