🔒 Authentication: JWT and Sessions

🎯 Introduction

Welcome to the exciting world of TypeScript authentication! 🎉 In this guide, we’ll explore JWT (JSON Web Tokens) and session-based authentication - the two most popular ways to keep your applications secure.

You’ll discover how authentication can transform your TypeScript backend development experience. Whether you’re building APIs 🌐, web applications 🖥️, or microservices 📚, understanding authentication is essential for writing secure, maintainable code.

By the end of this tutorial, you’ll feel confident implementing both JWT and session authentication in your own projects! Let’s dive in! 🏊‍♂️

📚 Understanding Authentication

🤔 What is Authentication?

Authentication is like being a bouncer at a nightclub 🎨. Think of it as checking IDs at the door - you need to verify someone is who they claim to be before letting them into your exclusive app!

In TypeScript terms, authentication is the process of verifying user credentials and managing their access to protected resources ✨. This means you can:

✨ Secure your API endpoints
🚀 Control user access levels
🛡️ Protect sensitive data

💡 JWT vs Sessions: The Great Debate

Here’s why developers have passionate discussions about these approaches:

JWT (JSON Web Tokens) 🎫:

Stateless 🔒: All info stored in the token
Scalable 💻: No server-side storage needed
Cross-Domain 📖: Works across different services
Portable 🔧: Easy to pass between services

Sessions 🗝️:

Server-Controlled 🎯: Full control over sessions
Secure by Default 🛡️: Harder to tamper with
Easy Revocation ⚡: Can instantly invalidate sessions
Simpler Logic 📝: Straightforward to implement

Real-world example: Imagine building a banking app 🏦. With JWT, it’s like giving customers a tamper-proof ID card. With sessions, it’s like keeping a guest list at the front desk.

🔧 Basic Syntax and Usage

📝 Setting Up Our Types

Let’s start with friendly type definitions:

// 👋 Hello, Authentication Types!
interface User {
  id: string;          // 🆔 Unique identifier
  email: string;       // 📧 User's email
  password: string;    // 🔑 Hashed password
  role: "admin" | "user"; // 👤 User role
  createdAt: Date;     // 📅 Registration date
  emoji: string;       // 🎭 User's favorite emoji!
}

// 🎫 JWT Payload structure
interface JWTPayload {
  userId: string;      // 👤 User identifier
  email: string;       // 📧 User email
  role: string;        // 🎯 User role
  iat: number;         // 🕐 Issued at
  exp: number;         // ⏰ Expires at
}

// 🗝️ Session data structure
interface SessionData {
  userId: string;      // 👤 User identifier
  email: string;       // 📧 User email
  role: string;        // 🎯 User role
  loginTime: Date;     // 🕐 When they logged in
  lastActivity: Date;  // ⚡ Last activity time
}

💡 Explanation: Notice how we define clear types for our authentication data! The emoji field adds personality to our users. 😊

🎯 Common Authentication Patterns

Here are patterns you’ll use daily:

// 🏗️ Pattern 1: Password hashing
import bcrypt from 'bcrypt';

const hashPassword = async (password: string): Promise<string> => {
  const saltRounds = 10; // 🧂 Salt rounds for security
  return await bcrypt.hash(password, saltRounds);
};

// 🔍 Pattern 2: Password verification
const verifyPassword = async (
  password: string, 
  hashedPassword: string
): Promise<boolean> => {
  return await bcrypt.compare(password, hashedPassword);
};

// 🎨 Pattern 3: Login response type
interface LoginResponse {
  success: boolean;    // ✅ Login success status  
  token?: string;      // 🎫 JWT token (if successful)
  user?: User;         // 👤 User data (without password!)
  message: string;     // 📝 Response message
  emoji: string;       // 🎉 Success/error emoji
}

💡 Practical Examples

🔒 Example 1: JWT Authentication System

Let’s build a complete JWT authentication system:

import jwt from 'jsonwebtoken';
import bcrypt from 'bcrypt';
import express, { Request, Response, NextFunction } from 'express';

// 🎯 JWT Authentication Service
class JWTAuthService {
  private readonly JWT_SECRET = process.env.JWT_SECRET || 'your-super-secret-key-🔐';
  private readonly JWT_EXPIRES_IN = '24h';
  
