Spring Security 6 & JWT: The 6 Common Mistakes (and How to Fix Them)

Welcome back to our CoddyKit series on Spring Security 6 and JWT Authentication! In Post 1, we laid the groundwork with an introduction to getting started, and in Post 2, we explored best practices for building a solid foundation. Now, in this crucial third installment, we're going to shift our focus from what to do right to what often goes wrong. Even seasoned developers can stumble when integrating JWTs with Spring Security, leading to subtle bugs or, worse, significant security vulnerabilities.

Today, we'll uncover the six most common mistakes developers make and, more importantly, equip you with the knowledge to avoid them. By understanding these pitfalls, you can build more resilient, secure, and maintainable authentication systems.

Mistake 1: Neglecting Comprehensive JWT Validation

One of the most critical errors is assuming a JWT is valid just because it parses. A JWT's primary value comes from its verifiable integrity and authenticity. Without proper validation, an attacker could forge tokens, impersonate users, or gain unauthorized access.

How to Avoid It: Thorough Validation is Non-Negotiable

Always perform thorough validation of the JWT's signature, expiration, and essential claims. Spring Security 6, especially with its OAuth2 resource server capabilities, provides robust mechanisms for this. Ensure your JwtDecoder is configured correctly to check all necessary aspects.

import com.nimbusds.jose.jwk.source.ImmutableSecret; // For symmetric keys
import com.nimbusds.jose.jwk.source.JWKSource;
import com.nimbusds.jose.proc.SecurityContext;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.oauth2.core.DelegatingOAuth2TokenValidator;
import org.springframework.security.oauth2.core.OAuth2TokenValidator;
import org.springframework.security.oauth2.jwt.*;

import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
import java.util.Arrays;
import java.util.Collections;

@Configuration
public class JwtValidationConfig {

    // Use a strong, securely stored key (e.g., from environment variables)
    private final String jwtSecret = "YOUR_VERY_STRONG_SECRET_KEY_AT_LEAST_32_BYTES_LONG_AND_SECURELY_STORED";

    @Bean
    public JwtDecoder jwtDecoder() {
        // For symmetric keys (HS256, HS384, HS512)
        SecretKey secretKey = new SecretKeySpec(jwtSecret.getBytes(), "HmacSHA256");
        NimbusJwtDecoder jwtDecoder = NimbusJwtDecoder.withSecretKey(secretKey).build();

        // For asymmetric keys (RS256, ES256), you'd use .withPublicKey() or .withJwkSetUri()
        // Example: .withJwkSetUri("https://your-auth-server.com/.well-known/jwks.json")

        // Customizing the JwtValidator to check issuer, audience, and timestamp
        OAuth2TokenValidator<Jwt> withIssuer = new JwtIssuerValidator("https://your-auth-server.com");
        OAuth2TokenValidator<Jwt> withAudience = new JwtAudienceValidator(Collections.singleton("your-api-resource"));
        OAuth2TokenValidator<Jwt> validator = new DelegatingOAuth2TokenValidator<>(
            withIssuer,
            withAudience,
            new JwtTimestampValidator() // Checks exp, nbf
        );

        jwtDecoder.setJwtValidator(validator);
        return jwtDecoder;
    }
}

Key validations to check:

• Signature Verification: Paramount for integrity. Your JwtDecoder handles this using the configured secret/public key.
• Expiration (exp claim): Tokens must have a limited lifespan. Reject expired tokens immediately.
• Not Before (nbf claim): Ensures the token isn't used before its intended activation time.
• Issuer (iss claim): Verifies the token was issued by the expected authentication server.
• Audience (aud claim): Confirms the token is intended for your specific API resource.
• Subject (sub claim): Identifies the principal.

Mistake 2: Storing JWTs Insecurely (e.g., Local Storage)

A common mistake in client-side applications is storing JWTs in browser localStorage or sessionStorage. While convenient, this practice exposes your tokens to Cross-Site Scripting (XSS) attacks. If an attacker can inject malicious JavaScript into your page, they can easily retrieve your user's JWT and use it to impersonate them.

How to Avoid It: Embrace HttpOnly Cookies

The most secure way to store access tokens in a browser environment is within HttpOnly cookies. These cookies cannot be accessed by client-side JavaScript, significantly mitigating XSS risks. For refresh tokens, a secure HttpOnly cookie is also recommended, often with additional security attributes like Secure and SameSite=Strict.

• Access Tokens: Store in an HttpOnly cookie. Set its expiration to match the JWT's expiry.
• Refresh Tokens: Also store in an HttpOnly cookie, ideally with a longer expiration. Use this token to request new access tokens.
• CSRF Protection: When using cookies, ensure you implement CSRF protection. Spring Security handles this automatically for session-based authentication, but for JWTs, you might need to manage it if your client is sending a CSRF token in a header.

Mistake 3: Using JWTs for Session Management (Stateless vs. State-aware)

The core principle of JWTs is statelessness. This means the server doesn't need to maintain session information for a user after issuing the token. However, developers sometimes try to treat JWTs like traditional session IDs, leading to complications, especially around token revocation.

