JWT Token Best Practices and Common Pitfalls

JWT tokens are widely used but commonly implemented insecurely, leading to token theft, privilege escalation, or inability to revoke access.

JWT security best practices:

Token Creation:

const jwt = require('jsonwebtoken');

// GOOD: short-lived access token + refresh token
const accessToken = jwt.sign(
  { sub: user.id, role: user.role },
  process.env.JWT_SECRET,
  {
    expiresIn: '15m',   // Short-lived!
    algorithm: 'HS256',  // Or RS256 for asymmetric
    issuer: 'myapp',
    audience: 'myapp-api'
  }
);

// Refresh token: stored in DB, can be revoked
const refreshToken = crypto.randomBytes(64).toString('hex');
await db.refreshTokens.create({
  token: hashToken(refreshToken),
  userId: user.id,
  expiresAt: addDays(new Date(), 30)
});

Token Verification:

// ALWAYS verify algorithm, issuer, audience
try {
  const payload = jwt.verify(token, secret, {
    algorithms: ['HS256'],  // Prevent algorithm confusion
    issuer: 'myapp',
    audience: 'myapp-api'
  });
} catch (err) {
  if (err.name === 'TokenExpiredError') {
    // Redirect to refresh flow
  }
  // Invalid token - reject
}

Storage:

• Access token: memory (JS variable) or short-lived httpOnly cookie
• Refresh token: httpOnly, Secure, SameSite=Strict cookie
• NEVER localStorage for sensitive tokens (XSS can steal them)

Revocation:

• Access tokens can't be revoked (keep them short-lived)
• Refresh tokens: store in DB, delete on logout
• For immediate revocation: use a short blocklist cached in Redis

JWTs are self-contained and stateless by design, which means they can't be revoked once issued. This is both their strength (scalable) and weakness (security risk if stolen).

Implementing JWT-based authentication