  // 🎫 Generate JWT token
  generateToken(user: User): string {
    const payload: JWTPayload = {
      userId: user.id,
      email: user.email,
      role: user.role,
      iat: Math.floor(Date.now() / 1000),
      exp: Math.floor(Date.now() / 1000) + (24 * 60 * 60) // 24 hours
    };
    
    return jwt.sign(payload, this.JWT_SECRET, { 
      expiresIn: this.JWT_EXPIRES_IN 
    });
  }
  
  // 🔍 Verify JWT token
  verifyToken(token: string): JWTPayload | null {
    try {
      return jwt.verify(token, this.JWT_SECRET) as JWTPayload;
    } catch (error) {
      console.log('🚫 Invalid token:', error);
      return null;
    }
  }
  
  // 🛡️ Middleware for protecting routes
  authenticate = (req: Request, res: Response, next: NextFunction): void => {
    const authHeader = req.headers.authorization;
    const token = authHeader?.split(' ')[1]; // Bearer TOKEN
    
    if (!token) {
      res.status(401).json({ 
        message: 'Access denied! No token provided 🚫',
        emoji: '🔒'
      });
      return;
    }
    
    const payload = this.verifyToken(token);
    if (!payload) {
      res.status(403).json({ 
        message: 'Invalid token! 🚫',
        emoji: '❌'
      });
      return;
    }
    
    // ✨ Add user info to request
    (req as any).user = payload;
    next();
  };
}

// 🏗️ User service for authentication
class UserService {
  private users: Map<string, User> = new Map();
  private authService = new JWTAuthService();
  
  // 📝 Register new user
  async register(email: string, password: string, emoji: string = '😊'): Promise<LoginResponse> {
    // 🔍 Check if user already exists
    const existingUser = Array.from(this.users.values())
      .find(user => user.email === email);
    
    if (existingUser) {
      return {
        success: false,
        message: 'User already exists! 🙋‍♂️',
        emoji: '⚠️'
      };
    }
    
    // 🔐 Hash password and create user
    const hashedPassword = await bcrypt.hash(password, 10);
    const newUser: User = {
      id: Date.now().toString(),
      email,
      password: hashedPassword,
      role: 'user',
      createdAt: new Date(),
      emoji
    };
    
    this.users.set(newUser.id, newUser);
    const token = this.authService.generateToken(newUser);
    
    return {
      success: true,
      token,
      user: { ...newUser, password: '' }, // 🚫 Never send password!
      message: 'Registration successful! Welcome aboard! 🎉',
      emoji: '🎊'
    };
  }
  
  // 🔑 Login user
  async login(email: string, password: string): Promise<LoginResponse> {
    // 🔍 Find user by email
    const user = Array.from(this.users.values())
      .find(user => user.email === email);
    
    if (!user) {
      return {
        success: false,
        message: 'User not found! 🔍',
        emoji: '😕'
      };
    }
    
    // 🔐 Verify password
    const isValidPassword = await bcrypt.compare(password, user.password);
    if (!isValidPassword) {
      return {
        success: false,
        message: 'Invalid password! 🚫',
        emoji: '🔐'
      };
    }
    
    // ✅ Generate token and return success
    const token = this.authService.generateToken(user);
    return {
      success: true,
      token,
      user: { ...user, password: '' }, // 🚫 Clean password
      message: `Welcome back, ${user.emoji}! 👋`,
      emoji: '🎉'
    };
  }
}

🎯 Try it yourself: Add a logout functionality that blacklists tokens!

🗝️ Example 2: Session-Based Authentication

Let’s implement session authentication:

import session from 'express-session';
import connectRedis from 'connect-redis';
import redis from 'redis';

// 🗃️ Session store configuration
const redisClient = redis.createClient({
  host: 'localhost',
  port: 6379
});

const RedisStore = connectRedis(session);

// 🎮 Session authentication service
class SessionAuthService {
  private users: Map<string, User> = new Map();
  
