Part 4: Authentication and Authorization

The $50,000 Security Lesson

In my second year as a developer, I built an admin dashboard API. I implemented authentication—users had to log in with email/password. I felt secure.

Until our security audit revealed: any authenticated user could access admin endpoints. A regular customer could delete products, modify orders, view all user data. We had authentication (who you are) but no authorization (what you can do).

We were lucky—caught before production. That audit taught me: authentication gets you in the door, authorization decides which rooms you can enter.

This article covers both, using patterns from my production microservices.

Authentication vs Authorization

Authentication: Verifying identity

• "Who are you?"

• Login with email/password

• Returns access token

Authorization: Verifying permissions

• "What can you do?"

• Check user role/permissions

• Allow or deny access

Real example:

// Authentication: Verify JWT token
// Authorization: Check if user is admin

GET /api/admin/users
Authorization: Bearer eyJhbGc...  ← Authentication (valid user?)
User role: admin                  ← Authorization (admin access?)

JWT (JSON Web Tokens)

JWT is the standard for stateless authentication in REST APIs.

JWT Structure

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJyb2xlIjoiYWRtaW4ifQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

[Header].[Payload].[Signature]

Header: Algorithm and token type

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload: User data (claims)

{
  "userId": "123",
  "email": "[email protected]",
  "role": "admin",
  "iat": 1516239022,
  "exp": 1516242622
}

Signature: Ensures integrity

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

JWT Service Implementation

// src/services/jwt-service.ts
import jwt from 'jsonwebtoken';
import { config } from '../config/environment';

export interface JwtPayload {
  userId: string;
  email: string;
  role: string;
}

export class JwtService {
  private readonly secret: string;
  private readonly expiresIn: string;

  constructor() {
    this.secret = config.jwt.secret;
    this.expiresIn = config.jwt.expiresIn;
  }

  sign(payload: JwtPayload): string {
    return jwt.sign(payload, this.secret, {
      expiresIn: this.expiresIn,
    });
  }

  verify(token: string): JwtPayload {
    try {
      return jwt.verify(token, this.secret) as JwtPayload;
    } catch (error) {
      if (error instanceof jwt.TokenExpiredError) {
        throw new Error('Token expired');
      }
      if (error instanceof jwt.JsonWebTokenError) {
        throw new Error('Invalid token');
      }
      throw new Error('Token verification failed');
    }
  }

  decode(token: string): JwtPayload | null {
    try {
      return jwt.decode(token) as JwtPayload;
    } catch (error) {
      return null;
    }
  }
}

Authentication Service

// src/services/auth-service.ts
import bcrypt from 'bcrypt';
import { UserRepository } from '../repositories/user-repository';
import { JwtService, JwtPayload } from './jwt-service';

export interface LoginDto {
  email: string;
  password: string;
}

export interface AuthResponse {
  user: {
    id: string;
    email: string;
    name: string;
    role: string;
  };
  token: string;
  expiresIn: string;
}

export class AuthService {
  constructor(
    private readonly userRepository: UserRepository,
    private readonly jwtService: JwtService
  ) {}

  async login(credentials: LoginDto): Promise<AuthResponse> {
    // Find user by email
    const user = await this.userRepository.findByEmailWithPassword(
      credentials.email
    );

    if (!user) {
      throw new Error('Invalid email or password');
    }

    // Verify password
    const validPassword = await bcrypt.compare(
      credentials.password,
      user.password
    );

    if (!validPassword) {
      throw new Error('Invalid email or password');
    }

    // Generate JWT token
    const payload: JwtPayload = {
      userId: user.id,
      email: user.email,
      role: user.role,
    };

    const token = this.jwtService.sign(payload);

    return {
      user: {
        id: user.id,
        email: user.email,
        name: user.name,
        role: user.role,
      },
      token,
      expiresIn: '24h',
    };
  }

  async register(userData: {
    email: string;
    password: string;
    name: string;
  }): Promise<AuthResponse> {
    // Check if user exists
    const existing = await this.userRepository.findByEmail(userData.email);
    if (existing) {
      throw new Error('Email already registered');
    }

    // Hash password
    const hashedPassword = await bcrypt.hash(userData.password, 10);

    // Create user
    const user = await this.userRepository.create({
      ...userData,
      password: hashedPassword,
      role: 'user', // Default role
    });

    // Generate token
    const payload: JwtPayload = {
      userId: user.id,
      email: user.email,
      role: user.role,
    };

    const token = this.jwtService.sign(payload);

    return {
      user: {
        id: user.id,
        email: user.email,
        name: user.name,
        role: user.role,
      },
      token,
      expiresIn: '24h',
    };
  }

