JWT Security Considerations

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// HOW THE ATTACK WORKS (DO NOT DO THIS IN PRODUCTION)
 
// Server's legitimate setup
const publicKey = fs.readFileSync('public.pem');  // For verifying RS256
const privateKey = fs.readFileSync('private.pem');  // For signing RS256
 
// Legitimate token creation
const legitimateToken = jwt.sign(
    { sub: 'user-123', admin: false },
    privateKey,
    { algorithm: 'RS256' }
);
 
// VULNERABLE verification (uses algorithm from token header)
function vulnerableVerify(token: string) {
    const decoded = jwt.decode(token, { complete: true });
    const algorithm = decoded.header.alg;  // DANGER: Trusting token's claim
    
    // If algorithm is HS256, 'publicKey' is used as HMAC secret
    // If algorithm is RS256, 'publicKey' is used as RSA public key
    return jwt.verify(token, publicKey, { algorithms: [algorithm] });
}
 
// Attacker's forged token
const forgedToken = jwt.sign(
    { sub: 'user-123', admin: true },  // Escalated privileges!
    publicKey,  // Using public key as HMAC secret
    { algorithm: 'HS256' }  // Switching to symmetric algorithm
);
 
// Vulnerable server accepts the forged token!
vulnerableVerify(forgedToken);  // SUCCEEDS - attacker is now admin

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// SECURE: Explicit algorithm specification
const EXPECTED_ALGORITHM = 'RS256';
 
function secureVerify(token: string, publicKey: Buffer): JwtPayload {
    // Explicitly specify the ONLY algorithm we accept
    return jwt.verify(token, publicKey, {
        algorithms: [EXPECTED_ALGORITHM],  // Rejects anything else
    }) as JwtPayload;
}
 
// Even better: Use different keys for different algorithms
// This makes algorithm confusion structurally impossible
 
interface KeyProvider {
    getRS256Key(): Buffer;   // Public key for RS256
    getHS256Key(): Buffer;   // Secret for HS256 (not the public key!)
}
 
