JWT Security Best Practices

Understanding JWT Security

JSON Web Tokens (JWTs) are widely used for authentication and authorization, but they're also frequently misconfigured. This guide covers the essential security practices for working with JWTs.

Choosing the Right Algorithm

Symmetric Algorithms (HMAC)

Use HMAC algorithms when the same party signs and verifies tokens.

Asymmetric Algorithms (RSA/ECDSA)

Use asymmetric algorithms when different parties sign and verify tokens (e.g., microservices).

Secret Key Requirements

HMAC Secret Keys

For HMAC algorithms, your secret key should be:

• At least as long as the hash output (256 bits for HS256)
• Generated using a cryptographically secure random number generator
• Unique per environment (dev/staging/production)

# Good: Generate a secure 256-bit secret
openssl rand -base64 32

# Example output (DO NOT USE THIS!)
# K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=

Common Vulnerabilities & Prevention

1. Algorithm Confusion (alg=none)

Attackers may try to change the algorithm to "none" or switch between symmetric/asymmetric algorithms.

// VULNERABLE: Accepts any algorithm
jwt.verify(token, secret);

// SECURE: Explicitly specify allowed algorithms
jwt.verify(token, secret, { algorithms: ['HS256'] });

2. Missing Signature Verification

Always verify the signature before trusting token contents.

// VULNERABLE: Decodes without verification
const payload = jwt.decode(token);

// SECURE: Verifies signature first
const payload = jwt.verify(token, secret);

3. Key Confusion Attack

When using RS256, attackers may try to verify with the public key as an HMAC secret.

// VULNERABLE: Could be tricked into HMAC verification
jwt.verify(token, publicKey);

// SECURE: Explicitly require RS256
jwt.verify(token, publicKey, { algorithms: ['RS256'] });

4. Missing Expiration

Tokens without expiration never become invalid:

// Always include expiration
const token = jwt.sign(
  { userId: 123 },
  secret,
  { expiresIn: '1h' }  // or use 'exp' claim directly
);

Token Validation Checklist

Always validate these claims when verifying a JWT:

// Comprehensive validation
jwt.verify(token, secret, {
  algorithms: ['HS256'],
  issuer: 'https://yourapp.com',
  audience: 'your-api',
  clockTolerance: 30,  // 30 second clock skew
});

Token Lifetime & Refresh

Recommended Lifetimes

Refresh Token Strategy

Use short-lived access tokens with longer-lived refresh tokens:

• Store refresh tokens securely (HttpOnly cookies or secure storage)
• Implement refresh token rotation (issue new refresh token on each use)
• Maintain a token blacklist or use token families for revocation

Storage Best Practices

Browser Applications

Cookie Configuration

// Secure cookie settings
res.cookie('token', jwt, {
  httpOnly: true,     // Prevents JavaScript access
  secure: true,       // HTTPS only
  sameSite: 'strict', // CSRF protection
  maxAge: 3600000,    // 1 hour
  path: '/',
});

Token Revocation

JWTs are stateless by design, making revocation challenging. Consider these approaches:

Strategies

• Short expiration - Tokens naturally expire quickly
• Token blacklist - Store revoked token IDs (jti claim)
• Token versioning - Increment user's token version on logout
• Refresh token revocation - Revoke refresh tokens to prevent new access tokens

Implementation Checklist