  async validateToken(token: string): Promise<JwtPayload> {
    return this.jwtService.verify(token);
  }
}

Authentication Controller

// src/controllers/auth-controller.ts
import { Request, Response } from 'express';
import { AuthService } from '../services/auth-service';
import { ResponseFormatter } from '../utils/response-formatter';

export class AuthController {
  constructor(private readonly authService: AuthService) {}

  async login(req: Request, res: Response): Promise<void> {
    try {
      const { email, password } = req.body;

      if (!email || !password) {
        res.status(400).json(
          ResponseFormatter.error('Email and password are required')
        );
        return;
      }

      const authResponse = await this.authService.login({ email, password });

      res.json(
        ResponseFormatter.success(authResponse, 'Login successful')
      );
    } catch (error) {
      if (error instanceof Error) {
        res.status(401).json(
          ResponseFormatter.error(error.message)
        );
      } else {
        res.status(500).json(
          ResponseFormatter.error('Login failed')
        );
      }
    }
  }

  async register(req: Request, res: Response): Promise<void> {
    try {
      const { email, password, name } = req.body;

      if (!email || !password || !name) {
        res.status(400).json(
          ResponseFormatter.error('Email, password, and name are required')
        );
        return;
      }

      const authResponse = await this.authService.register({
        email,
        password,
        name,
      });

      res.status(201).json(
        ResponseFormatter.success(authResponse, 'Registration successful')
      );
    } catch (error) {
      if (error instanceof Error) {
        res.status(400).json(
          ResponseFormatter.error(error.message)
        );
      } else {
        res.status(500).json(
          ResponseFormatter.error('Registration failed')
        );
      }
    }
  }

  async validateToken(req: Request, res: Response): Promise<void> {
    try {
      const authHeader = req.headers.authorization;

      if (!authHeader) {
        res.status(401).json(
          ResponseFormatter.error('Authorization header missing')
        );
        return;
      }

      const [scheme, token] = authHeader.split(' ');

      if (scheme !== 'Bearer' || !token) {
        res.status(401).json(
          ResponseFormatter.error('Invalid authorization format')
        );
        return;
      }

      const payload = await this.authService.validateToken(token);

      res.json(
        ResponseFormatter.success(payload, 'Token is valid')
      );
    } catch (error) {
      if (error instanceof Error) {
        res.status(401).json(
          ResponseFormatter.error(error.message)
        );
      } else {
        res.status(500).json(
          ResponseFormatter.error('Token validation failed')
        );
      }
    }
  }
}

Authentication Middleware

// src/middleware/auth-middleware.ts
import { Request, Response, NextFunction } from 'express';
import { JwtService } from '../services/jwt-service';
import { ResponseFormatter } from '../utils/response-formatter';

// Extend Express Request type
declare global {
  namespace Express {
    interface Request {
      user?: {
        userId: string;
        email: string;
        role: string;
      };
    }
  }
}

export class AuthMiddleware {
  private readonly jwtService: JwtService;

  constructor() {
    this.jwtService = new JwtService();
  }

  authenticate = async (
    req: Request,
    res: Response,
    next: NextFunction
  ): Promise<void> => {
    try {
      // Extract token from Authorization header
      const authHeader = req.headers.authorization;

      if (!authHeader) {
        res.status(401).json(
          ResponseFormatter.error('Authorization header missing')
        );
        return;
      }

      // Expected format: "Bearer <token>"
      const [scheme, token] = authHeader.split(' ');

      if (scheme !== 'Bearer') {
        res.status(401).json(
          ResponseFormatter.error('Invalid authorization scheme. Use Bearer')
        );
        return;
      }

      if (!token) {
        res.status(401).json(
          ResponseFormatter.error('Token missing')
        );
        return;
      }

      // Verify token
      const payload = this.jwtService.verify(token);

      // Attach user info to request
      req.user = {
        userId: payload.userId,
        email: payload.email,
        role: payload.role,
      };

      next();
    } catch (error) {
      if (error instanceof Error) {
        res.status(401).json(
          ResponseFormatter.error(error.message)
        );
      } else {
        res.status(401).json(
          ResponseFormatter.error('Authentication failed')
        );
      }
    }
  };

