131 lines
4.1 KiB
Markdown
131 lines
4.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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):
|
|
```bash
|
|
curl -H "x-tenant-id: acme-corp" http://localhost:3000/api/auth/login
|
|
```
|
|
|
|
3. **For central admin, use central subdomain:**
|
|
```bash
|
|
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
|