JWT Best Practices for Authentication

JWTs enable stateless authentication. Here's how to implement them securely.

JWT Structure#

// JWT has three parts: header.payload.signature

// Header
{
  "alg": "HS256",  // Algorithm
  "typ": "JWT"     // Type
}

// Payload (Claims)
{
  "sub": "user123",        // Subject (user ID)
  "iat": 1609459200,       // Issued at
  "exp": 1609545600,       // Expiration
  "iss": "myapp.com",      // Issuer
  "aud": "myapp.com",      // Audience
  "role": "user",          // Custom claim
  "permissions": ["read"]  // Custom claim
}

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

Token Generation#

import jwt from 'jsonwebtoken';

interface TokenPayload {
  userId: string;
  email: string;
  role: string;
}

const ACCESS_TOKEN_SECRET = process.env.ACCESS_TOKEN_SECRET!;
const REFRESH_TOKEN_SECRET = process.env.REFRESH_TOKEN_SECRET!;

function generateAccessToken(payload: TokenPayload): string {
  return jwt.sign(payload, ACCESS_TOKEN_SECRET, {
    expiresIn: '15m',      // Short-lived
    issuer: 'myapp.com',
    audience: 'myapp.com',
  });
}

function generateRefreshToken(userId: string): string {
  return jwt.sign(
    { userId, tokenVersion: 1 },
    REFRESH_TOKEN_SECRET,
    {
      expiresIn: '7d',     // Longer-lived
      issuer: 'myapp.com',
    }
  );
}

// Login endpoint
app.post('/auth/login', async (req, res) => {
  const { email, password } = req.body;

  const user = await validateCredentials(email, password);
  if (!user) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  const accessToken = generateAccessToken({
    userId: user.id,
    email: user.email,
    role: user.role,
  });

  const refreshToken = generateRefreshToken(user.id);

  // Store refresh token hash in database
  await db.refreshToken.create({
    data: {
      userId: user.id,
      tokenHash: hashToken(refreshToken),
      expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
    },
  });

  // Send refresh token as httpOnly cookie
  res.cookie('refreshToken', refreshToken, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict',
    maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
  });

  res.json({ accessToken });
});

Token Verification#

import jwt, { JwtPayload } from 'jsonwebtoken';

interface VerifiedPayload extends JwtPayload {
  userId: string;
  email: string;
  role: string;
}

function verifyAccessToken(token: string): VerifiedPayload {
  return jwt.verify(token, ACCESS_TOKEN_SECRET, {
    issuer: 'myapp.com',
    audience: 'myapp.com',
  }) as VerifiedPayload;
}

// Middleware
function authenticate(req: Request, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization;

  if (!authHeader?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing token' });
  }

  const token = authHeader.slice(7);

  try {
    const payload = verifyAccessToken(token);
    req.user = payload;
    next();
  } catch (error) {
    if (error instanceof jwt.TokenExpiredError) {
      return res.status(401).json({ error: 'Token expired' });
    }
    if (error instanceof jwt.JsonWebTokenError) {
      return res.status(401).json({ error: 'Invalid token' });
    }
    return res.status(401).json({ error: 'Authentication failed' });
  }
}

Refresh Token Flow#

// Refresh endpoint
app.post('/auth/refresh', async (req, res) => {
  const refreshToken = req.cookies.refreshToken;

  if (!refreshToken) {
    return res.status(401).json({ error: 'Refresh token required' });
  }

  try {
    const payload = jwt.verify(refreshToken, REFRESH_TOKEN_SECRET) as {
      userId: string;
      tokenVersion: number;
    };

    // Verify token exists in database and hasn't been revoked
    const storedToken = await db.refreshToken.findFirst({
      where: {
        userId: payload.userId,
        tokenHash: hashToken(refreshToken),
        revokedAt: null,
        expiresAt: { gt: new Date() },
      },
    });

    if (!storedToken) {
      return res.status(401).json({ error: 'Invalid refresh token' });
    }

    // Get user
    const user = await db.user.findUnique({
      where: { id: payload.userId },
    });

    if (!user) {
      return res.status(401).json({ error: 'User not found' });
    }

    // Check token version (for forced logout)
    if (user.tokenVersion !== payload.tokenVersion) {
      return res.status(401).json({ error: 'Token revoked' });
    }

    // Generate new tokens
    const newAccessToken = generateAccessToken({
      userId: user.id,
      email: user.email,
      role: user.role,
    });

    // Optionally rotate refresh token
    const newRefreshToken = generateRefreshToken(user.id);

    // Revoke old refresh token
    await db.refreshToken.update({
      where: { id: storedToken.id },
      data: { revokedAt: new Date() },
    });

    // Store new refresh token
    await db.refreshToken.create({
      data: {
        userId: user.id,
        tokenHash: hashToken(newRefreshToken),
        expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
      },
    });

    res.cookie('refreshToken', newRefreshToken, {
      httpOnly: true,
      secure: process.env.NODE_ENV === 'production',
      sameSite: 'strict',
      maxAge: 7 * 24 * 60 * 60 * 1000,
    });

    res.json({ accessToken: newAccessToken });
  } catch (error) {
    return res.status(401).json({ error: 'Invalid refresh token' });
  }
});