  // Optional authentication - doesn't fail if no token
  optionalAuth = async (
    req: Request,
    res: Response,
    next: NextFunction
  ): Promise<void> => {
    try {
      const authHeader = req.headers.authorization;

      if (!authHeader) {
        return next(); // No token, continue without user
      }

      const [scheme, token] = authHeader.split(' ');

      if (scheme === 'Bearer' && token) {
        const payload = this.jwtService.verify(token);
        req.user = {
          userId: payload.userId,
          email: payload.email,
          role: payload.role,
        };
      }

      next();
    } catch (error) {
      // Invalid token, but don't fail - continue without user
      next();
    }
  };
}

Authorization Middleware

// src/middleware/authorization-middleware.ts
import { Request, Response, NextFunction } from 'express';
import { ResponseFormatter } from '../utils/response-formatter';

export class AuthorizationMiddleware {
  // Check if user has required role
  static requireRole(...allowedRoles: string[]) {
    return (req: Request, res: Response, next: NextFunction): void => {
      if (!req.user) {
        res.status(401).json(
          ResponseFormatter.error('Authentication required')
        );
        return;
      }

      if (!allowedRoles.includes(req.user.role)) {
        res.status(403).json(
          ResponseFormatter.error('Insufficient permissions')
        );
        return;
      }

      next();
    };
  }

  // Check if user is accessing their own resource
  static requireOwnership(userIdParam: string = 'userId') {
    return (req: Request, res: Response, next: NextFunction): void => {
      if (!req.user) {
        res.status(401).json(
          ResponseFormatter.error('Authentication required')
        );
        return;
      }

      const resourceUserId = req.params[userIdParam];

      // Admin can access any resource
      if (req.user.role === 'admin') {
        return next();
      }

      // User must own the resource
      if (req.user.userId !== resourceUserId) {
        res.status(403).json(
          ResponseFormatter.error('Access denied. You can only access your own resources')
        );
        return;
      }

      next();
    };
  }

  // Permission-based authorization
  static requirePermission(...permissions: string[]) {
    return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
      if (!req.user) {
        res.status(401).json(
          ResponseFormatter.error('Authentication required')
        );
        return;
      }

      // In production, fetch user permissions from database
      // For now, role-based mapping
      const rolePermissions: Record<string, string[]> = {
        admin: ['read', 'write', 'delete', 'admin'],
        manager: ['read', 'write'],
        user: ['read'],
      };

      const userPermissions = rolePermissions[req.user.role] || [];

      const hasPermission = permissions.some(permission =>
        userPermissions.includes(permission)
      );

      if (!hasPermission) {
        res.status(403).json(
          ResponseFormatter.error('Insufficient permissions')
        );
        return;
      }

      next();
    };
  }
}

Protected Routes

// src/routes/user-routes.ts
import { Router } from 'express';
import { UserController } from '../controllers/user-controller';
import { AuthMiddleware } from '../middleware/auth-middleware';
import { AuthorizationMiddleware } from '../middleware/authorization-middleware';

export class UserRoutes {
  static setup(controller: UserController, authMiddleware: AuthMiddleware): Router {
    const router = Router();

    // Public route - no authentication
    router.get('/public', controller.getPublicUsers.bind(controller));

    // Protected routes - authentication required
    router.use(authMiddleware.authenticate);

    // Any authenticated user can access
    router.get('/me', controller.getCurrentUser.bind(controller));

    // Admin only
    router.get(
      '/',
      AuthorizationMiddleware.requireRole('admin'),
      controller.getAllUsers.bind(controller)
    );

    // User can access their own data, admin can access any
    router.get(
      '/:userId',
      AuthorizationMiddleware.requireOwnership('userId'),
      controller.getUserById.bind(controller)
    );

    // Manager or admin can create users
    router.post(
      '/',
      AuthorizationMiddleware.requireRole('admin', 'manager'),
      controller.createUser.bind(controller)
    );

    // User can update their own data, admin can update any
    router.patch(
      '/:userId',
      AuthorizationMiddleware.requireOwnership('userId'),
      controller.updateUser.bind(controller)
    );

    // Admin only
    router.delete(
      '/:userId',
      AuthorizationMiddleware.requireRole('admin'),
      controller.deleteUser.bind(controller)
    );

    return router;
  }
}