  // ⚙️ Session middleware configuration
  getSessionMiddleware() {
    return session({
      store: new RedisStore({
        client: redisClient,
        prefix: 'myapp:sess:' // 🏷️ Session prefix
      }),
      secret: process.env.SESSION_SECRET || 'your-session-secret-🗝️',
      resave: false,
      saveUninitialized: false,
      rolling: true, // 🔄 Reset expiry on activity
      cookie: {
        secure: process.env.NODE_ENV === 'production', // 🔒 HTTPS only in prod
        httpOnly: true, // 🛡️ Prevent XSS
        maxAge: 24 * 60 * 60 * 1000, // 📅 24 hours
        sameSite: 'strict' // 🛡️ CSRF protection
      }
    });
  }
  
  // 🔑 Login with session
  async loginWithSession(
    req: express.Request, 
    email: string, 
    password: string
  ): Promise<LoginResponse> {
    // 🔍 Find and verify user (similar to JWT example)
    const user = Array.from(this.users.values())
      .find(user => user.email === email);
    
    if (!user || !await bcrypt.compare(password, user.password)) {
      return {
        success: false,
        message: 'Invalid credentials! 🚫',
        emoji: '❌'
      };
    }
    
    // ✨ Create session data
    const sessionData: SessionData = {
      userId: user.id,
      email: user.email,
      role: user.role,
      loginTime: new Date(),
      lastActivity: new Date()
    };
    
    // 🗝️ Store in session
    (req.session as any).user = sessionData;
    
    return {
      success: true,
      user: { ...user, password: '' },
      message: `Welcome back! ${user.emoji} 🎉`,
      emoji: '🎊'
    };
  }
  
  // 🛡️ Session authentication middleware
  requireAuth = (req: express.Request, res: express.Response, next: express.NextFunction): void => {
    const sessionUser = (req.session as any).user as SessionData;
    
    if (!sessionUser) {
      res.status(401).json({
        message: 'Please log in first! 🔑',
        emoji: '🚪'
      });
      return;
    }
    
    // 🔄 Update last activity
    sessionUser.lastActivity = new Date();
    (req.session as any).user = sessionUser;
    
    // ✨ Add user to request
    (req as any).user = sessionUser;
    next();
  };
  
  // 👋 Logout (destroy session)
  logout(req: express.Request): Promise<boolean> {
    return new Promise((resolve) => {
      req.session.destroy((err) => {
        if (err) {
          console.log('🚫 Session destroy error:', err);
          resolve(false);
        } else {
          console.log('👋 Session destroyed successfully!');
          resolve(true);
        }
      });
    });
  }
}

🚀 Advanced Concepts

🧙‍♂️ Advanced Topic 1: Refresh Token System

When you’re ready to level up, implement refresh tokens:

// 🎯 Advanced token system with refresh
interface TokenPair {
  accessToken: string;    // 🎫 Short-lived (15 mins)
  refreshToken: string;   // 🔄 Long-lived (7 days)
  expiresIn: number;      // ⏰ Access token expiry
  tokenType: "Bearer";    // 🏷️ Token type
}

class AdvancedJWTService {
  private readonly ACCESS_TOKEN_EXPIRY = '15m';
  private readonly REFRESH_TOKEN_EXPIRY = '7d';
  private refreshTokens: Set<string> = new Set(); // 🗃️ Store valid refresh tokens
  
  // 🎫 Generate token pair
  generateTokenPair(user: User): TokenPair {
    const accessToken = jwt.sign(
      { userId: user.id, email: user.email, role: user.role },
      process.env.JWT_SECRET!,
      { expiresIn: this.ACCESS_TOKEN_EXPIRY }
    );
    
    const refreshToken = jwt.sign(
      { userId: user.id, type: 'refresh' },
      process.env.REFRESH_SECRET!,
      { expiresIn: this.REFRESH_TOKEN_EXPIRY }
    );
    
    // 🗃️ Store refresh token
    this.refreshTokens.add(refreshToken);
    
    return {
      accessToken,
      refreshToken,
      expiresIn: 15 * 60, // 15 minutes in seconds
      tokenType: "Bearer"
    };
  }
  
