Spring Boot Security Basics: Architecture and Implementation

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();
    }
}

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);
    }
}

Frequently Asked Questions