Implementing & Rotating Refresh Tokens

Introduction to Refresh Tokens

Welcome to the first lesson of our course on securing your REST API application with TypeScript . In this lesson, we will focus on implementing and rotating refresh tokens .

What are Refresh Tokens?

Refresh tokens are long-lived credentials that allow clients to obtain new access tokens without requiring the user to re-authenticate. While access tokens are short-lived (typically minutes) and grant access to protected resources, refresh tokens have a longer lifespan (days or weeks) and are used solely to obtain new access tokens when the current ones expire.

Why Use Refresh Tokens?

The main purposes of refresh tokens include: Improving User Experience : Users don't need to login repeatedly Enhancing Security : Access tokens can be short-lived, limiting the damage if compromised Maintaining Sessions : Applications can maintain user sessions across restarts or network changes

Pros and Cons of Refresh Tokens

Advantages: Reduces the frequency of user authentication Allows for shorter-lived access tokens, improving security Enables token revocation without affecting the authentication flow Supports proper logout functionality by invalidating tokens Disadvantages: Increases complexity of the authentication system Requires server-side storage and management Can be vulnerable to theft if not properly secured Adds additional API calls to the authentication flow

Understanding Refresh Token Rotation

Refresh token rotation is a critical security practice where each refresh token can only be used once. Let's clarify how it works: What is token rotation? When a client uses a refresh token to get a new access token, they also receive a new refresh token simultaneously, and the old refresh token becomes invalid. The rotation flow: Client sends the current refresh token to get a new access token Server immediately invalidates the sent refresh token Server generates and returns both a new access token AND a new refresh token Client must use the new refresh token for future refreshes Security benefits: Creates a rotating chain of tokens that are each used exactly once If a refresh token is stolen and used by an attacker, the legitimate user's next refresh attempt will fail This failure serves as an early warning system for token theft Limits the "window of opportunity" for attackers to use a stolen token This approach differs from simple refresh mechanisms where the same refresh token can be used multiple times, which creates a longer vulnerability window if the token is compromised. By the end of this lesson, you will be able to implement refresh tokens, create authentication tokens, and handle token rotation securely.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Creating Auth Tokens

Next, we implement the function that generates both access and refresh tokens:

TypeScript

import jwt from 'jsonwebtoken';
import { v4 as uuidv4 } from 'uuid';
import { RefreshToken } from '../models/RefreshToken';
import { JWT_SECRET_KEY } from '../../config';

const ACCESS_TOKEN_EXPIRES_IN = '15m';       // e.g. 15 minutes
const REFRESH_TOKEN_LIFETIME_DAYS = 7;       // e.g. 7 days

function generateAccessToken(userId: number) {
  return jwt.sign({ 
    userId,
    jti: uuidv4() // Add a unique JWT ID for each token
  }, JWT_SECRET_KEY, {
    expiresIn: ACCESS_TOKEN_EXPIRES_IN,
  });
}

async function createAuthTokens(userId: number) {
  const accessToken = generateAccessToken(userId);
  const refreshToken = uuidv4();
  
  const expiresAt = new Date();
  expiresAt.setDate(expiresAt.getDate() + REFRESH_TOKEN_LIFETIME_DAYS);
  
  await RefreshToken.destroy({ where: { userId } });
  
  await RefreshToken.create({
    token: refreshToken,
    userId,
    expiresAt,
  });
  
  return { accessToken, refreshToken };
}

import jwt from 'jsonwebtoken';
import { v4 as uuidv4 } from 'uuid';
import { RefreshToken } from '../models/RefreshToken';
import { JWT_SECRET_KEY } from '../../config';

const ACCESS_TOKEN_EXPIRES_IN = '15m';       // e.g. 15 minutes
const REFRESH_TOKEN_LIFETIME_DAYS = 7;       // e.g. 7 days

function generateAccessToken(userId: number) {
  return jwt.sign({ 
    userId,
    jti: uuidv4() // Add a unique JWT ID for each token
  }, JWT_SECRET_KEY, {
    expiresIn: ACCESS_TOKEN_EXPIRES_IN,
  });
}