  // 🔄 Refresh access token
  refreshAccessToken(refreshToken: string): TokenPair | null {
    try {
      // 🔍 Verify refresh token
      const payload = jwt.verify(refreshToken, process.env.REFRESH_SECRET!) as any;
      
      if (!this.refreshTokens.has(refreshToken) || payload.type !== 'refresh') {
        return null;
      }
      
      // 🗑️ Remove old refresh token
      this.refreshTokens.delete(refreshToken);
      
      // 🎫 Generate new token pair
      // (You'd fetch user from database using payload.userId)
      const user = this.getUserById(payload.userId);
      return user ? this.generateTokenPair(user) : null;
      
    } catch (error) {
      console.log('🚫 Refresh token error:', error);
      return null;
    }
  }
  
  // 🗑️ Revoke refresh token
  revokeRefreshToken(refreshToken: string): boolean {
    return this.refreshTokens.delete(refreshToken);
  }
}

🏗️ Advanced Topic 2: Role-Based Access Control (RBAC)

For enterprise-level security:

// 🚀 Role-based access control system
type Permission = 'read' | 'write' | 'delete' | 'admin';
type Resource = 'users' | 'posts' | 'comments' | 'settings';

interface Role {
  name: string;
  permissions: Map<Resource, Permission[]>;
  emoji: string; // 🎭 Role emoji!
}

class RBACService {
  private roles: Map<string, Role> = new Map([
    ['admin', {
      name: 'admin',
      permissions: new Map([
        ['users', ['read', 'write', 'delete', 'admin']],
        ['posts', ['read', 'write', 'delete', 'admin']],
        ['comments', ['read', 'write', 'delete', 'admin']],
        ['settings', ['read', 'write', 'delete', 'admin']]
      ]),
      emoji: '👑'
    }],
    ['user', {
      name: 'user',
      permissions: new Map([
        ['posts', ['read', 'write']],
        ['comments', ['read', 'write']]
      ]),
      emoji: '👤'
    }]
  ]);
  
  // 🔍 Check if user has permission
  hasPermission(userRole: string, resource: Resource, permission: Permission): boolean {
    const role = this.roles.get(userRole);
    if (!role) return false;
    
    const resourcePermissions = role.permissions.get(resource);
    return resourcePermissions?.includes(permission) || false;
  }
  
  // 🛡️ Permission middleware factory
  requirePermission = (resource: Resource, permission: Permission) => {
    return (req: express.Request, res: express.Response, next: express.NextFunction) => {
      const user = (req as any).user;
      
      if (!user || !this.hasPermission(user.role, resource, permission)) {
        res.status(403).json({
          message: `Access denied! Need ${permission} permission for ${resource} 🚫`,
          emoji: '🛡️'
        });
        return;
      }
      
      next();
    };
  };
}

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Storing Passwords in Plain Text

// ❌ Wrong way - NEVER do this!
const badUser = {
  email: "[email protected]",
  password: "mysecretpassword123" // 💥 Huge security risk!
};

// ✅ Correct way - always hash passwords!
import bcrypt from 'bcrypt';

const goodUser = {
  email: "[email protected]",
  password: await bcrypt.hash("mysecretpassword123", 10) // 🛡️ Safe and secure!
};

🤯 Pitfall 2: Sending Passwords in Responses

// ❌ Dangerous - exposing password!
const loginResponse = {
  success: true,
  user: {
    id: "123",
    email: "[email protected]", 
    password: "hashedpassword" // 💥 Never send this!
  }
};

// ✅ Safe - clean user data!
const safeLoginResponse = {
  success: true,
  user: {
    id: "123",
    email: "[email protected]"
    // 🚫 Password intentionally omitted!
  },
  message: "Login successful! 🎉"
};

🔐 Pitfall 3: Weak JWT Secrets

// ❌ Terrible - easily guessable!
const weakSecret = "secret"; // 💥 Hackers will break this instantly!

// ✅ Strong - cryptographically secure!
const strongSecret = process.env.JWT_SECRET || crypto.randomBytes(64).toString('hex');
// 🛡️ Use environment variables for production!

🛠️ Best Practices

🎯 Use Strong Secrets: Generate cryptographically strong secrets for JWT and sessions
📝 Hash Passwords: Always use bcrypt or similar for password hashing
🛡️ Validate Input: Sanitize and validate all user inputs
🎨 Clean Responses: Never send passwords or sensitive data in API responses
✨ Use HTTPS: Always use HTTPS in production for secure token transmission
⏰ Short-lived Tokens: Keep access tokens short-lived (15-30 minutes)
🔄 Implement Refresh: Use refresh tokens for seamless user experience
🚫 Logout Properly: Always provide secure logout functionality

