Stateless JWT Authentication in Spring Boot

A Quick Recap: The Spring Security Filter Chain

Before we write any code, let's quickly refresh our memory on the Spring Security architecture. As we've discussed, every request to a secured application passes through a series of filters.

Our goal is to create and insert our own custom filter into this chain. This filter's single responsibility will be to look for a JWT in the request headers, validate it, and if it's valid, establish the user's identity for that request.

1. Configuring the SecurityFilterChain for Statelessness

First, we need to configure Spring Security to behave in a stateless manner. Since Spring Security 5.7, this is done by defining a SecurityFilterChain bean, which replaces the older WebSecurityConfigurerAdapter.

In your security configuration class (e.g., SecurityConfig), you'll define a bean like this:

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            // 1. Disable CSRF, as we are stateless and don't use sessions/cookies.
            .csrf(csrf -> csrf.disable())

            // 2. Set session management to stateless.
            .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))

            // 3. Define authorization rules for our endpoints.
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**").permitAll() // Login/register endpoints are public.
                .anyRequest().authenticated() // All other requests require authentication.
            );
        
        // We will add our custom JWT filter here later.

        return http.build();
    }
}

Key Points for Interviews:

• CSRF (.csrf().disable()): CSRF protection works by using a unique token stored in the user's session. Since we are building a stateless API and disabling sessions, this mechanism is not needed and can be disabled.
• Stateless Session (.sessionCreationPolicy(STATELESS)): This is the most critical setting. It tells Spring Security not to create or use any HttpSession. Each request must be authenticated independently, which is the core principle of token-based authentication.

2. The Heart of the Matter: The JwtAuthenticationFilter

Now, let's create the filter itself. Best practice is to extend OncePerRequestFilter, which guarantees the filter is executed only once for any given request.

This filter will perform the following steps for every incoming request:

1. Check for an Authorization header containing a Bearer token.
2. If the token exists, validate it.
3. If the token is valid, load the associated user from the database.
4. Set the authenticated user in Spring Security's SecurityContextHolder.

The logic within this filter is crucial, and the Toptal article "Spring Security With JWT for REST API" provides a clear, classic implementation.

Let's implement our version, JwtAuthenticationFilter.java:

@Component
@RequiredArgsConstructor // Lombok annotation for constructor injection
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtService jwtService; // Our service to handle JWTs
    private final UserDetailsService userDetailsService;

    @Override
    protected void doFilterInternal(
            @NonNull HttpServletRequest request,
            @NonNull HttpServletResponse response,
            @NonNull FilterChain filterChain) throws ServletException, IOException {

        final String authHeader = request.getHeader("Authorization");
        final String jwt;
        final String userEmail;

        // 1. Check if the Authorization header is present and correctly formatted
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            filterChain.doFilter(request, response); // If not, pass to the next filter
            return;
        }

        jwt = authHeader.substring(7); // Extract the token from "Bearer "
        userEmail = jwtService.extractUsername(jwt); // Extract username from token

        // 2. Check if user is extracted and not already authenticated
        if (userEmail != null && SecurityContextHolder.getContext().getAuthentication() == null) {
            UserDetails userDetails = this.userDetailsService.loadUserByUsername(userEmail);

            // 3. If token is valid, update the SecurityContextHolder
            if (jwtService.isTokenValid(jwt, userDetails)) {
                UsernamePasswordAuthenticationToken authToken = new UsernamePasswordAuthenticationToken(
                        userDetails,
                        null, // We don't have credentials
                        userDetails.getAuthorities()
                );
                authToken.setDetails(
                        new WebAuthenticationDetailsSource().buildDetails(request)
                );
                // This is the crucial step that authenticates the user for the request
                SecurityContextHolder.getContext().setAuthentication(authToken);
            }
        }
        filterChain.doFilter(request, response);
    }
}

This filter depends on a JwtService for token operations and a UserDetailsService (which you built in a previous lesson) to fetch user data.

3. Creating Supporting Components

Our filter won't work in isolation. It needs a way to generate, parse, and validate tokens. We'll follow the modern and secure approach of using asymmetric keys (RSA).

The video below by Dan Vega is an end-to-end guide. We will use it to implement the necessary components: the key generation, the configuration properties, the JwtEncoder/JwtDecoder beans, and the login endpoint.

After following the video, you will have:

• RSA key files (private.pem, public.pem).
• Configuration in application.properties pointing to these keys.
• JwtEncoder and JwtDecoder beans in your SecurityConfig.
• A TokenService (or JwtService) to generate tokens.
• A controller with a login endpoint that returns a JWT upon successful authentication.

4. Integrating the Filter into the Security Chain

The final step is to tell Spring Security to use our custom filter. We do this by adding it to the SecurityFilterChain bean we defined earlier.

Update your securityFilterChain method:

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig {

    private final JwtAuthenticationFilter jwtAuthFilter;
    private final AuthenticationProvider authenticationProvider; // Assumes you have this bean defined

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**").permitAll()
                .anyRequest().authenticated()
            )
            .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authenticationProvider(authenticationProvider) // Set the auth provider
            // Add our custom JWT filter before the standard UsernamePasswordAuthenticationFilter
            .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }
}

addFilterBefore(...) is the key. We are inserting our JwtAuthenticationFilter into the chain before the UsernamePasswordAuthenticationFilter. This ensures that for every request, we first check for a valid JWT. If one is found and validated, the user is authenticated, and subsequent filters will see this. If no JWT is present, the request proceeds down the chain, and if it hits a protected endpoint, an authentication error will be triggered as expected.

Conclusion

Congratulations! You have now implemented the complete flow for stateless JWT authentication in a Spring Boot application. This is a robust and scalable solution used widely in the industry.

Key Takeaways:

• Stateless Configuration: You must configure Spring Security's SecurityFilterChain to be stateless by disabling CSRF and setting the session creation policy to STATELESS.
• The Custom Filter is Key: The JwtAuthenticationFilter (extending OncePerRequestFilter) is the central component that intercepts requests, extracts the JWT, and validates it.
• SecurityContextHolder: The primary goal of the filter upon successful token validation is to create a UsernamePasswordAuthenticationToken and set it in the SecurityContextHolder. This is how you integrate with the rest of Spring Security.
• Filter Order Matters: You must add your custom filter at the correct position in the filter chain, typically before UsernamePasswordAuthenticationFilter, using addFilterBefore.
• Supporting Beans: A complete solution requires supporting components like JwtEncoder, JwtDecoder, and a service to encapsulate token logic, often backed by RSA keys for security.

Preview of the Next Lesson:
With our authentication mechanism in place, the server now knows who the user is. The next logical step is to control what the user can do. In the next lesson, "Implement method-level security using @PreAuthorize", we will leverage the authorities (roles) embedded in our JWT to enforce fine-grained access control on specific service methods.