How to Avoid It: Embrace Statelessness, Plan for Revocation

Understand that once a JWT is issued, it's valid until it expires. Revoking an individual JWT before its natural expiry is challenging in a truly stateless system. If revocation is a hard requirement (e.g., after password change, logout), consider these strategies:

• Short-lived Access Tokens + Refresh Tokens: Use very short-lived access tokens (e.g., 5-15 minutes) and longer-lived refresh tokens. If a token is compromised, its window of vulnerability is small. Revoke refresh tokens when necessary.
• Token Blacklisting/Whitelisting: If immediate revocation is critical, you'll need a mechanism (like a Redis cache) to blacklist compromised tokens or whitelist only valid ones. This introduces state, but might be necessary for specific use cases.
• Configure Spring Security for Stateless Sessions: Ensure your security configuration explicitly disables session creation.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            // ... other configurations ...
            .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            // ... other configurations ...
            ;
        return http.build();
    }
}

Mistake 4: Overloading JWTs with Too Much Information

While JWTs can carry claims, there's a temptation to cram too much user data into them. This can lead to large tokens, performance issues, and potentially expose sensitive information if the token is intercepted (even if encrypted, the size itself can be a concern).

How to Avoid It: Keep Claims Minimal and Relevant

JWTs should be compact. Store only the absolute essential information required for authentication and authorization decisions within the token itself. This typically includes:

• User ID (sub)
• Roles/Authorities (roles, scope)
• Expiration (exp), Issuer (iss), Audience (aud)

Any additional user details (e.g., full name, address, preferences) should be fetched from a database or a dedicated user service using the user ID from the token, rather than embedding them directly in the JWT.

Mistake 5: Incorrectly Configuring Security Filters

Spring Security's power lies in its filter chain. Misconfiguring this chain, especially when integrating JWTs, can lead to authentication bypasses, unexpected behavior, or even a completely unsecured application.

How to Avoid It: Understand the Filter Chain and Order

Pay close attention to how your JWT authentication filter is integrated into Spring Security's filter chain. Common issues include:

• Ignoring Authentication for Critical Endpoints: Accidentally allowing unauthenticated access to sensitive APIs via .permitAll() or misconfigured matchers.
• JWT Filter Not Being Applied: The JWT filter might be missing or placed incorrectly, leading to requests not being authenticated.
• Conflicting Authentication Mechanisms: If you have multiple authentication providers (e.g., form login, JWT), ensure they don't interfere with each other or that the correct one is prioritized.

With Spring Security 6, the oauth2ResourceServer().jwt() configuration simplifies much of this, but you still need to be careful with authorizeHttpRequests().

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityFilterChainConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable()) // Disable CSRF for stateless APIs
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/auth/**").permitAll() // Allow unauthenticated access for login/registration
                .requestMatchers("/public/**").permitAll()
                .requestMatchers("/admin/**").hasRole("ADMIN") // Require ADMIN role for admin paths
                .anyRequest().authenticated() // All other requests require authentication
            )
            .oauth2ResourceServer(oauth2 -> oauth2.jwt()) // Enable JWT authentication
            .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)); // Crucial for JWTs

        return http.build();
    }
}

Always review your authorization rules carefully. Use specific matchers before general ones (e.g., .requestMatchers("/admin/**") before .anyRequest()).

Mistake 6: Weak Secret Keys or Algorithm Misuse

The security of your JWTs hinges entirely on the strength and secrecy of your cryptographic keys. Using weak keys or inappropriate algorithms is like leaving your front door unlocked.

How to Avoid It: Strong Keys and Proper Algorithm Selection

• Strong Secret Keys: For symmetric algorithms (HS256, HS384, HS512), use a key that is at least 256 bits (32 bytes) long, generated securely, and stored in a safe place (e.g., environment variables, a secrets manager, not directly in source code).
• Asymmetric Keys (RSA/EC): For RS256 or ES256, ensure your private key is truly private and securely stored. The public key can be distributed or exposed via a JWKS endpoint.
• Avoid none Algorithm: Never, ever use the none algorithm. This algorithm indicates that the token is unsecured and its signature should not be verified, making it trivial for an attacker to forge tokens. Spring Security's JwtDecoder typically won't allow this by default, but be aware.
• Choose Appropriate Algorithm: HS256 is fine for services that only need to verify tokens they themselves issued. For distributed systems where multiple services (resource servers) need to verify tokens issued by a central authorization server, RS256 (RSA with SHA-256) is often preferred as it allows verification with a public key without sharing the private key.

Conclusion

Implementing JWT authentication with Spring Security 6 provides a powerful and flexible way to secure your APIs. However, like any powerful tool, it requires careful handling. By being aware of these common mistakes—from neglecting validation and insecure storage to misconfiguring filters and using weak keys—you can significantly enhance the security and robustness of your applications.

Take the time to review your existing implementations against these points, or keep them in mind as you build new ones. A small investment in understanding these common pitfalls can save you from major headaches down the road. Stay tuned for Post 4, where we'll explore advanced techniques and real-world use cases for Spring Security and JWTs!