🧪 Hands-On Exercise

🎯 Challenge: Build a Complete Authentication System

Create a type-safe authentication system with both JWT and session support:

📋 Requirements:

✅ User registration and login endpoints
🏷️ Both JWT and session authentication
👤 Role-based access control
📅 Password reset functionality
🎨 Each user needs a favorite emoji!
🔄 Refresh token implementation

🚀 Bonus Points:

Add password strength validation
Implement account lockout after failed attempts
Create audit logging for security events
Add two-factor authentication (2FA)

💡 Solution

🔍 Click to see solution

// 🎯 Complete authentication system!
import express from 'express';
import bcrypt from 'bcrypt';
import jwt from 'jsonwebtoken';
import rateLimit from 'express-rate-limit';

interface CompleteUser {
  id: string;
  email: string;
  password: string;
  role: 'admin' | 'user';
  emoji: string;
  isLocked: boolean;
  failedLoginAttempts: number;
  lastLoginAttempt?: Date;
  createdAt: Date;
  lastLogin?: Date;
}

class CompleteAuthSystem {
  private users: Map<string, CompleteUser> = new Map();
  private refreshTokens: Set<string> = new Set();
  private readonly MAX_FAILED_ATTEMPTS = 5;
  private readonly LOCKOUT_DURATION = 15 * 60 * 1000; // 15 minutes

  // 🛡️ Rate limiting middleware
  private loginLimiter = rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 5, // Max 5 attempts per window
    message: {
      error: 'Too many login attempts! Try again later 🚫',
      emoji: '⏰'
    }
  });

  // 📝 Register with validation
  async register(
    email: string, 
    password: string, 
    emoji: string = '😊'
  ): Promise<{ success: boolean; message: string; user?: any; token?: string }> {
    
    // 🔍 Email validation
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    if (!emailRegex.test(email)) {
      return {
        success: false,
        message: 'Invalid email format! 📧'
      };
    }

    // 🔐 Password strength validation
    if (password.length < 8) {
      return {
        success: false,
        message: 'Password must be at least 8 characters long! 🔒'
      };
    }

    // 🔍 Check if user exists
    const existingUser = Array.from(this.users.values())
      .find(user => user.email === email);
    
    if (existingUser) {
      return {
        success: false,
        message: 'Email already registered! 🙋‍♂️'
      };
    }

    // 🏗️ Create user
    const hashedPassword = await bcrypt.hash(password, 12);
    const newUser: CompleteUser = {
      id: Date.now().toString(),
      email,
      password: hashedPassword,
      role: 'user',
      emoji,
      isLocked: false,
      failedLoginAttempts: 0,
      createdAt: new Date()
    };

    this.users.set(newUser.id, newUser);

    // 🎫 Generate tokens
    const tokens = this.generateTokenPair(newUser);

    return {
      success: true,
      message: `Welcome aboard! ${emoji} 🎉`,
      user: this.sanitizeUser(newUser),
      token: tokens.accessToken
    };
  }

  // 🔑 Enhanced login with security features
  async login(
    email: string, 
    password: string
  ): Promise<{ success: boolean; message: string; user?: any; tokens?: any }> {
    
    const user = Array.from(this.users.values())
      .find(u => u.email === email);

    if (!user) {
      return {
        success: false,
        message: 'Invalid credentials! 🚫'
      };
    }

    // 🔒 Check if account is locked
    if (this.isAccountLocked(user)) {
      return {
        success: false,
        message: 'Account temporarily locked! Try again later 🔒'
      };
    }

    // 🔐 Verify password
    const isValidPassword = await bcrypt.compare(password, user.password);
    
    if (!isValidPassword) {
      // 📈 Increment failed attempts
      user.failedLoginAttempts++;
      user.lastLoginAttempt = new Date();
      
      if (user.failedLoginAttempts >= this.MAX_FAILED_ATTEMPTS) {
        user.isLocked = true;
      }

      return {
        success: false,
        message: `Invalid password! ${this.MAX_FAILED_ATTEMPTS - user.failedLoginAttempts} attempts remaining 🚫`
      };
    }

    // ✅ Successful login - reset counters
    user.failedLoginAttempts = 0;
    user.isLocked = false;
    user.lastLogin = new Date();

    const tokens = this.generateTokenPair(user);

    return {
      success: true,
      message: `Welcome back! ${user.emoji} 👋`,
      user: this.sanitizeUser(user),
      tokens
    };
  }

  // 🔄 Token pair generation
  private generateTokenPair(user: CompleteUser) {
    const accessToken = jwt.sign(
      { 
        userId: user.id, 
        email: user.email, 
        role: user.role,
        emoji: user.emoji 
      },
      process.env.JWT_SECRET || 'fallback-secret',
      { expiresIn: '15m' }
    );

    const refreshToken = jwt.sign(
      { userId: user.id, type: 'refresh' },
      process.env.REFRESH_SECRET || 'refresh-secret',
      { expiresIn: '7d' }
    );

    this.refreshTokens.add(refreshToken);

    return {
      accessToken,
      refreshToken,
      expiresIn: 15 * 60, // 15 minutes
      tokenType: 'Bearer'
    };
  }

  // 🔒 Check if account is locked
  private isAccountLocked(user: CompleteUser): boolean {
    if (!user.isLocked || !user.lastLoginAttempt) return false;
    
    const timeSinceLock = Date.now() - user.lastLoginAttempt.getTime();
    if (timeSinceLock > this.LOCKOUT_DURATION) {
      // 🔓 Auto-unlock after lockout duration
      user.isLocked = false;
      user.failedLoginAttempts = 0;
      return false;
    }
    
    return true;
  }

  // 🧹 Remove sensitive data
  private sanitizeUser(user: CompleteUser) {
    const { password, failedLoginAttempts, isLocked, ...safeUser } = user;
    return safeUser;
  }

  // 🛡️ Authentication middleware
  authenticate = (req: express.Request, res: express.Response, next: express.NextFunction) => {
    const authHeader = req.headers.authorization;
    const token = authHeader?.split(' ')[1];

    if (!token) {
      res.status(401).json({
        message: 'Access token required! 🎫',
        emoji: '🚪'
      });
      return;
    }

    try {
      const payload = jwt.verify(token, process.env.JWT_SECRET || 'fallback-secret') as any;
      (req as any).user = payload;
      next();
    } catch (error) {
      res.status(403).json({
        message: 'Invalid or expired token! 🚫',
        emoji: '⏰'
      });
    }
  };
}

