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

cd backend
npm run create-central-admin

Follow the interactive prompts to create your admin user.

Environment Variable Method

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:

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

Response:

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

Tenant Login (for comparison):

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

{
  "sub": "user-id",
  "email": "admin@platform.com",
  "isCentralAdmin": true,
  "iat": 1234567890,
  "exp": 1234654290
}

Tenant User Token Payload

{
  "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

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.