function superSecureVerify(
    token: string, 
    keyProvider: KeyProvider
): JwtPayload {
    // Decode header first (without verification)
    const decoded = jwt.decode(token, { complete: true });
    
    // Select key based on OUR configuration, not the token
    const algorithm = EXPECTED_ALGORITHM;
    const key = algorithm.startsWith('RS') 
        ? keyProvider.getRS256Key()
        : keyProvider.getHS256Key();
    
    return jwt.verify(token, key, {
        algorithms: [algorithm],
    }) as JwtPayload;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// UNSIGNED TOKEN ATTACK
 
// Attacker constructs a token with alg: none
const header = { alg: 'none', typ: 'JWT' };
const payload = { sub: 'admin', role: 'super_admin' };
 
// Base64URL encode
const encodedHeader = Buffer.from(JSON.stringify(header)).toString('base64url');
const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
 
// No signature (or empty signature)
const forgedToken = `${encodedHeader}.${encodedPayload}.`;
 
// Vulnerable libraries may accept this!
// jwt.verify(forgedToken, secret, { algorithms: ['HS256', 'none'] })  // BAD!
 
// PREVENTION: Never include 'none' in allowed algorithms
jwt.verify(token, secret, {
    algorithms: ['HS256'],  // Explicitly list ONLY real algorithms
});
 
// Or explicitly reject 'none'
function rejectNoneAlgorithm(token: string): void {
    const decoded = jwt.decode(token, { complete: true });
    
    if (!decoded || !decoded.header) {
        throw new Error('Invalid token format');
    }
    
    if (decoded.header.alg.toLowerCase() === 'none') {
        throw new Error('Algorithm "none" is not permitted');
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

// JKU INJECTION ATTACK EXAMPLE
 
// Attacker creates a key pair
const attackerKeyPair = crypto.generateKeyPairSync('rsa', {
    modulusLength: 2048,
});
 
// Attacker hosts their public key at an attacker-controlled URL
// https://evil.com/.well-known/jwks.json
// {
//   "keys": [{
//     "kty": "RSA",
//     "kid": "attacker-key",
//     "n": "...",
//     "e": "AQAB"
//   }]
// }
 
// Attacker forges token pointing to their keys
const forgedToken = jwt.sign(
    { sub: 'admin', role: 'super_admin' },
    attackerKeyPair.privateKey,
    { 
        algorithm: 'RS256',
        header: {
            jku: 'https://evil.com/.well-known/jwks.json',  // Attacker's key URL
            kid: 'attacker-key',
        },
    }
);
 
// VULNERABLE verification fetches key from jku header
async function vulnerableVerify(token: string) {
    const decoded = jwt.decode(token, { complete: true });
    const jku = decoded.header.jku;  // DANGER: Trusting token's URL
    
    // Fetches attacker's key from attacker's server
    const keys = await fetch(jku).then(r => r.json());
    const key = keys.keys.find(k => k.kid === decoded.header.kid);
    
    return jwt.verify(token, key);  // Verifies against attacker's key!
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

// SECURE: Statically configured JWKS with key pinning
 
interface SecureKeyProvider {
    // Cached keys from trusted JWKS endpoint
    private keyCache: Map<string, crypto.KeyObject> = new Map();
    private readonly TRUSTED_JWKS_URL = 'https://auth.mycompany.com/.well-known/jwks.json';
    private readonly TRUSTED_ISSUER = 'https://auth.mycompany.com';
    
    async getKey(kid: string): Promise<crypto.KeyObject> {
        // Return from cache if available
        if (this.keyCache.has(kid)) {
            return this.keyCache.get(kid)!;
        }
        
        // Fetch from TRUSTED URL only (not from token)
        const keys = await this.fetchTrustedKeys();
        
        const key = keys.find(k => k.kid === kid);
        if (!key) {
            throw new Error(`Unknown key ID: ${kid}`);
        }
        
        const cryptoKey = crypto.createPublicKey(key);
        this.keyCache.set(kid, cryptoKey);
        return cryptoKey;
    }
    
    private async fetchTrustedKeys(): Promise<JWK[]> {
        // ONLY fetch from trusted, hardcoded URL
        const response = await fetch(this.TRUSTED_JWKS_URL);
        
        if (!response.ok) {
            throw new Error('Failed to fetch JWKS');
        }
        
        const data = await response.json();
        return data.keys;
    }
}
 
// Verify using secure key provider
async function secureVerify(token: string): Promise<JwtPayload> {
    const decoded = jwt.decode(token, { complete: true });
    
    // IGNORE jku, x5u, jwk, x5c from the token
    // Use kid only to select from OUR pre-trusted keys
    const kid = decoded?.header?.kid;
    if (!kid) {
        throw new Error('Token missing kid header');
    }
    
    const key = await secureKeyProvider.getKey(kid);
    
    return jwt.verify(token, key, {
        algorithms: ['RS256'],
        issuer: 'https://auth.mycompany.com',  // Verify issuer too
    }) as JwtPayload;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

// SERVER: Setting secure cookies
 
app.post('/api/auth/login', async (req, res) => {
    const user = await authenticate(req.body);
    const tokens = await tokenService.createTokenPair(user);
    
    // Set refresh token as httpOnly cookie
    res.cookie('refresh_token', tokens.refreshToken, {
        httpOnly: true,     // Inaccessible to JavaScript
        secure: true,       // HTTPS only
        sameSite: 'strict', // CSRF protection
        path: '/api/auth',  // Only sent to auth endpoints
        maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
    });
    
    // Return access token in response body
    // Client stores this in memory only
    res.json({
        accessToken: tokens.accessToken,
        expiresIn: 900, // 15 minutes
    });
});
 
app.post('/api/auth/refresh', async (req, res) => {
    // Refresh token comes from httpOnly cookie automatically
    const refreshToken = req.cookies.refresh_token;
    
    if (!refreshToken) {
        return res.status(401).json({ error: 'No refresh token' });
    }
    
    try {
        const tokens = await tokenService.rotateRefreshToken(refreshToken);
        
        // Set new refresh token cookie
        res.cookie('refresh_token', tokens.refreshToken, {
            httpOnly: true,
            secure: true,
            sameSite: 'strict',
            path: '/api/auth',
            maxAge: 7 * 24 * 60 * 60 * 1000,
        });
        
        res.json({
            accessToken: tokens.accessToken,
            expiresIn: 900,
        });
    } catch (error) {
        // Clear invalid refresh token cookie
        res.clearCookie('refresh_token', { path: '/api/auth' });
        return res.status(401).json({ error: 'Invalid refresh token' });
    }
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

// CLIENT: Secure token handling
 
class SecureTokenManager {
    // Store access token in memory ONLY
    // Lost on page refresh — that's intentional
    private accessToken: string | null = null;
    private tokenExpiresAt: number = 0;
    
    setAccessToken(token: string, expiresIn: number): void {
        this.accessToken = token;
        this.tokenExpiresAt = Date.now() + (expiresIn * 1000);
    }
    
    getAccessToken(): string | null {
        // Check if token is still valid
        if (!this.accessToken || Date.now() >= this.tokenExpiresAt) {
            return null;
        }
        return this.accessToken;
    }
    
    async ensureValidToken(): Promise<string> {
        const token = this.getAccessToken();
        if (token) return token;
        
        // Refresh using httpOnly cookie (automatically included)
        const response = await fetch('/api/auth/refresh', {
            method: 'POST',
            credentials: 'include', // Include cookies
        });
        
        if (!response.ok) {
            throw new SessionExpiredError();
        }
        
        const data = await response.json();
        this.setAccessToken(data.accessToken, data.expiresIn);
        return data.accessToken;
    }
    
    clear(): void {
        this.accessToken = null;
        this.tokenExpiresAt = 0;
    }
}
 
// Usage with fetch wrapper
const tokenManager = new SecureTokenManager();
 
async function authenticatedFetch(url: string, options: RequestInit = {}): Promise<Response> {
    const token = await tokenManager.ensureValidToken();
    
    return fetch(url, {
        ...options,
        headers: {
            ...options.headers,
            'Authorization': `Bearer ${token}`,
        },
    });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// Content Security Policy header
app.use((req, res, next) => {
    res.setHeader('Content-Security-Policy', [
        "default-src 'self'",
        "script-src 'self'",  // No inline scripts, no external scripts
        "style-src 'self' 'unsafe-inline'",  // Allow inline styles (CSS-in-JS)
        "img-src 'self' data: https:",
        "connect-src 'self' https://api.example.com",
        "frame-ancestors 'none'",  // Prevent clickjacking
        "base-uri 'self'",
        "form-action 'self'",
    ].join('; '));
    next();
});
 
// Even with XSS, httpOnly refresh tokens can't be stolen directly
// Attacker can only use them in-context (session riding)
// Short access token expiration limits damage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// Token binding example - include client fingerprint in token
 
function createBoundToken(user: User, clientInfo: ClientInfo): string {
    // Create fingerprint from client characteristics
    const fingerprint = crypto.createHash('sha256')
        .update(clientInfo.userAgent)
        .update(clientInfo.ipSubnet)  // /24 for IPv4, /48 for IPv6
        .digest('hex')
        .substring(0, 16);
    
    return jwt.sign({
        sub: user.id,
        fingerprint,  // Bound to this client
        iat: Math.floor(Date.now() / 1000),
        exp: Math.floor(Date.now() / 1000) + 900,
    }, secret);
}
 
function validateBoundToken(token: string, clientInfo: ClientInfo): JwtPayload {
    const payload = jwt.verify(token, secret) as JwtPayload;
    
    // Verify fingerprint matches current client
    const expectedFingerprint = crypto.createHash('sha256')
        .update(clientInfo.userAgent)
        .update(clientInfo.ipSubnet)
        .digest('hex')
        .substring(0, 16);
    
    if (payload.fingerprint !== expectedFingerprint) {
        // Token used from different client - possible theft
        throw new TokenBindingMismatchError();
    }
    
    return payload;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

// Secure key loading from environment/secrets manager
 
import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
 
class SecureKeyProvider {
    private jwtSecret: string | null = null;
    private rsaPrivateKey: crypto.KeyObject | null = null;
    private rsaPublicKey: crypto.KeyObject | null = null;
    
    async initialize(): Promise<void> {
        const secrets = new SecretsManagerClient({});
        
        // Load from AWS Secrets Manager (or HashiCorp Vault, etc.)
        const response = await secrets.send(new GetSecretValueCommand({
            SecretId: 'production/jwt/signing-keys',
        }));
        
        const keys = JSON.parse(response.SecretString!);
        
        // HMAC secret - should be at least 256 bits (32 bytes)
        this.jwtSecret = keys.hmacSecret;
        if (Buffer.from(this.jwtSecret).length < 32) {
            throw new Error('HMAC secret must be at least 256 bits');
        }
        
        // RSA keys
        this.rsaPrivateKey = crypto.createPrivateKey(keys.rsaPrivateKey);
        this.rsaPublicKey = crypto.createPublicKey(keys.rsaPublicKey);
    }
    
    getHmacSecret(): string {
        if (!this.jwtSecret) {
            throw new Error('Keys not initialized');
        }
        return this.jwtSecret;
    }
    
    getRsaPrivateKey(): crypto.KeyObject {
        if (!this.rsaPrivateKey) {
            throw new Error('Keys not initialized');
        }
        return this.rsaPrivateKey;
    }
    
    getRsaPublicKey(): crypto.KeyObject {
        if (!this.rsaPublicKey) {
            throw new Error('Keys not initialized');
        }
        return this.rsaPublicKey;
    }
}
 
// Strong secret generation (for development/initial setup)
function generateStrongSecret(): string {
    // 256 bits = 32 bytes of cryptographically random data
    return crypto.randomBytes(32).toString('base64');
}
 
// DO NOT DO THIS:
// const JWT_SECRET = 'mysecretkey';  // Hardcoded, predictable
// const JWT_SECRET = process.env.JWT_SECRET || 'default';  // Fallback is dangerous

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

// Secure authentication event logging
 
interface AuthEvent {
    timestamp: Date;
    eventType: 'login' | 'logout' | 'refresh' | 'revoke' | 'validation_failure';
    userId?: string;
    tokenId?: string;      // jti - safe to log
    clientIp: string;
    userAgent: string;
    success: boolean;
    failureReason?: string;
    metadata?: Record<string, unknown>;
}
 
class SecureAuthLogger {
    async log(event: AuthEvent): Promise<void> {
        // Sanitize before logging
        const sanitizedEvent = {
            ...event,
            // Truncate/hash potentially sensitive fields
            userAgent: event.userAgent.substring(0, 200),
            metadata: this.sanitizeMetadata(event.metadata),
        };
        
        // Send to structured logging system
        await this.logger.info('auth_event', sanitizedEvent);
        
        // Send critical events to security team
        if (this.isSecurityRelevant(event)) {
            await this.alerter.send(sanitizedEvent);
        }
    }
    
    private sanitizeMetadata(metadata?: Record<string, unknown>): Record<string, unknown> {
        if (!metadata) return {};
        
        // Remove sensitive keys
        const { token, password, secret, key, ...safe } = metadata as any;
        return safe;
    }
    
    private isSecurityRelevant(event: AuthEvent): boolean {
        // Alert on security-relevant events
        return (
            event.eventType === 'revoke' ||
            event.failureReason?.includes('reuse') ||
            event.failureReason?.includes('algorithm') ||
            event.failureReason?.includes('injection')
        );
    }
}
 
// Monitoring queries to run
const SECURITY_QUERIES = {
    // Detect brute force attempts
    bruteForce: `
        SELECT client_ip, COUNT(*) as failures
        FROM auth_events
        WHERE event_type = 'login' 
        AND success = false
        AND timestamp > NOW() - INTERVAL '1 hour'
        GROUP BY client_ip
        HAVING COUNT(*) > 10
    `,
    
    // Detect unusual refresh patterns
    suspiciousRefresh: `
        SELECT user_id, COUNT(*) as refresh_count
        FROM auth_events
        WHERE event_type = 'refresh'
        AND timestamp > NOW() - INTERVAL '1 hour'
        GROUP BY user_id
        HAVING COUNT(*) > 100
    `,
    
    // Detect token reuse attempts
    tokenReuse: `
        SELECT * FROM auth_events
        WHERE failure_reason LIKE '%reuse%'
        AND timestamp > NOW() - INTERVAL '24 hours'
    `,
};