Spring Boot Security — Session Fixation via migrateSession

Spring Boot Security Basics is a core pillar of any production-grade Spring Boot application. It was designed to solve a specific, recurring problem: the repetitive and error-prone nature of implementing security logic manually across every endpoint.

Instead of scattering if statements to check user roles throughout your business logic, Spring Security uses a Security Filter Chain. This chain intercepts incoming requests before they ever reach your controllers, ensuring that security concerns are decoupled from your application code. That decoupling matters more than people realize early on — it means you can change your security model without touching your business logic, and your controllers stay focused on what they were actually written to do.

By utilizing the DelegatingFilterProxy, Spring bridges the gap between the Servlet container's lifecycle and Spring's ApplicationContext, allowing your security filters to be managed as standard Spring Beans. This article focuses on the modern Spring Security 6+ component-based configuration, deliberately stepping away from the deprecated WebSecurityConfigurerAdapter pattern. If you are still on that path, migrating is not optional — it is overdue.

What Is Spring Boot Security Basics and Why Does It Exist?

Spring Boot Security Basics exists because security is a cross-cutting concern — and cross-cutting concerns handled inline become unmanageable fast. Every time a developer writes an if (user.hasRole("ADMIN")) check inside a service method, they are making a bet that every other developer who touches that code will remember to replicate the same check elsewhere. That bet does not age well.

Spring Security's answer is the Security Filter Chain. Before any request reaches your @RestController or @Controller, it passes through an ordered series of filters. Each filter has a single responsibility: validate the CSRF token, extract and authenticate a bearer token, check session validity, enforce authorization rules. If a filter rejects the request, the chain short-circuits and your application code never executes.

This architecture gives you something genuinely valuable: your controllers can assume the request is legitimate. You do not write defensive role checks in service methods. You declare your security rules in one place, and the framework enforces them everywhere.

The DelegatingFilterProxy is the seam between the Servlet container world and the Spring world. The container knows nothing about Spring beans — it just knows about javax.servlet.Filter. DelegatingFilterProxy registers itself with the container as a standard filter, then delegates all actual work to FilterChainProxy, a Spring-managed bean that runs your configured SecurityFilterChain beans. That indirection is what makes Spring Security filters injectable, testable, and composable like any other Spring component.

package io.thecodeforge.security;

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.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;
import static org.springframework.security.config.Customizer.withDefaults;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    /**
     * io.thecodeforge: Standard Filter Chain Configuration
     *
     * Rule ordering is intentional and matters:
     *   1. Most specific path matchers come first.
     *   2. Broader matchers (anyRequest) always come last.
     *
     * Swapping that order causes Spring Security to apply the
     * broader rule first, silently locking out public endpoints.
     *
     * CSRF is disabled here because this config targets a
     * stateless REST API using token-based auth. Do NOT
     * disable CSRF for session-based web applications.
     */
    @Bean
    public SecurityFilterChain forgeSecurityFilterChain(HttpSecurity http) throws Exception {
        http
            // Stateless REST API: CSRF tokens are not needed because
            // we do not rely on browser session cookies for auth.
            .csrf(AbstractHttpConfigurer::disable)

            .authorizeHttpRequests(auth -> auth
                // Public endpoints — no authentication required
                .requestMatchers("/api/v1/public/**").permitAll()
                // Health and readiness probes should be accessible to infra
                .requestMatchers("/actuator/health", "/actuator/info").permitAll()
                // Admin endpoints require the ADMIN role (stored as ROLE_ADMIN)
                .requestMatchers("/api/v1/admin/**").hasRole("ADMIN")
                // Standard user endpoints — accessible to USER or ADMIN
                .requestMatchers("/api/v1/user/**").hasAnyRole("USER", "ADMIN")
                // Everything else must be authenticated; explicit is safer than implicit
                .anyRequest().authenticated()
            )

            // No server-side session state — tokens carry identity per request
            .sessionManagement(session -> session
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            )

            // HTTP Basic for simplicity; swap for JWT filter in production
            .httpBasic(withDefaults());

        return http.build();
    }
}

Spring Security Filter Chain — Order and Purpose of Built-in Filters

