neo/docs/CENTRAL_LOGIN.md

Central Admin Login

Overview

The platform supports seamless authentication for both tenant users and central administrators using the same login endpoint. The system automatically determines which database to authenticate against based on the subdomain.

How It Works

Subdomain-Based Routing

The authentication flow uses subdomain detection to determine the authentication context:

1. Central Subdomains (e.g., central.yourdomain.com, admin.yourdomain.com)

   • Authenticates against the central database
   • Used for platform administrators
   • Configured via CENTRAL_SUBDOMAINS environment variable

2. Tenant Subdomains (e.g., acme.yourdomain.com, client1.yourdomain.com)

   • Authenticates against the tenant's database
   • Used for regular tenant users
   • Each tenant has its own isolated database

Configuration

Set the central subdomains in your .env file:

# Comma-separated list of subdomains that access the central database
CENTRAL_SUBDOMAINS="central,admin"

Implementation Details

1. Tenant Middleware (tenant.middleware.ts)

The middleware extracts the subdomain from the request and:

• Checks if it matches a central subdomain
• If yes: Skips tenant resolution and attaches subdomain to request
• If no: Resolves the tenant ID from the subdomain and attaches it to request

2. Auth Service (auth.service.ts)

The auth service has branching logic in validateUser() and register():

• Checks if the subdomain is in the central list
• Routes to validateCentralUser() or normal tenant user validation
• Central users are authenticated against the central database
• Tenant users are authenticated against their tenant's database

3. Auth Controller (auth.controller.ts)

The controller:

• Extracts subdomain from the request
• Validates tenant ID requirement (not needed for central subdomains)
• Passes subdomain to auth service for proper routing

Usage

Creating a Central Admin User

cd backend
npm run create-central-admin

Follow the prompts to enter:

• Email
• Password
• First Name (optional)
• Last Name (optional)

Logging In as Central Admin

1. Navigate to central.yourdomain.com (or whatever central subdomain you configured)
2. Enter your central admin email and password
3. You'll be authenticated against the central database

No special UI elements needed - the system automatically detects the subdomain!

Logging In as Tenant User

1. Navigate to yourtenantslug.yourdomain.com
2. Enter your tenant user credentials
3. You'll be authenticated against that tenant's database

Architecture Benefits

✅ Transparent to Frontend - No need for special "login as admin" checkboxes or UI elements ✅ Secure - Central and tenant authentication are completely separated ✅ Scalable - Easy to add more central subdomains by updating environment variable ✅ Clean Code - Single auth controller/service with clear branching logic ✅ Flexible - Can be used for both development (localhost) and production

Local Development

For local development, you can:

1. Use subdomain on localhost:

   central.localhost:3000
   acme.localhost:3000
   

2. Use x-tenant-id header (for tenant-specific requests):

   curl -H "x-tenant-id: acme-corp" http://localhost:3000/api/auth/login
   

3. For central admin, use central subdomain:

   curl http://central.localhost:3000/api/auth/login
   

Database Schema

Central Database (User model)

• Stores platform administrators
• Prisma schema: schema-central.prisma
• Fields: id, email, password, firstName, lastName, isActive, createdAt, updatedAt

Tenant Database (users table)

• Stores tenant-specific users
• Knex migrations: migrations/tenant/
• Fields: id, email, password, firstName, lastName, isActive, created_at, updated_at

Security Considerations

• Central admin credentials are never stored in tenant databases
• Tenant user credentials are never stored in the central database
• JWT tokens include user context (tenant ID or central admin flag)
• Subdomain validation prevents unauthorized access