Add record access strategy
This commit is contained in:
Francisco Gaona
231
docs/CENTRAL_ADMIN_AUTH_GUIDE.md
Normal file
231
docs/CENTRAL_ADMIN_AUTH_GUIDE.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user