🛡️ “Behind the Scenes of Spring Security: Mastering SecurityFilterChain Like a Pro”

🛡️ Behind the Scenes of Spring Security: Mastering SecurityFilterChain Like a Pro

Spring Security has evolved — the old WebSecurityConfigurerAdapter is gone, and the new SecurityFilterChain is now the backbone of Spring Boot security configuration.

If you’ve ever wondered what happens behind the curtain when a request hits your secure API, or how filters decide whether to allow or deny access — this guide is for you. 🚀

Let’s break down what SecurityFilterChain really is, why it replaced the old approach, and how to configure it the right way.

🔍 What Is a SecurityFilterChain?

Think of it as a sequence of filters that inspect and process every incoming HTTP request before it reaches your controllers.

Each filter has one job:

• Authenticate users 🧑‍💻
• Check permissions 🔐
• Handle CSRF tokens 🧾
• Redirect or deny unauthorized access 🚫

Together, these filters form a chain — the SecurityFilterChain.

In short:

🔗 Every request goes through the chain, and each filter decides what happens next.

⚙️ Why WebSecurityConfigurerAdapter Was Replaced

Before Spring Security 5.7, we used this pattern 👇

@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
@Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
            .antMatchers("/public/**").permitAll()
            .anyRequest().authenticated()
            .and()
            .formLogin();
    }
}

That worked fine — but it was:

• Hard to test (tight coupling)
• Not modular
• Verbally heavy

Now, the modern Spring Security style uses beans instead. 💡

🧩 The New Way — Defining SecurityFilterChain as a Bean

Here’s the new (and preferred) approach 👇

@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable()) // disable CSRF for simplicity
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/public/**").permitAll() // public APIs
                .requestMatchers("/admin/**").hasRole("ADMIN") // restricted APIs
                .anyRequest().authenticated() // everything else
            )
            .formLogin(Customizer.withDefaults()) // enable form login
            .httpBasic(Customizer.withDefaults()); // enable basic auth
        return http.build();
    }
}

✅ Advantages:

• Uses modern functional style
• Supports multiple filter chains
• Easier to maintain and test

🧠 How It Works Internally

When you start your Spring Boot app:

1. Spring Security creates a filter chain proxy (FilterChainProxy).
2. Each request is checked against a list of configured SecurityFilterChains.
3. The first chain that matches handles the request.
4. Filters execute in order (e.g., CORS → CSRF → Authentication → Authorization).

If no chain matches, the request is processed as unsecured (open endpoint).

💡 You can have multiple SecurityFilterChain beans, each handling a different path.

🔐 Example: Multiple SecurityFilterChains

Let’s say you want different rules for /api/** and /admin/**.

@Configuration
@EnableWebSecurity
public class MultiSecurityConfig {@Bean
    @Order(1)
    public SecurityFilterChain adminChain(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/admin/**")
            .authorizeHttpRequests(auth -> auth
                .anyRequest().hasRole("ADMIN")
            )
            .formLogin(Customizer.withDefaults());
        return http.build();
    }
    @Bean
    @Order(2)
    public SecurityFilterChain apiChain(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/api/**")
            .authorizeHttpRequests(auth -> auth
                .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

✅ Each SecurityFilterChain applies only to matching URLs. 🧠 Order matters — Spring picks the first matching chain.

🧾 Adding a Custom Filter

Want to add your own logic (e.g., logging or token validation)? You can easily inject a custom filter into the chain.

@Component
public class RequestLoggingFilter extends OncePerRequestFilter {
@Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain)
                                    throws ServletException, IOException {
        System.out.println("🔍 Incoming request: " + request.getRequestURI());
        filterChain.doFilter(request, response);
    }
}

Then, plug it into your chain:

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        .addFilterBefore(new RequestLoggingFilter(), UsernamePasswordAuthenticationFilter.class)
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .httpBasic(Customizer.withDefaults());
    return http.build();
}

✅ Your custom filter executes before authentication. Perfect for request logging, rate limiting, or custom headers.

🧩 Bonus Tip: Testing Your Security Config

You can write quick tests using Spring’s MockMvc to ensure your security behaves correctly.

@SpringBootTest
@AutoConfigureMockMvc
class SecurityTests {
@Autowired
    private MockMvc mockMvc;
    @Test
    void whenAccessPublic_thenOk() throws Exception {
        mockMvc.perform(get("/public/hello"))
                .andExpect(status().isOk());
    }
    @Test
    void whenAccessAdminWithoutAuth_thenUnauthorized() throws Exception {
        mockMvc.perform(get("/admin/panel"))
                .andExpect(status().isUnauthorized());
    }
}

✅ Helps you confirm that your SecurityFilterChain behaves as expected.

🔮 The Future of Spring Security Config

Spring Security’s move to SecurityFilterChain is part of a functional, declarative trend:

• Less boilerplate 🧱
• More composable configurations
• Easier testing & multiple chain support

If you’ve been using WebSecurityConfigurerAdapter, it’s time to embrace the future — cleaner, leaner, and more powerful.

🏁 TL;DR — Key Takeaways

💬 Final Thought

Spring Security isn’t just a firewall — it’s a framework built around filter orchestration. Once you understand SecurityFilterChain, you understand how every request in your app is secured.

“Security isn’t a plugin — it’s a mindset. 🔐”

A message from our Founder

Hey, Sunil here. I wanted to take a moment to thank you for reading until the end and for being a part of this community.

Did you know that our team run these publications as a volunteer effort to over 3.5m monthly readers? We don’t receive any funding, we do this to support the community. ❤️

If you want to show some love, please take a moment to follow me on LinkedIn, TikTok, **Instagram. You can also subscribe to our [weekly newsletter](https://newsletter.plainenglish.io/)**.

And before you go, don’t forget to clap and follow the writer️!