Yaltopia-Ticket-Admin/dev-docs/AUTHENTICATION.md

Authentication Setup

Overview

The admin dashboard now requires authentication before accessing any admin routes and follows industry-standard security practices.

Security Status

✅ Frontend Security (Implemented)

• Protected routes with authentication check
• Role-based access control (ADMIN only)
• httpOnly cookie support (withCredentials: true)
• Automatic token refresh on expiration
• Centralized logout with backend call
• localStorage fallback for compatibility
• Secure error handling
• CSRF protection ready (via SameSite cookies)

⚠️ Backend Security (Required)

The backend MUST implement these critical security measures:

1. httpOnly Cookies: Store tokens in httpOnly cookies (not response body)
2. Password Hashing: Use bcrypt with salt rounds >= 12
3. Rate Limiting: Limit login attempts (5 per 15 minutes)
4. HTTPS: Enable HTTPS in production
5. Token Refresh: Implement refresh token endpoint
6. Input Validation: Sanitize and validate all inputs
7. CORS: Configure with specific origin and credentials
8. Security Headers: Use helmet.js for security headers
9. Audit Logging: Log all admin actions
10. SQL Injection Prevention: Use parameterized queries

See SECURITY_CHECKLIST.md for complete requirements.

How It Works

1. Protected Routes

All admin routes are wrapped with ProtectedRoute component that checks for a valid access token.

2. Login Flow

• User visits any admin route without authentication → Redirected to /login
• User enters credentials → API validates and returns user data
• Backend sets httpOnly cookies (recommended) OR returns token (fallback)
• Token/cookies stored, user redirected to originally requested page

3. Token Management

• Recommended: Tokens stored in httpOnly cookies (XSS protection)
• Fallback: Access token in localStorage, automatically added to requests
• Token automatically sent with all API requests
• On 401 response, automatically attempts token refresh
• If refresh fails, user is logged out and redirected to login

4. Logout

• Calls backend /auth/logout to clear httpOnly cookies
• Clears localStorage (access_token, user)
• Redirects to /login page

API Endpoints Required

POST /auth/login

Request:

{
  "email": "admin@example.com",
  "password": "password123"
}

Response (Cookie-based - Recommended):

HTTP/1.1 200 OK
Set-Cookie: access_token=<jwt>; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=900
Set-Cookie: refresh_token=<jwt>; HttpOnly; Secure; SameSite=Strict; Path=/auth/refresh; Max-Age=604800

{
  "user": {
    "id": "user-id",
    "email": "admin@example.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "ADMIN"
  }
}

Response (localStorage fallback):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user-id",
    "email": "admin@example.com",
    "role": "ADMIN"
  }
}

POST /auth/logout

Clears httpOnly cookies and invalidates tokens.

POST /auth/refresh

Refreshes expired access token using refresh token from cookie.

GET /auth/me (Optional)

Returns current authenticated user for session validation.

Files Modified/Created

Created:

• src/pages/login/index.tsx - Login page with show/hide password
• src/components/ProtectedRoute.tsx - Route protection wrapper
• dev-docs/AUTHENTICATION.md - This documentation
• dev-docs/API_STANDARDS.md - Detailed API standards
• dev-docs/SECURITY_CHECKLIST.md - Complete security checklist

Modified:

• src/App.tsx - Added login route and protected admin routes
• src/layouts/app-shell.tsx - User state management and logout
• src/lib/api-client.ts - Cookie support, token refresh, centralized auth

Testing

1. Start the application
2. Navigate to any admin route (e.g., /admin/dashboard)
3. Should be redirected to /login
4. Enter valid admin credentials
5. Should be redirected back to the dashboard
6. Check browser DevTools > Application > Cookies (if backend uses cookies)
7. Click logout to clear session

Security Comparison

Feature	Current (Frontend)	With Backend Implementation
XSS Protection	⚠️ Partial (localStorage)	✅ Full (httpOnly cookies)
CSRF Protection	✅ Ready	✅ Full (SameSite cookies)
Token Refresh	✅ Automatic	✅ Automatic
Rate Limiting	❌ None	✅ Required
Password Hashing	❌ Backend only	✅ Required
Audit Logging	❌ Backend only	✅ Required
HTTPS	⚠️ Production	✅ Required

Production Deployment Checklist

Frontend

• ✅ Build with production environment variables
• ✅ Enable HTTPS
• ✅ Configure CSP headers
• ✅ Set secure cookie flags

Backend

• ⚠️ Implement httpOnly cookies
• ⚠️ Enable HTTPS with valid SSL certificate
• ⚠️ Configure CORS with specific origin
• ⚠️ Add rate limiting
• ⚠️ Implement password hashing
• ⚠️ Add security headers (helmet.js)
• ⚠️ Set up audit logging
• ⚠️ Configure environment variables
• ⚠️ Enable database encryption
• ⚠️ Set up monitoring and alerting

Security Notes

Current Implementation

• Frontend follows industry standards
• Supports both cookie-based and localStorage authentication
• Automatic token refresh prevents session interruption
• Centralized error handling and logout

Backend Requirements

• Critical: Backend must implement security measures in SECURITY_CHECKLIST.md
• Recommended: Use httpOnly cookies instead of localStorage
• Required: Implement rate limiting, password hashing, HTTPS
• Important: Regular security audits and updates

Support

For detailed security requirements, see:

• dev-docs/SECURITY_CHECKLIST.md - Complete security checklist
• dev-docs/API_STANDARDS.md - API implementation guide
• dev-docs/DEPLOYMENT.md - Deployment instructions