async function createAuthTokens(userId: number) {
  const accessToken = generateAccessToken(userId);
  const refreshToken = uuidv4();
  
  const expiresAt = new Date();
  expiresAt.setDate(expiresAt.getDate() + REFRESH_TOKEN_LIFETIME_DAYS);
  
  await RefreshToken.destroy({ where: { userId } });
  
  await RefreshToken.create({
    token: refreshToken,
    userId,
    expiresAt,
  });
  
  return { accessToken, refreshToken };
}

Code Logic:

The access token is a JWT with a short lifespan (15 minutes) that contains the user ID and a unique token ID
The refresh token is a simple UUID with a longer lifespan (7 days)
Before creating a new refresh token, we delete any existing tokens for that user, implementing a "one token per user" policy
Both tokens are returned to the client, but only the refresh token is stored in the database

This approach ensures that a user can only have one valid refresh token at a time, which simplifies token management and enhances security by making it easier to detect token abuse.

Implementing the /refresh Endpoint

The /refresh endpoint is where token rotation happens:

TypeScript

router.post('/refresh', async (req, res) => {
  try {
    const { refreshToken: incomingToken } = req.body;
    if (!incomingToken) {
      return res.status(400).json({ error: 'Missing refresh token' });
    }

    const stored = await RefreshToken.findByPk(incomingToken);
    if (!stored) {
      return res.status(401).json({ error: 'Invalid refresh token' });
    }

    if (stored.expiresAt < new Date()) {
      await stored.destroy();
      return res.status(401).json({ error: 'Refresh token expired' });
    }

    // Begin token rotation process
    const accessToken = generateAccessToken(stored.userId);
    const refreshToken = uuidv4();  // Generate new refresh token

    await stored.destroy();  // Invalidate the old token immediately

    const expiresAt = new Date();
    expiresAt.setDate(expiresAt.getDate() + REFRESH_TOKEN_LIFETIME_DAYS);
    await RefreshToken.create({
      token: refreshToken,
      userId: stored.userId,
      expiresAt,
    });   // Store the new refresh token

    res.json({ accessToken, refreshToken });
  } catch (error) {
    console.error('Refresh error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

router.post('/refresh', async (req, res) => {
  try {
    const { refreshToken: incomingToken } = req.body;
    if (!incomingToken) {
      return res.status(400).json({ error: 'Missing refresh token' });
    }

    const stored = await RefreshToken.findByPk(incomingToken);
    if (!stored) {
      return res.status(401).json({ error: 'Invalid refresh token' });
    }

    if (stored.expiresAt < new Date()) {
      await stored.destroy();
      return res.status(401).json({ error: 'Refresh token expired' });
    }

    // Begin token rotation process
    const accessToken = generateAccessToken(stored.userId);
    const refreshToken = uuidv4();  // Generate new refresh token

    await stored.destroy();  // Invalidate the old token immediately

    const expiresAt = new Date();
    expiresAt.setDate(expiresAt.getDate() + REFRESH_TOKEN_LIFETIME_DAYS);
    await RefreshToken.create({
      token: refreshToken,
      userId: stored.userId,
      expiresAt,
    });   // Store the new refresh token

    res.json({ accessToken, refreshToken });
  } catch (error) {
    console.error('Refresh error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

Code Logic: This is the core of our token rotation implementation:

Verify the incoming refresh token exists in our database
Check if the token has expired
Immediately delete the used token from the database
Generate a new access token and refresh token pair
Store the new refresh token in the database
Return both tokens to the client

This rotation mechanism is crucial for security because:

It ensures each refresh token can only be used once
If a token is stolen and used by an attacker, the legitimate user's token becomes invalid
This invalidation alerts the user to potential token theft when their app suddenly requires re-authentication

Key Error Handling Aspects:

We immediately fail with appropriate error codes if tokens are missing or invalid
Expired tokens are automatically removed from the database
Database errors are caught and don't expose internal details to clients
Each error response includes a specific message to help debug client-side issues