// src/routes/product-routes.ts
export class ProductRoutes {
  static setup(
    controller: ProductController,
    authMiddleware: AuthMiddleware
  ): Router {
    const router = Router();

    // Public - anyone can view products
    router.get('/', controller.getAllProducts.bind(controller));
    router.get('/:id', controller.getProductById.bind(controller));

    // Protected - must be authenticated
    router.use(authMiddleware.authenticate);

    // Write permission required
    router.post(
      '/',
      AuthorizationMiddleware.requirePermission('write'),
      controller.createProduct.bind(controller)
    );

    router.patch(
      '/:id',
      AuthorizationMiddleware.requirePermission('write'),
      controller.updateProduct.bind(controller)
    );

    // Admin permission required
    router.delete(
      '/:id',
      AuthorizationMiddleware.requirePermission('admin'),
      controller.deleteProduct.bind(controller)
    );

    return router;
  }
}

Refresh Tokens

For production, implement refresh tokens to avoid storing long-lived JWTs.

// src/services/refresh-token-service.ts
import { randomBytes } from 'crypto';
import { Pool } from 'pg';

export interface RefreshToken {
  id: string;
  userId: string;
  token: string;
  expiresAt: Date;
  createdAt: Date;
}

export class RefreshTokenService {
  constructor(private readonly db: Pool) {}

  async create(userId: string, expiresInDays: number = 30): Promise<string> {
    const token = randomBytes(32).toString('hex');
    const expiresAt = new Date();
    expiresAt.setDate(expiresAt.getDate() + expiresInDays);

    await this.db.query(
      `INSERT INTO refresh_tokens (id, user_id, token, expires_at, created_at)
       VALUES ($1, $2, $3, $4, NOW())`,
      [this.generateId(), userId, token, expiresAt]
    );

    return token;
  }

  async verify(token: string): Promise<string | null> {
    const result = await this.db.query(
      `SELECT user_id, expires_at FROM refresh_tokens
       WHERE token = $1 AND expires_at > NOW()`,
      [token]
    );

    if (result.rows.length === 0) {
      return null;
    }

    return result.rows[0].user_id;
  }

  async revoke(token: string): Promise<void> {
    await this.db.query('DELETE FROM refresh_tokens WHERE token = $1', [token]);
  }

  async revokeAllForUser(userId: string): Promise<void> {
    await this.db.query('DELETE FROM refresh_tokens WHERE user_id = $1', [userId]);
  }

  private generateId(): string {
    return `rt_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
  }
}

// Updated AuthService with refresh tokens
export class AuthService {
  async login(credentials: LoginDto): Promise<AuthResponse> {
    // ... existing login logic ...

    // Generate access token (short-lived)
    const accessToken = this.jwtService.sign(payload, '15m');

    // Generate refresh token (long-lived)
    const refreshToken = await this.refreshTokenService.create(user.id, 30);

    return {
      user: { ... },
      accessToken,
      refreshToken,
      expiresIn: '15m',
    };
  }

  async refreshAccessToken(refreshToken: string): Promise<{ accessToken: string }> {
    const userId = await this.refreshTokenService.verify(refreshToken);

    if (!userId) {
      throw new Error('Invalid or expired refresh token');
    }

    const user = await this.userRepository.findById(userId);

    if (!user) {
      throw new Error('User not found');
    }

    const payload: JwtPayload = {
      userId: user.id,
      email: user.email,
      role: user.role,
    };

    const accessToken = this.jwtService.sign(payload, '15m');

    return { accessToken };
  }

  async logout(refreshToken: string): Promise<void> {
    await this.refreshTokenService.revoke(refreshToken);
  }
}

API Usage Examples

# Register
curl -X POST http://localhost:4000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123",
    "name": "John Doe"
  }'

# Response:
{
  "success": true,
  "data": {
    "user": {
      "id": "user_123",
      "email": "[email protected]",
      "name": "John Doe",
      "role": "user"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": "24h"
  }
}

# Login
curl -X POST http://localhost:4000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123"
  }'

# Access protected endpoint
curl http://localhost:4000/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Admin endpoint (requires admin role)
curl http://localhost:4000/api/v1/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Key Takeaways

1. Authentication verifies identity, Authorization verifies permissions

2. JWT provides stateless authentication

3. Never store passwords in plain text - always hash with bcrypt

4. Short-lived access tokens (15min) with long-lived refresh tokens (30 days)

5. Role-based (RBAC) and permission-based authorization

6. Ownership checks ensure users access only their resources

7. 401 Unauthorized for authentication failures

8. 403 Forbidden for authorization failures

9. Revoke refresh tokens on logout

10. Validate tokens on every protected endpoint

Next in series: Error Handling and Validation—building robust APIs that handle failures gracefully.

---

Security isn't optional. Implement authentication and authorization from day one.