appointment_system/backend/ADMIN_AUTH.md

Admin Authentication and Authorization System

Overview

This document describes the admin authentication and role-based access control (RBAC) system implemented for the overseas appointment backend.

Features

1. Admin Login - Secure authentication with JWT tokens
2. Role-Based Access Control (RBAC) - Three-tier permission system
3. Operation Logging - Audit trail for all admin actions
4. Login History - Track admin login attempts and device information

Admin Roles

The system supports three admin roles with hierarchical permissions:

Role	Level	Description
super_admin	3	Full system access, can manage all resources
admin	2	Can manage users, orders, and services
operator	1	Basic read access and limited operations

Role Hierarchy: Higher roles inherit permissions from lower roles.

• super_admin can access all admin and operator endpoints
• admin can access all operator endpoints
• operator has limited access

API Endpoints

Admin Login

POST /api/v1/admin/login

Request Body:

{
  "username": "admin",
  "password": "password123"
}

Response:

{
  "success": true,
  "data": {
    "admin": {
      "id": "uuid",
      "username": "admin",
      "email": "admin@example.com",
      "role": "admin",
      "status": "active",
      "lastLoginAt": "2025-12-01T12:00:00.000Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Get Admin Profile

GET /api/v1/admin/profile
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "admin": {
      "id": "uuid",
      "username": "admin",
      "email": "admin@example.com",
      "role": "admin",
      "status": "active"
    }
  }
}

Using Authentication Middleware

Authenticate Admin Requests

const { authenticateAdmin } = require('../middleware/auth');

router.get('/admin/users', authenticateAdmin, (req, res) => {
  // req.admin contains the authenticated admin
  // req.adminId contains the admin's ID
});

Apply Role-Based Access Control

const { authenticateAdmin } = require('../middleware/auth');
const { requireSuperAdmin, requireAdmin, requireOperator } = require('../middleware/rbac');

// Only super_admin can access
router.delete('/admin/users/:id', 
  authenticateAdmin, 
  requireSuperAdmin, 
  deleteUserController
);

// admin or super_admin can access
router.put('/admin/services/:id', 
  authenticateAdmin, 
  requireAdmin, 
  updateServiceController
);

// Any authenticated admin can access
router.get('/admin/statistics', 
  authenticateAdmin, 
  requireOperator, 
  getStatisticsController
);

Custom Role Requirements

const { requireRole } = require('../middleware/rbac');

// Only specific roles can access
router.post('/admin/reports', 
  authenticateAdmin, 
  requireRole(['admin', 'super_admin']), 
  generateReportController
);

Operation Logging

All admin operations are automatically logged for audit purposes. To enable logging on a route:

const { logAdminOperation } = require('../middleware/adminLogger');

router.put('/admin/users/:id', 
  authenticateAdmin, 
  requireAdmin,
  logAdminOperation,  // Add this middleware
  updateUserController
);

Logged Information:

• Timestamp
• Admin ID and username
• Admin role
• HTTP method and path
• IP address
• User agent
• Status code
• Request body (with sensitive data redacted)

Login History

Every successful admin login creates a record in the login_history table with:

• User ID
• User type (admin)
• IP address
• User agent
• Device information
• Login timestamp

Security Features

1. Password Hashing: Passwords are hashed using bcrypt with 10 salt rounds
2. JWT Tokens: Tokens expire after 7 days (configurable)
3. Token Type Validation: Admin tokens cannot be used for user endpoints and vice versa
4. Account Status Check: Inactive admin accounts cannot login
5. Sensitive Data Redaction: Passwords and secrets are redacted from logs

Error Codes

Code	Status	Description
MISSING_CREDENTIALS	400	Username or password not provided
INVALID_CREDENTIALS	401	Wrong username or password
ACCOUNT_INACTIVE	403	Admin account is inactive
MISSING_TOKEN	401	No authentication token provided
INVALID_TOKEN	401	Token is invalid or expired
INVALID_TOKEN_TYPE	401	Wrong token type (user token for admin endpoint)
UNAUTHORIZED	401	Authentication required
FORBIDDEN	403	Insufficient permissions for this action

Example Usage

Complete Admin Route Setup

const express = require('express');
const router = express.Router();
const { authenticateAdmin } = require('../middleware/auth');
const { requireAdmin } = require('../middleware/rbac');
const { logAdminOperation } = require('../middleware/adminLogger');
const userController = require('../controllers/admin/userController');

// Get all users (any admin)
router.get('/users', 
  authenticateAdmin, 
  logAdminOperation,
  userController.getUsers
);

// Update user status (admin or super_admin only)
router.put('/users/:id/status', 
  authenticateAdmin, 
  requireAdmin,
  logAdminOperation,
  userController.updateUserStatus
);

module.exports = router;

Frontend Integration

// Login
const response = await fetch('/api/v1/admin/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username, password })
});

const { data } = await response.json();
const { token } = data;

// Store token
localStorage.setItem('adminToken', token);

// Use token for authenticated requests
const usersResponse = await fetch('/api/v1/admin/users', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

Testing

Unit Tests

npm test -- rbac.unit.test.js

Integration Tests (requires database)

npm test -- admin.integration.test.js
npm test -- rbac.test.js

Default Admin Account

A default super admin account is created during database seeding:

• Username: admin
• Password: admin123
• Role: super_admin

⚠️ Important: Change the default password in production!

Configuration

Environment variables for admin authentication:

JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=7d

Future Enhancements

• Two-factor authentication (2FA)
• Password reset functionality
• Session management and revocation
• IP whitelisting for admin access
• More granular permissions system