Initial commit - Current state of vip-coordinator
This commit is contained in:
300
ROLE_BASED_ACCESS_CONTROL.md
Normal file
300
ROLE_BASED_ACCESS_CONTROL.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# Role-Based Access Control (RBAC) System
|
||||
|
||||
## Overview
|
||||
|
||||
The VIP Coordinator application implements a comprehensive role-based access control system with three distinct user roles, each with specific permissions and access levels.
|
||||
|
||||
## User Roles
|
||||
|
||||
### 1. System Administrator (`administrator`)
|
||||
**Highest privilege level - Full system access**
|
||||
|
||||
#### Permissions:
|
||||
- ✅ **User Management**: Create, read, update, delete users
|
||||
- ✅ **Role Management**: Assign and modify user roles
|
||||
- ✅ **VIP Management**: Full CRUD operations on VIP records
|
||||
- ✅ **Driver Management**: Full CRUD operations on driver records
|
||||
- ✅ **Schedule Management**: Full CRUD operations on schedules
|
||||
- ✅ **System Settings**: Access to admin panel and API configurations
|
||||
- ✅ **Flight Tracking**: Access to all flight tracking features
|
||||
- ✅ **Reports & Analytics**: Access to all system reports
|
||||
|
||||
#### API Endpoints Access:
|
||||
```
|
||||
POST /auth/users ✅ Admin only
|
||||
GET /auth/users ✅ Admin only
|
||||
PATCH /auth/users/:email/role ✅ Admin only
|
||||
DELETE /auth/users/:email ✅ Admin only
|
||||
|
||||
POST /api/vips ✅ Admin + Coordinator
|
||||
GET /api/vips ✅ All authenticated users
|
||||
PUT /api/vips/:id ✅ Admin + Coordinator
|
||||
DELETE /api/vips/:id ✅ Admin + Coordinator
|
||||
|
||||
POST /api/drivers ✅ Admin + Coordinator
|
||||
GET /api/drivers ✅ All authenticated users
|
||||
PUT /api/drivers/:id ✅ Admin + Coordinator
|
||||
DELETE /api/drivers/:id ✅ Admin + Coordinator
|
||||
|
||||
POST /api/vips/:vipId/schedule ✅ Admin + Coordinator
|
||||
GET /api/vips/:vipId/schedule ✅ All authenticated users
|
||||
PUT /api/vips/:vipId/schedule/:id ✅ Admin + Coordinator
|
||||
PATCH /api/vips/:vipId/schedule/:id/status ✅ All authenticated users
|
||||
DELETE /api/vips/:vipId/schedule/:id ✅ Admin + Coordinator
|
||||
```
|
||||
|
||||
### 2. Coordinator (`coordinator`)
|
||||
**Standard operational access - Can manage VIPs, drivers, and schedules**
|
||||
|
||||
#### Permissions:
|
||||
- ❌ **User Management**: Cannot manage users or roles
|
||||
- ✅ **VIP Management**: Full CRUD operations on VIP records
|
||||
- ✅ **Driver Management**: Full CRUD operations on driver records
|
||||
- ✅ **Schedule Management**: Full CRUD operations on schedules
|
||||
- ❌ **System Settings**: No access to admin panel
|
||||
- ✅ **Flight Tracking**: Access to flight tracking features
|
||||
- ✅ **Driver Availability**: Can check driver conflicts and availability
|
||||
- ✅ **Status Updates**: Can update event statuses
|
||||
|
||||
#### Typical Use Cases:
|
||||
- Managing VIP arrivals and departures
|
||||
- Assigning drivers to VIPs
|
||||
- Creating and updating schedules
|
||||
- Monitoring flight statuses
|
||||
- Coordinating transportation logistics
|
||||
|
||||
### 3. Driver (`driver`)
|
||||
**Limited access - Can view assigned schedules and update status**
|
||||
|
||||
#### Permissions:
|
||||
- ❌ **User Management**: Cannot manage users
|
||||
- ❌ **VIP Management**: Cannot create/edit/delete VIPs
|
||||
- ❌ **Driver Management**: Cannot manage other drivers
|
||||
- ❌ **Schedule Creation**: Cannot create or delete schedules
|
||||
- ✅ **View Schedules**: Can view VIP schedules and assigned events
|
||||
- ✅ **Status Updates**: Can update status of assigned events
|
||||
- ✅ **Personal Schedule**: Can view their own complete schedule
|
||||
- ❌ **System Settings**: No access to admin features
|
||||
|
||||
#### API Endpoints Access:
|
||||
```
|
||||
GET /api/vips ✅ View only
|
||||
GET /api/drivers ✅ View only
|
||||
GET /api/vips/:vipId/schedule ✅ View only
|
||||
PATCH /api/vips/:vipId/schedule/:id/status ✅ Can update status
|
||||
GET /api/drivers/:driverId/schedule ✅ Own schedule only
|
||||
```
|
||||
|
||||
#### Typical Use Cases:
|
||||
- Viewing assigned VIP transportation schedules
|
||||
- Updating event status (en route, completed, delayed)
|
||||
- Checking personal daily/weekly schedule
|
||||
- Viewing VIP contact information and notes
|
||||
|
||||
## Authentication Flow
|
||||
|
||||
### 1. Google OAuth Integration
|
||||
- Users authenticate via Google OAuth 2.0
|
||||
- First user automatically becomes `administrator`
|
||||
- Subsequent users default to `coordinator` role
|
||||
- Administrators can change user roles after authentication
|
||||
|
||||
### 2. JWT Token System
|
||||
- Secure JWT tokens issued after successful authentication
|
||||
- Tokens include user role information
|
||||
- Middleware validates tokens and role permissions on each request
|
||||
|
||||
### 3. Role Assignment
|
||||
```typescript
|
||||
// First user becomes admin
|
||||
const userCount = await databaseService.getUserCount();
|
||||
const role = userCount === 0 ? 'administrator' : 'coordinator';
|
||||
```
|
||||
|
||||
## Security Implementation
|
||||
|
||||
### Middleware Protection
|
||||
```typescript
|
||||
// Authentication required
|
||||
app.get('/api/vips', requireAuth, async (req, res) => { ... });
|
||||
|
||||
// Role-based access
|
||||
app.post('/api/vips', requireAuth, requireRole(['coordinator', 'administrator']),
|
||||
async (req, res) => { ... });
|
||||
|
||||
// Admin only
|
||||
app.get('/auth/users', requireAuth, requireRole(['administrator']),
|
||||
async (req, res) => { ... });
|
||||
```
|
||||
|
||||
### Frontend Role Checking
|
||||
```typescript
|
||||
// User Management component
|
||||
if (currentUser?.role !== 'administrator') {
|
||||
return (
|
||||
<div className="p-6 bg-red-50 border border-red-200 rounded-lg">
|
||||
<h2 className="text-xl font-semibold text-red-800 mb-2">Access Denied</h2>
|
||||
<p className="text-red-600">You need administrator privileges to access user management.</p>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Database Schema
|
||||
|
||||
### Users Table
|
||||
```sql
|
||||
CREATE TABLE users (
|
||||
id VARCHAR(255) PRIMARY KEY,
|
||||
email VARCHAR(255) UNIQUE NOT NULL,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
picture TEXT,
|
||||
role VARCHAR(50) NOT NULL DEFAULT 'coordinator',
|
||||
provider VARCHAR(50) NOT NULL DEFAULT 'google',
|
||||
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
|
||||
last_sign_in_at TIMESTAMP WITH TIME ZONE
|
||||
);
|
||||
|
||||
-- Indexes for performance
|
||||
CREATE INDEX idx_users_email ON users(email);
|
||||
CREATE INDEX idx_users_role ON users(role);
|
||||
```
|
||||
|
||||
## Role Transition Guidelines
|
||||
|
||||
### Promoting Users
|
||||
1. **Coordinator → Administrator**
|
||||
- Grants full system access
|
||||
- Can manage other users
|
||||
- Access to system settings
|
||||
- Should be limited to trusted personnel
|
||||
|
||||
2. **Driver → Coordinator**
|
||||
- Grants VIP and schedule management
|
||||
- Can assign other drivers
|
||||
- Suitable for supervisory roles
|
||||
|
||||
### Demoting Users
|
||||
1. **Administrator → Coordinator**
|
||||
- Removes user management access
|
||||
- Retains operational capabilities
|
||||
- Cannot access system settings
|
||||
|
||||
2. **Coordinator → Driver**
|
||||
- Removes management capabilities
|
||||
- Retains view and status update access
|
||||
- Suitable for field personnel
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Principle of Least Privilege
|
||||
- Users should have minimum permissions necessary for their role
|
||||
- Regular review of user roles and permissions
|
||||
- Temporary elevation should be avoided
|
||||
|
||||
### 2. Role Assignment Strategy
|
||||
- **Administrators**: IT staff, senior management (limit to 2-3 users)
|
||||
- **Coordinators**: Operations staff, event coordinators (primary users)
|
||||
- **Drivers**: Field personnel, transportation staff
|
||||
|
||||
### 3. Security Considerations
|
||||
- Regular audit of user access logs
|
||||
- Monitor for privilege escalation attempts
|
||||
- Implement session timeouts for sensitive operations
|
||||
- Use HTTPS for all authentication flows
|
||||
|
||||
### 4. Emergency Access
|
||||
- Maintain at least one administrator account
|
||||
- Document emergency access procedures
|
||||
- Consider backup authentication methods
|
||||
|
||||
## API Security Features
|
||||
|
||||
### 1. Token Validation
|
||||
```typescript
|
||||
export function requireAuth(req: Request, res: Response, next: NextFunction) {
|
||||
const authHeader = req.headers.authorization;
|
||||
|
||||
if (!authHeader || !authHeader.startsWith('Bearer ')) {
|
||||
return res.status(401).json({ error: 'No token provided' });
|
||||
}
|
||||
|
||||
const token = authHeader.substring(7);
|
||||
const user = verifyToken(token);
|
||||
|
||||
if (!user) {
|
||||
return res.status(401).json({ error: 'Invalid token' });
|
||||
}
|
||||
|
||||
(req as any).user = user;
|
||||
next();
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Role Validation
|
||||
```typescript
|
||||
export function requireRole(roles: string[]) {
|
||||
return (req: Request, res: Response, next: NextFunction) => {
|
||||
const user = (req as any).user;
|
||||
|
||||
if (!user || !roles.includes(user.role)) {
|
||||
return res.status(403).json({ error: 'Insufficient permissions' });
|
||||
}
|
||||
|
||||
next();
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Monitoring and Auditing
|
||||
|
||||
### 1. User Activity Logging
|
||||
- Track user login/logout events
|
||||
- Log role changes and who made them
|
||||
- Monitor sensitive operations (user deletion, role changes)
|
||||
|
||||
### 2. Access Attempt Monitoring
|
||||
- Failed authentication attempts
|
||||
- Unauthorized access attempts
|
||||
- Privilege escalation attempts
|
||||
|
||||
### 3. Regular Security Reviews
|
||||
- Quarterly review of user roles
|
||||
- Annual security audit
|
||||
- Regular password/token rotation
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Granular Permissions
|
||||
- Department-based access control
|
||||
- Resource-specific permissions
|
||||
- Time-based access restrictions
|
||||
|
||||
### 2. Advanced Security Features
|
||||
- Multi-factor authentication
|
||||
- IP-based access restrictions
|
||||
- Session management improvements
|
||||
|
||||
### 3. Audit Trail
|
||||
- Comprehensive activity logging
|
||||
- Change history tracking
|
||||
- Compliance reporting
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Feature | Administrator | Coordinator | Driver |
|
||||
|---------|--------------|-------------|--------|
|
||||
| User Management | ✅ | ❌ | ❌ |
|
||||
| VIP CRUD | ✅ | ✅ | ❌ |
|
||||
| Driver CRUD | ✅ | ✅ | ❌ |
|
||||
| Schedule CRUD | ✅ | ✅ | ❌ |
|
||||
| Status Updates | ✅ | ✅ | ✅ |
|
||||
| View Data | ✅ | ✅ | ✅ |
|
||||
| System Settings | ✅ | ❌ | ❌ |
|
||||
| Flight Tracking | ✅ | ✅ | ❌ |
|
||||
|
||||
**Last Updated**: June 2, 2025
|
||||
**Version**: 1.0
|
||||
Reference in New Issue
Block a user