Authentication System

FSS provides a robust, enterprise-grade authentication system built with security best practices.

Overview

The authentication system includes:

• ✅ JWT-based authentication with access/refresh tokens
• ✅ Multi-Factor Authentication (MFA/TOTP)
• ✅ Password hashing with bcrypt
• ✅ Session management with Redis
• ✅ Rate limiting and brute-force protection
• ✅ Audit logging for all auth events

Authentication Flow

Registration & Email Verification Flow

Token System

Access Token

interface AccessToken {
  sub: string;        // User ID
  email: string;
  role: string;
  iat: number;        // Issued at
  exp: number;        // Expiration
  type: 'access';
}

Properties:

• Short-lived (15 minutes default)
• Contains user identity and role
• Stored in memory or secure cookie

Refresh Token

interface RefreshToken {
  sub: string;        // User ID
  iat: number;        // Issued at
  exp: number;        // Expiration
  type: 'refresh';
  jti: string;        // Unique token ID
}

Properties:

• Long-lived (7-30 days)
• Used to obtain new access tokens
• Stored in HTTP-only cookie
• Can be revoked

Registration

POST /auth/register
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SecurePassword123!",
  "name": "John Doe"
}

Response:

{
  "message": "Registration successful. Please verify your email.",
  "userId": "uuid-here"
}

Login

POST /auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SecurePassword123!"
}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid-here",
    "email": "[email protected]",
    "name": "John Doe"
  },
  "requiresMfa": false
}

Token Refresh Flow

Multi-Factor Authentication (MFA)

MFA Login Flow

Setup MFA

POST /auth/setup-totp
Authorization: Bearer <access-token>

# Response
{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCode": "data:image/png;base64,...",
  "backupCodes": ["XXXX-XXXX", "XXXX-XXXX"]
}

Verify MFA

POST /auth/verify-mfa
Content-Type: application/json

{
  "tempToken": "temporary-token-from-login",
  "code": "123456"
}

Use Backup Code

POST /auth/verify-mfa
Content-Type: application/json

{
  "tempToken": "temporary-token-from-login",
  "backupCode": "XXXX-XXXX"
}

Token Refresh

POST /auth/refresh
Content-Type: application/json
Cookie: refreshToken=<refresh-token>

# Response
{
  "accessToken": "new-access-token",
  "refreshToken": "new-refresh-token"
}

Password Requirements

const passwordRequirements = {
  minLength: 8,
  requireUppercase: true,
  requireLowercase: true,
  requireNumber: true,
  requireSpecial: true,
  maxAge: 90, // days
};

Security Features

Rate Limiting

// Auth endpoints rate limiting
const authRateLimit = {
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 5, // 5 attempts per window
  message: "Too many login attempts. Please try again later.",
};

Account Lockout

const accountLockout = {
  maxAttempts: 5,
  lockoutDuration: 15 * 60 * 1000, // 15 minutes
  resetCounterAfter: 60 * 60 * 1000, // 1 hour
};

Password Hashing

// Using bcrypt with salt rounds
const bcrypt = require('bcrypt');
const saltRounds = 12;

async function hashPassword(password) {
  return bcrypt.hash(password, saltRounds);
}

async function verifyPassword(password, hash) {
  return bcrypt.compare(password, hash);
}

Session Management

Active Sessions

GET /user/sessions
Authorization: Bearer <access-token>

# Response
[
  {
    "id": "session-uuid",
    "device": "Chrome on Windows",
    "ip": "192.168.1.1",
    "createdAt": "2024-01-01T00:00:00Z",
    "lastActive": "2024-01-01T01:00:00Z",
    "current": true
  }
]

Revoke Session

DELETE /user/sessions/:id
Authorization: Bearer <access-token>

Revoke All Sessions

DELETE /user/sessions
Authorization: Bearer <access-token>

Protected Routes

// Middleware example
import { JwtAuthGuard } from './guards/jwt-auth.guard';

@Controller('dashboard')
@UseGuards(JwtAuthGuard)
export class DashboardController {
  @Get()
  getDashboard() {
    return { message: 'Protected data' };
  }
}

API Endpoints Summary

Endpoint	Method	Description
/auth/register	POST	Register new user
/auth/login	POST	User login
/auth/logout	POST	User logout
/auth/refresh	POST	Refresh tokens
/auth/verify-email	POST	Verify email
/auth/forgot-password	POST	Request password reset
/auth/reset-password	POST	Reset password
/auth/setup-totp	POST	Setup MFA
/auth/verify-mfa	POST	Verify MFA code
/user/profile	GET	Get user profile

Next Steps

• Security Best Practices - Security hardening
• Configuration - Auth configuration
• API Reference - Complete API docs