JWT Authentication Validation

This documentation covers the comprehensive validation system implemented in the JWT Authentication Spring Boot Starter. The validation system ensures secure token handling through multiple layers of security checks.

Overview

The validation system consists of three main components:

• JwtAuthenticationFilter: Entry point filter that orchestrates the validation process
• TokenValidationUtils: Handles JWT token validation and verification
• CookieValidationUtils: Validates fingerprint cookies for additional security
• TokenRevoker: Manages token revocation and blacklisting

Architecture Flow

HTTP Request → JwtAuthenticationFilter → TokenValidationUtils → CookieValidationUtils → SecurityContext
                     ↓
              TokenRevoker (checks revocation)

JwtAuthenticationFilter

The main authentication filter that processes incoming requests and validates JWT tokens.

Key Features

• Extends OncePerRequestFilter to ensure single execution per request
• Validates Bearer token format
• Orchestrates token and cookie validation
• Sets Spring Security context upon successful validation

Validation Flow

1. Header Validation: Checks for Authorization header with Bearer prefix
2. Token Validation: Delegates to TokenValidationUtils
3. Cookie Validation: Validates fingerprint cookie via CookieValidationUtils
4. User Loading: Loads user details and creates authentication token
5. Security Context: Sets authentication in Spring Security context

Error Handling

• Returns HTTP 401 for authentication failures
• Clears security context on validation errors
• Comprehensive logging for debugging

TokenValidationUtils

Handles the core JWT token validation logic with multiple security layers.

Validation Steps

1. Token Revocation Check

if (tokenRevoker.isTokenRevoked(encryptedToken)) {
    log.warn("Token revoked: {}", encryptedToken);
    return false;
}

• Checks if token is in revocation blacklist
• Prevents use of compromised tokens

2. Token Decryption

String token = decryptToken(encryptedToken);

• Decrypts the encrypted JWT token
• Uses TokenCipher for secure decryption

3. Fingerprint Validation

String fingerprint = cookieProvider.extractFingerprintCookie(request);
String fingerprintHash = FingerprintUtils.hashFingerprint(fingerprint);

• Extracts fingerprint from HTTP cookies
• Hashes fingerprint for comparison with token claim

4. JWT Claims Verification

Uses Auth0 JWT library for comprehensive token verification:

• Issuer Validation: Verifies token issuer matches expected value
• Fingerprint Claim: Validates fingerprint hash matches token claim
• Temporal Validation: Checks notBefore and expiration times
• Algorithm Verification: Ensures token uses expected signing algorithm

Security Features

• Encrypted Tokens: All tokens are encrypted before transmission
• Fingerprint Binding: Tokens are bound to browser fingerprints
• Issuer Validation: Prevents token forgery from other sources
• Time-based Validation: Prevents replay attacks with expired tokens

CookieValidationUtils

Provides comprehensive fingerprint cookie validation with multiple security checks.

Validation Layers

1. Cookie Existence Check

if (request.getCookies() == null || request.getCookies().length == 0) {
    throw new FingerprintValidationException("No cookies found in request");
}

2. Fingerprint Cookie Retrieval

• Searches for specific fingerprint cookie by name
• Uses configurable cookie name from JwtProperties

3. Format Validation

private static final int FINGERPRINT_LENGTH = 200;
private static final String FINGERPRINT_PATTERN = "^[a-f0-9]{200}$";

• Length Check: Ensures exactly 200 characters
• Pattern Validation: Only allows hexadecimal characters (a-f, 0-9)
• Null/Empty Check: Prevents null or empty fingerprints

4. Security Flags Validation

if (request.isSecure() && !cookie.getSecure()) {
    throw new FingerprintValidationException("Fingerprint cookie must have Secure flag set for HTTPS requests");
}

• Secure Flag: Required for HTTPS requests
• HttpOnly: Prevents JavaScript access (configured externally)
• SameSite: CSRF protection (configured externally)

5. Expiration Validation

if (maxAge == 0) {
    throw new FingerprintValidationException("Fingerprint cookie has expired");
}