// 🎮 Usage example
const authSystem = new CompleteAuthSystem();
const app = express();

app.use(express.json());

// 📝 Registration endpoint
app.post('/register', async (req, res) => {
  const { email, password, emoji } = req.body;
  const result = await authSystem.register(email, password, emoji);
  
  res.status(result.success ? 201 : 400).json(result);
});

// 🔑 Login endpoint
app.post('/login', async (req, res) => {
  const { email, password } = req.body;
  const result = await authSystem.login(email, password);
  
  res.status(result.success ? 200 : 401).json(result);
});

// 🛡️ Protected route example
app.get('/profile', authSystem.authenticate, (req, res) => {
  const user = (req as any).user;
  res.json({
    message: `Hello ${user.emoji}! Here's your profile 👋`,
    user: user
  });
});

console.log('🚀 Authentication server ready on port 3000!');

🎓 Key Takeaways

You’ve learned so much! Here’s what you can now do:

✅ Implement JWT authentication with confidence 💪
✅ Create session-based auth that scales 🚀
✅ Avoid security pitfalls that trip up beginners 🛡️
✅ Apply RBAC patterns for enterprise apps 🎯
✅ Debug authentication issues like a pro 🐛
✅ Build secure, type-safe backends with TypeScript! ✨

Remember: Security is not a feature, it’s a foundation! Build it right from the start. 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered authentication fundamentals!

Here’s what to do next:

💻 Practice with the exercises above
🏗️ Build a complete app with authentication
📚 Move on to our next tutorial: Authorization & Middleware
🌟 Share your secure apps with the world!
🔍 Explore OAuth2 and social login integrations

Remember: Every security expert was once a beginner. Keep coding, keep learning, and most importantly, keep your users safe! 🚀

Happy coding! 🎉🔒✨

Prerequisites

What you'll learn