Spring Security's filter chain is not a random pile of filters — it is a carefully ordered pipeline where each filter has a single responsibility and executes in a strict sequence defined by FilterOrderRegistration. Understanding this order is not academic trivia; it determines whether your custom JWT filter runs before or after the session management filter, and whether your authorization rules are applied to the right set of requests.

The following diagram shows the default ordering of the key built-in filters in a typical SecurityFilterChain:

Filter Order (first to last): 1. DisableEncodeUrlFilter — prevent session ID in URLs (defense against session fixation via URL rewriting) 2. ForceEagerSessionCreationFilter — force session creation before authentication (used in some session-fixation scenarios) 3. ChannelProcessingFilter — enforce HTTPS redirect 4. WebAsyncManagerIntegrationFilter — integrate SecurityContext with async request processing 5. SecurityContextHolderFilter (or SecurityContextPersistenceFilter) — load/save SecurityContext from session 6. HeaderWriterFilter — add security headers (X-Content-Type-Options, X-Frame-Options, etc.) 7. CorsFilter — handle CORS preflight 8. CsrfFilter — validate CSRF token for state-changing requests 9. LogoutFilter — handle logout requests 10. OAuth2AuthorizationRequestRedirectFilter / OAuth2LoginAuthenticationFilter — OAuth2 login flows 11. UsernamePasswordAuthenticationFilter — form login authentication 12. DefaultLoginPageGeneratingFilter — generate login page if no custom page configured 13. DefaultLogoutPageGeneratingFilter — generate logout page 14. BasicAuthenticationFilter — HTTP Basic auth 15. RequestCacheAwareFilter — replay original request after authentication 16. SecurityContextHolderAwareRequestWrapper — wrap request to provide isUserInRole(), getUserPrincipal(), etc. 17. RememberMeAuthenticationFilter — handle remember-me cookies 18. AnonymousAuthenticationFilter — populate SecurityContext with anonymous token if no authentication present 19. SessionManagementFilter — detect session-fixation attacks, enforce concurrent session control 20. ExceptionTranslationFilter — translate security exceptions to HTTP responses (401/403) 21. AuthorizationFilter (formerly FilterSecurityInterceptor) — enforce access rules based on authorizeHttpRequests()

This order is by design — authentication filters (UsernamePasswordAuthenticationFilter, BasicAuthenticationFilter) run before the AuthorizationFilter so that the security context is populated before access decisions are made. Similarly, CsrfFilter runs before authentication filters because CSRF tokens are validated regardless of whether the user is authenticated.

When you add a custom filter, you must tell Spring where in this order it should be inserted. The most common insertion points are: - addFilterBefore(customFilter, UsernamePasswordAuthenticationFilter.class) — for JWT filters that need to run before form login - addFilterAfter(customFilter, BasicAuthenticationFilter.class) — for post-authentication processing - addFilterAt(customFilter, UsernamePasswordAuthenticationFilter.class) — replace a filter at that position (rare)

Misplacing a filter can have subtle consequences. For example, if you insert a JWT filter after ExceptionTranslationFilter, the AuthenticationEntryPoint (which redirects to login page) may override your 401 response.

package io.thecodeforge.security;

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.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;

@Configuration
@EnableWebSecurity
public class CustomFilterPlacementConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // Custom JWT filter runs BEFORE UsernamePasswordAuthenticationFilter
            .addFilterBefore(new JwtAuthenticationFilter(),
                             UsernamePasswordAuthenticationFilter.class)

            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**").permitAll()
                .anyRequest().authenticated()
            )
            .httpBasic();

        return http.build();
    }
}

Authentication vs Authorization: Understanding the Difference

Authentication and authorization are the two pillars of security, but they are frequently confused — even in production code. Authentication answers who you are (identity verification), while authorization answers what you can do (access permission).

The following comparison table clarifies the distinction and shows how each concept maps to Spring Security components:

In Spring Security, authentication is typically handled by filters like UsernamePasswordAuthenticationFilter or BasicAuthenticationFilter. They extract credentials, delegate to an AuthenticationProvider, and on success store an Authentication object in SecurityContextHolder. That object contains the principal (user identity) and the GrantedAuthority list.

Authorization is enforced later in the filter chain by AuthorizationFilter. It evaluates the request against the rules declared in authorizeHttpRequests() (URL-based) or via method-level annotations like @PreAuthorize (method-based).