• Checks cookie hasn't expired
• Validates against expected maximum age
• Warns if cookie age exceeds expectations

6. Fingerprint Matching

public boolean validateFingerprintMatch(String rawFingerprint, String token) {
    String tokenFingerprintHash = jwtTokenProvider.getHashedFingerprintFromToken(token);
    String hashedFingerprint = hashFingerprint(rawFingerprint);
    return hashedFingerprint.equals(tokenFingerprintHash);
}

• Compares hashed cookie fingerprint with token claim
• Prevents token theft and session hijacking
• Comprehensive logging for security monitoring

TokenRevoker

Manages token revocation and blacklisting with automatic cleanup.

Key Features

1. Token Revocation

public void revokeToken(String jwtInHex) {
    String decipheredToken = tokenCipher.decipherToken(jwtInHex);
    String jwtTokenDigestInHex = calculateSHA256Hash(decipheredToken);
    // Store in revocation database
}

• Decrypts token before processing
• Creates SHA-256 hash digest for storage
• Stores revocation timestamp

2. Revocation Check

public boolean isTokenRevoked(String jwtInHex) {
    String digest = calculateTokenDigest(jwtInHex);
    return revokedTokenRepository.findByJwtTokenDigest(digest).isPresent();
}

• Fast database lookup by token digest
• Returns true for invalid/malformed tokens

3. Automatic Cleanup

protected void scheduleRevokedTokensDeletion() {
    scheduler.scheduleAtFixedRate(
        this::deleteAllRevokedTokensFromDb,
        initialDelay,
        30 * 24 * 60, // 30 days
        TimeUnit.MINUTES
    );
}

• Scheduled cleanup every 30 days
• Runs at 3:00 AM to minimize impact
• Prevents database bloat

Security Considerations

Multi-Layer Defense

1. Token Encryption: All tokens encrypted in transit
2. Fingerprint Binding: Prevents cross-device token theft
3. Revocation System: Immediate token invalidation capability
4. Temporal Validation: Time-based security checks
5. Cookie Security: Secure, HttpOnly, SameSite cookies
6. Input Validation: Strict format validation for all inputs

Attack Mitigation

• Token Theft: Fingerprint binding prevents use on different devices
• Session Hijacking: Cookie security flags and fingerprint validation
• Replay Attacks: Temporal validation and revocation system
• CSRF: SameSite cookie configuration
• XSS: HttpOnly cookies prevent JavaScript access

Configuration

Required Properties

jwt:
  fingerprint-cookie-name: "fp_token"
  fingerprint-cookie-max-age: 3600
  issuer-id: "your-application"

Database Schema

CREATE TABLE revoked_tokens (
    id BIGINT PRIMARY KEY,
    jwt_token_digest VARCHAR(255) UNIQUE NOT NULL,
    revocation_date TIMESTAMP NOT NULL
);

Error Handling

Exception Types

• FingerprintValidationException: Cookie validation failures
• TokenValidationException: JWT validation failures
• TokenProcessingException: Encryption/decryption errors
• AuthenticationCredentialsNotFoundException: Authentication failures

Logging Levels

• DEBUG: Detailed validation flow information
• INFO: Authentication success/failure events
• WARN: Security violations and suspicious activity
• ERROR: System errors and unexpected failures

Best Practices

Implementation

1. Always validate both token and cookie
2. Use HTTPS in production environments
3. Configure proper cookie security flags
4. Monitor revocation database size
5. Implement proper error handling
6. Use structured logging for security events

Security

1. Regularly rotate signing keys
2. Monitor for suspicious authentication patterns
3. Implement rate limiting on authentication endpoints
4. Use strong encryption for token cipher
5. Validate all security configurations in production

Monitoring and Alerts

Key Metrics

• Authentication success/failure rates
• Token revocation frequency
• Fingerprint validation failures
• Cookie security flag violations
• Database cleanup execution

Recommended Alerts

• High authentication failure rates
• Unusual token revocation patterns
• Missing security cookie flags
• Database cleanup failures
• Encryption/decryption errors

This validation system provides enterprise-grade security for JWT authentication with comprehensive protection against common attack vectors.