neo/docs/CENTRAL_ADMIN_AUTH_GUIDE.md

# Central Admin Authentication Guide

## Overview

The platform now supports **two types of authentication**:

1. **Tenant Login** - Authenticates users against a specific tenant's database
2. **Central Admin Login** - Authenticates administrators against the central platform database

## Central vs Tenant Authentication

### Tenant Authentication (Default)
- Users login to their specific tenant database
- Each tenant has isolated user tables
- Access is scoped to the tenant's data
- API Endpoint: `/api/auth/login`
- Requires `x-tenant-id` header or subdomain detection

### Central Admin Authentication
- Administrators login to the central platform database
- Can manage all tenants and platform-wide features
- Users stored in the central database `users` table
- API Endpoint: `/api/central/auth/login`
- No tenant ID required

## Creating a Central Admin User

### Quick Start

```bash
cd backend
npm run create-central-admin
```

Follow the interactive prompts to create your admin user.

### Environment Variable Method

```bash
EMAIL=admin@platform.com \
PASSWORD=SecureP@ssw0rd \
FIRST_NAME=Admin \
LAST_NAME=User \
ROLE=superadmin \
npm run create-central-admin
```

### Role Types

- **admin** - Standard administrator with platform management access
- **superadmin** - Super administrator with full platform access

## Logging In as Central Admin

### Frontend Login

1. Navigate to the login page (`/login`)
2. **Check the "Login as Central Admin" checkbox**
3. Enter your central admin email and password
4. Click "Login to Central"

The checkbox toggles between:
- ✅ **Checked** - Authenticates against central database
- ⬜ **Unchecked** - Authenticates against tenant database (default)

### API Login (Direct)

**Central Admin Login:**
```bash
curl -X POST http://localhost:3000/api/central/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@platform.com",
    "password": "SecureP@ssw0rd"
  }'
```

**Response:**
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "cm5a1b2c3d4e5f6g7h8i9j0k",
    "email": "admin@platform.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "superadmin",
    "isCentralAdmin": true
  }
}
```

**Tenant Login (for comparison):**
```bash
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: tenant1" \
  -d '{
    "email": "user@tenant1.com",
    "password": "password123"
  }'
```

## JWT Token Differences

### Central Admin Token Payload
```json
{
  "sub": "user-id",
  "email": "admin@platform.com",
  "isCentralAdmin": true,
  "iat": 1234567890,
  "exp": 1234654290
}
```

### Tenant User Token Payload
```json
{
  "sub": "user-id",
  "email": "user@tenant1.com",
  "iat": 1234567890,
  "exp": 1234654290
}
```

The `isCentralAdmin` flag in the JWT can be used to determine if the user is a central admin.

## Database Schema

### Central Database - `users` Table

```sql
CREATE TABLE users (
  id VARCHAR(30) PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  password VARCHAR(255) NOT NULL,
  firstName VARCHAR(100),
  lastName VARCHAR(100),
  role VARCHAR(50) DEFAULT 'admin',
  isActive BOOLEAN DEFAULT true,
  createdAt DATETIME DEFAULT CURRENT_TIMESTAMP,
  updatedAt DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

### Tenant Database - `users` Table

Tenant databases have their own separate `users` table with similar structure but tenant-specific users.

## Security Considerations

1. **Separate Password Storage** - Central admin passwords are stored separately from tenant user passwords
2. **Role-Based Access** - Central admins have different permissions than tenant users
3. **JWT Identification** - The `isCentralAdmin` flag helps identify admin users
4. **Encryption** - All passwords are hashed using bcrypt with salt rounds

## Common Use Cases

### Platform Administration
- **Login as:** Central Admin
- **Can do:** 
  - Create/manage tenants
  - View all tenant information
  - Manage platform-wide settings
  - Access tenant provisioning APIs

### Tenant Management
- **Login as:** Tenant User
- **Can do:**
  - Access tenant-specific data
  - Manage records within the tenant
  - Use tenant applications
  - Limited to tenant scope

## Troubleshooting

### "Tenant ID is required" Error
- You're trying to login to tenant endpoint without tenant ID
- Solution: Either provide `x-tenant-id` header or use central admin login

### "Invalid credentials" with Central Login
- Check that you're using the "Login as Central Admin" checkbox
- Verify the user exists in the central database
- Use the script to create a central admin if needed

### "User already exists"
- A central admin with that email already exists
- Use a different email or reset the existing user's password

## Architecture

```
┌─────────────────────────────────────────┐
│         Frontend Login Form              │
│  ┌────────────────────────────────────┐ │
│  │ ☑ Login as Central Admin           │ │
│  └────────────────────────────────────┘ │
└──────────────┬──────────────────────────┘
               │
       ┌───────┴────────┐
       │    Checked?    │
       └───────┬────────┘
               │
    ┌──────────┴──────────┐
    │                     │
    ▼                     ▼
/api/central/auth/login  /api/auth/login
    │                     │
    ▼                     ▼
Central Database      Tenant Database
(users table)        (users table)
```

## API Endpoints Summary

| Endpoint | Purpose | Requires Tenant ID | Database |
|----------|---------|-------------------|----------|
| `POST /api/central/auth/login` | Central admin login | ❌ No | Central |
| `POST /api/central/auth/register` | Create central admin | ❌ No | Central |
| `POST /api/auth/login` | Tenant user login | ✅ Yes | Tenant |
| `POST /api/auth/register` | Create tenant user | ✅ Yes | Tenant |

## Next Steps

1. Create your first central admin user
2. Login with the central admin checkbox enabled
3. Access platform administration features
4. Manage tenants and platform settings

For tenant management and provisioning, see [TENANT_MIGRATION_GUIDE.md](../TENANT_MIGRATION_GUIDE.md).