The critical thing to understand: authorization never happens before authentication. If a request reaches the AuthorizationFilter without a valid Authentication in the SecurityContext, it will be rejected with a 401, not a 403. This is why the filter order matters — authentication filters must run before the authorization filter.

A common mistake is to confuse the two at the code level. Developers sometimes write hasAuthority('ROLE_USER') inside an AuthenticationProvider check, which conflates credential validation with role assignment. Keep authentication and authorization logic in separate layers.

package io.thecodeforge.security;

import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AuthController {

    @GetMapping("/whoami")
    public String whoAmI() {
        // Authentication object from SecurityContext
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        if (auth == null || !auth.isAuthenticated()) {
            return "Not authenticated";
        }
        // principal provides identity (authentication)
        String username = auth.getName();
        // authorities define what user can do (authorization)
        java.util.Collection<?> authorities = auth.getAuthorities();
        return "Authenticated as: " + username + ", authorities: " + authorities;
    }
}

Authentication Methods Comparison: Form Login, HTTP Basic, JWT, OAuth2

Choosing the right authentication method for your Spring Boot application depends on your architecture, client type, and security requirements. Each method has different trade-offs in terms of session management, statefulness, and use-case fit.

The table below compares the four most common approaches:

The choice often comes down to this: if you control both the client and server (e.g., a full-stack web app), form login is straightforward and battle-tested. If you are building a JSON API consumed by a SPA or mobile app, JWT with a stateless session policy is the standard. If you need to integrate with Google, GitHub, or enterprise SAML, OAuth2 is the only sane option.

A common anti-pattern is mixing stateful and stateless approaches without careful segregation. For example, having a session-based form login for the admin panel and JWT for the public API works — but you must ensure the filter chains are properly scoped so that session cookies don't interfere with token-based requests.

package io.thecodeforge.security;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;
import static org.springframework.security.config.Customizer.withDefaults;

@Configuration
public class MultipleAuthConfig {