// Logout
app.post('/auth/logout', async (req, res) => {
  const refreshToken = req.cookies.refreshToken;

  if (refreshToken) {
    // Revoke refresh token
    await db.refreshToken.updateMany({
      where: { tokenHash: hashToken(refreshToken) },
      data: { revokedAt: new Date() },
    });
  }

  res.clearCookie('refreshToken');
  res.json({ message: 'Logged out' });
});

// Force logout all sessions
async function revokeAllTokens(userId: string) {
  // Increment token version
  await db.user.update({
    where: { id: userId },
    data: { tokenVersion: { increment: 1 } },
  });

  // Revoke all refresh tokens
  await db.refreshToken.updateMany({
    where: { userId, revokedAt: null },
    data: { revokedAt: new Date() },
  });
}

Client-Side Token Management#

// Token storage and refresh
class AuthService {
  private accessToken: string | null = null;
  private refreshPromise: Promise<string> | null = null;

  async getAccessToken(): Promise<string | null> {
    if (this.accessToken && !this.isTokenExpired(this.accessToken)) {
      return this.accessToken;
    }

    return this.refreshAccessToken();
  }

  private isTokenExpired(token: string): boolean {
    try {
      const payload = JSON.parse(atob(token.split('.')[1]));
      // Refresh 1 minute before expiry
      return payload.exp * 1000 < Date.now() + 60000;
    } catch {
      return true;
    }
  }

  async refreshAccessToken(): Promise<string | null> {
    // Deduplicate concurrent refresh requests
    if (this.refreshPromise) {
      return this.refreshPromise;
    }

    this.refreshPromise = (async () => {
      try {
        const response = await fetch('/auth/refresh', {
          method: 'POST',
          credentials: 'include', // Include cookies
        });

        if (!response.ok) {
          throw new Error('Refresh failed');
        }

        const { accessToken } = await response.json();
        this.accessToken = accessToken;
        return accessToken;
      } catch (error) {
        this.accessToken = null;
        throw error;
      } finally {
        this.refreshPromise = null;
      }
    })();

    return this.refreshPromise;
  }

  async fetch(url: string, options: RequestInit = {}): Promise<Response> {
    const token = await this.getAccessToken();

    const response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        Authorization: token ? `Bearer ${token}` : '',
      },
    });

    if (response.status === 401) {
      // Try refresh once
      const newToken = await this.refreshAccessToken();

      if (newToken) {
        return fetch(url, {
          ...options,
          headers: {
            ...options.headers,
            Authorization: `Bearer ${newToken}`,
          },
        });
      }
    }

    return response;
  }
}

Security Considerations#

// Use strong secrets
// Generate with: node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

// Validate algorithm
const payload = jwt.verify(token, secret, {
  algorithms: ['HS256'], // Explicitly specify allowed algorithms
});

// Never trust client-provided algorithm
// Always verify signature server-side

// Keep payloads minimal
// Don't include sensitive data
const payload = {
  userId: user.id,
  role: user.role,
  // NOT: password, creditCard, etc.
};

// Use short expiration for access tokens
const accessToken = jwt.sign(payload, secret, {
  expiresIn: '15m', // 15 minutes max
});

// Implement token blocklist for immediate revocation
const revokedTokens = new Set<string>();

function isTokenRevoked(token: string): boolean {
  const jti = jwt.decode(token)?.jti;
  return jti ? revokedTokens.has(jti) : false;
}

Best Practices#

Token Security:
✓ Use strong, unique secrets
✓ Short access token expiry (15m)
✓ Store refresh tokens securely
✓ Implement token rotation

Storage:
✓ httpOnly cookies for refresh tokens
✓ Memory for access tokens
✓ Never localStorage for tokens
✓ Use secure cookie flags

Validation:
✓ Verify signature
✓ Check expiration
✓ Validate issuer and audience
✓ Use explicit algorithm

Revocation:
✓ Implement token blocklist
✓ Store refresh tokens in DB
✓ Support forced logout
✓ Handle token rotation

JWTs enable scalable authentication when implemented securely. Use short-lived access tokens with refresh token rotation, store tokens appropriately, and implement proper revocation. Never store sensitive data in tokens and always validate on the server side.