    // Chain for public API endpoints — stateless, JWT
    @Bean
    @Order(1)
    public SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/api/**")
            .csrf(csrf -> csrf.disable())
            .sessionManagement(session -> session
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .addFilterBefore(new JwtAuthenticationFilter(),
                             UsernamePasswordAuthenticationFilter.class)
            .authorizeHttpRequests(auth -> auth
                .anyRequest().authenticated()
            );
        return http.build();
    }

    // Chain for admin web UI — session-based, form login
    @Bean
    @Order(2)
    public SecurityFilterChain adminFilterChain(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/admin/**")
            .csrf(csrf -> csrf.ignoringRequestMatchers("/admin/api/**"))  // partial stateless
            .sessionManagement(session -> session
                .sessionCreationPolicy(SessionCreationPolicy.IF_REQUIRED))
            .formLogin(withDefaults())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/admin/public/**").permitAll()
                .anyRequest().hasRole("ADMIN")
            );
        return http.build();
    }
}

Advantages and Disadvantages of Spring Boot Security

Spring Security is the most widely used security framework for Java applications, but it's not a silver bullet. Understanding its strengths and weaknesses helps you make informed architectural decisions and avoid common pitfalls.

Advantages:

Disadvantages:

The key takeaway: Spring Security is excellent at what it does — providing a comprehensive, extensible security framework — but it expects you to understand its architecture. The disadvantages primarily stem from misuse or underestimating the learning curve.

For most Spring Boot applications, the advantages far outweigh the disadvantages, especially once you invest the time to understand the filter chain model. The alternative — rolling your own security — almost always results in worse security and higher maintenance cost.

5 Practice Projects to Master Spring Security

Theory is necessary, but building real projects is how you internalize Spring Security's concepts. These five practice projects are ordered from beginner to advanced and cover the most common production scenarios.

1. Role-Based Access Control (RBAC) with Multiple User Types Build a web application with three user roles: USER, MODERATOR, and ADMIN. Implement endpoints that are accessible only to specific roles. Use an in-memory or database-backed UserDetailsService with BCryptPasswordEncoder. Configure authorizeHttpRequests() to enforce role-based access. What you'll learn: Request matcher ordering, role hierarchy, and the difference between hasRole() and hasAuthority(). Production relevance: Most enterprise applications require role-based permissions.

2. Method Security with @PreAuthorize Extend the RBAC project by adding method-level security using @EnableMethodSecurity and @PreAuthorize. For example, a bank transfer method should only be callable by users with AUTHORIZED_SIGNER permission. What you'll learn: How method security works with AOP, SpEL expressions, and how it complements URL-based security. Production relevance: Method security is essential for fine-grained access control in service layers.

3. Multi-Factor Authentication (MFA) with Time-Based One-Time Password (TOTP) Add a second factor to a Spring Security form login. After password authentication, redirect the user to an MFA challenge page that expects a 6-digit TOTP code (like Google Authenticator). Use a custom AuthenticationProvider that verifies both the password and the TOTP. What you'll learn: How to chain authentication providers, store and validate TOTP secrets, and handle partial authentication states. Production relevance: MFA is becoming mandatory for sensitive applications.

4. Stateless REST API with JWT and Refresh Tokens Build a REST API that authenticates with username/password and returns a short-lived access token (JWT) plus a long-lived refresh token. Implement a custom filter that validates the JWT on every request. Use the refresh token endpoint to issue new access tokens. What you'll learn: Custom filter placement, token generation and validation, stateless session policy, and refresh token rotation. Production relevance: This is the foundational pattern for most modern APIs.

5. OAuth2 Social Login with Google/GitHub and Custom User Registration Configure Spring Security's OAuth2 client to allow login via Google or GitHub. After a successful OAuth2 authentication, capture the user's email and store them in a local database, possibly prompting for additional details on first login. Use @AuthenticationPrincipal to retrieve the user in controllers. What you'll learn: OAuth2 login flow, OAuth2UserService customization, mapping external principals to local users, and handling multiple authentication providers (OAuth2 + form login). Production relevance: Social login is ubiquitous in consumer-facing applications.

package io.thecodeforge.service;

import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.stereotype.Service;

@Service
public class TransferService {

    /**
     * Only users with AUTHORIZED_SIGNER permission can execute transfers.
     * The method will throw AccessDeniedException if the caller lacks this authority.
     */
    @PreAuthorize("hasPermission(#accountId, 'TRANSFER')")
    public void transferFunds(Long accountId, double amount) {
        // business logic
    }
}

Common Mistakes and How to Avoid Them

Most Spring Security issues in production trace back to one of five mistakes. Understanding them up front saves a disproportionate amount of debugging time later.

1. Disabling CSRF globally without understanding what it protects. CSRF protection exists specifically for session-cookie-based authentication. If your application uses JWTs or OAuth2 tokens sent in the Authorization header, CSRF is genuinely unnecessary for those endpoints — tokens provide request authenticity that cookies cannot. The mistake is applying .csrf(AbstractHttpConfigurer::disable) to an application that also uses session cookies somewhere, usually for an admin panel or a legacy flow that did not get migrated. The safe approach is to scope the disable to specific request matchers using csrf.ignoringRequestMatchers("/api/**") and leave protection active everywhere else.

2. Misordering request matchers. Spring Security evaluates matchers in the order they are declared and stops at the first match. A rule like anyRequest().authenticated() placed before .requestMatchers("/api/v1/public/**").permitAll() means the broader rule matches every request first and the permit-all rule never fires. The fix is simple but requires discipline: always order from most specific to least specific, and add a comment explaining why the order is intentional.

3. Not encoding passwords — or encoding them inconsistently. This is more subtle than it sounds. The failure mode is not always an error at startup — sometimes it is a silent mismatch at login time that sends every user to the login page with no explanation. The root cause is usually a PasswordEncoder bean that was defined in one configuration class but a different hardcoded encoder being used in a migration script or a test fixture. Treat your PasswordEncoder bean as a singleton used in exactly one place for encoding and one place for verification.

4. Using WebSecurityConfigurerAdapter in Spring Security 6+. This class was deprecated in Spring Security 5.7 and removed entirely in 6.0. If you are on Spring Boot 3.x and still extending it, your application will not compile. The migration path is to declare SecurityFilterChain beans instead of overriding configure(HttpSecurity http). The resulting configuration is more readable and easier to test.

5. Not handling authentication and authorization exceptions explicitly. The default behavior when security blocks a request is to redirect to a login page or return a generic HTML error page. For a REST API, that is wrong on both counts. Clients expecting JSON get HTML, and error pages often include stack traces or framework version information. Define a custom AuthenticationEntryPoint that returns a structured 401 JSON body, and a custom AccessDeniedHandler that returns a structured 403 JSON body. This takes twenty minutes and prevents an entire category of information disclosure.

package io.thecodeforge.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;

@Configuration
public class PasswordConfig {

    /**
     * io.thecodeforge: Password encoding strategy.
     *
     * WHY BCrypt:
     *   - Adaptive: work factor increases as hardware improves
     *   - Built-in per-password salt: no rainbow table attacks
     *   - Intentionally slow: ~250ms at strength 12 on modern hardware
     *
     * WHY NOT MD5 or SHA-256:
     *   - They are fast — GPUs can compute billions per second
     *   - Fast hashing is a liability for passwords, not a feature
     *   - Neither includes a salt by design
     *
     * STRENGTH FACTOR GUIDANCE:
     *   - 10: ~100ms — acceptable minimum for most apps
     *   - 12: ~250ms — recommended for login endpoints
     *   - 14: ~1000ms — appropriate only if login volume is very low
     *
     * IMPORTANT: BCrypt silently truncates input beyond 72 bytes.
     * Validate password length at the controller/service layer
     * before this encoder ever sees the value.
     */
    @Bean
    public PasswordEncoder forgePasswordEncoder() {
        return new BCryptPasswordEncoder(12);
    }
}

The SecurityContext — Your App's Truth About Who's Asking

Every authenticated request deposits a SecurityContext into a ThreadLocal. That object holds the Authentication — the principal (who), the credentials (proof), and the granted authorities (what they can do). If you blindly trust that context without verifying it came through the filter chain, you're one FilterOrderRegistration bug away from privilege escalation. The SecurityContext is set by the SecurityContextPersistenceFilter before your controllers run, and it's cleared after the response commits. Never stash it in a static field or a session scoped bean. Always extract via SecurityContextHolder.getContext().getAuthentication(). If you call that from a background thread, it's null — pass the context explicitly or switch to DelegatingSecurityContextRunnable. This is why async methods break your @PreAuthorize annotations: the child thread has no auth context.

// io.thecodeforge
@Service
public class SecurityContextExtractor {

    // NEVER do this
    public String getUsernameFromStatic() {
        return SecurityContextHolder.getContext()
                .getAuthentication().getName();
    }

    // DO this — works only on the request thread
    public String getCurrentUser() {
        Authentication auth = SecurityContextHolder.getContext()
                .getAuthentication();
        if (auth == null || !auth.isAuthenticated()) {
            throw new IllegalStateException("No authenticated principal");
        }
        return auth.getName();
    }

    // For async: pass the context explicitly
    @Async
    public void processAsync(Authentication auth) {
        SecurityContextHolder.getContext().setAuthentication(auth);
        try {
            // business logic
        } finally {
            SecurityContextHolder.clearContext();
        }
    }
}

CSRF Protection: Why Your REST API Probably Doesn't Need It

CSRF (Cross-Site Request Forgery) exploits the fact that browsers automatically attach cookies to every request to a domain. If your app uses cookie-based authentication — form login or JSESSIONID — an attacker can trick a logged-in user into submitting a malicious request. Spring Security enables CSRF protection by default for any state-changing endpoint (POST, PUT, DELETE). For a server-rendered Thymeleaf app, that's correct. For a REST API that uses Bearer tokens (JWT, OAuth2), it's noise. The token isn't sent automatically by the browser — it's in the Authorization header, which JavaScript must explicitly attach. So if you're building a SPA with Angular/React that sends JWT, disable CSRF. Otherwise every POST to your API throws a 403 Forbidden. That wasted four hours debugging is a rite of passage. Save yourself.

// io.thecodeforge
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // REST API with JWT — no CSRF needed
            .csrf(csrf -> csrf.disable())
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/api/auth/**").permitAll()
                .anyRequest().authenticated()
            )
            .sessionManagement(session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(Customizer.withDefaults())
            );
        return http.build();
    }
}