Spring Security Architecture: Filter Chain Explained

Introduction

Authentication and authorization

• Authentication: who is making this request? The caller proves an identity, with a password, a token, a certificate or a login session.
• Authorization: is this caller allowed to do this? Only after we know who the caller is can we decide, for example, that only administrators may read /admin/stats.

Security as a chain of filters

• DelegatingFilterProxy: a plain servlet filter registered with Tomcat. The servlet container knows nothing about Spring beans, so this filter's only job is to hand each request over to a Spring bean.
• FilterChainProxy: that bean, named springSecurityFilterChain. An application can have several security configurations, for example one for /api/** and one for the web pages. FilterChainProxy picks the first chain whose request matcher matches the request, and runs only that one.
• SecurityFilterChain: an ordered list of security filters, each with one job. Their order matters: the user must be authenticated before the authorization filter can check what that user may do.

The example

//BookController.java
package com.javabrahman.security.arch;

import java.util.List;
import java.util.Map;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class BookController {

  @GetMapping("/public/hello")
  public String hello() {
    return "Hello, anyone";
  }

  @GetMapping("/api/books")
  public List<String> books() {
    return List.of("Effective Java", "Clean Code");
  }

  @GetMapping("/api/me")
  public Map<String, Object> me() {
    Authentication auth = SecurityContextHolder.getContext().getAuthentication();
    return Map.of(
        "name", auth.getName(),
        "authorities", auth.getAuthorities().stream().map(GrantedAuthority::getAuthority).sorted().toList(),
        "authenticationType", auth.getClass().getSimpleName(),
        "thread", Thread.currentThread().getName().replaceAll("\\d+$", "N"));
  }

  @GetMapping("/admin/stats")
  public Map<String, Integer> stats() {
    return Map.of("books", 2);
  }
}

//SecurityConfig.java
package com.javabrahman.security.arch;

import static org.springframework.security.config.Customizer.withDefaults;

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.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

  @Bean
  SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/public/**").permitAll()
            .requestMatchers("/admin/**").hasRole("ADMIN")
            .anyRequest().authenticated())
        .httpBasic(withDefaults())
        .formLogin(withDefaults());
    return http.build();
  }

  @Bean
  UserDetailsService users() {
    return new InMemoryUserDetailsManager(
        User.withUsername("ann").password("{noop}ann-pass").roles("USER").build(),
        User.withUsername("raj").password("{noop}raj-pass").roles("USER", "ADMIN").build());
  }
}

//SecurityApp.java
package com.javabrahman.security.arch;

import java.util.Arrays;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.Bean;
import org.springframework.security.web.FilterChainProxy;

@SpringBootApplication
public class SecurityApp {

  // Started with the argument "list-filters", prints every security filter chain and its filters, then stops
  @Bean
  CommandLineRunner listFilters(FilterChainProxy proxy, ApplicationContext context) {
    return args -> {
      if (!Arrays.asList(args).contains("list-filters")) {
        return;
      }
      proxy.getFilterChains().forEach(chain -> {
        System.out.println("Security filter chain: " + chain.getClass().getSimpleName());
        chain.getFilters().forEach(f -> System.out.println("   " + f.getClass().getSimpleName()));
      });
      System.exit(SpringApplication.exit(context));
    };
  }

  public static void main(String[] args) {
    SpringApplication.run(SecurityApp.class, args);
  }
}

Security filter chain: DefaultSecurityFilterChain
   DisableEncodeUrlFilter
   WebAsyncManagerIntegrationFilter
   SecurityContextHolderFilter
   HeaderWriterFilter
   CsrfFilter
   LogoutFilter
   UsernamePasswordAuthenticationFilter
   DefaultResourcesFilter
   DefaultLoginPageGeneratingFilter
   DefaultLogoutPageGeneratingFilter
   BasicAuthenticationFilter
   RequestCacheAwareFilter
   SecurityContextHolderAwareRequestFilter
   AnonymousAuthenticationFilter
   ExceptionTranslationFilter
   AuthorizationFilter

Explanation of the filter list

• Housekeeping: DisableEncodeUrlFilter stops session ids from being written into URLs, WebAsyncManagerIntegrationFilter makes the security context available to asynchronous requests, and SecurityContextHolderFilter loads the security context of this request, for example from the HTTP session after a form login.
• Protection: HeaderWriterFilter adds security headers to every response, and CsrfFilter checks CSRF tokens on requests that change data.
• Logging in and out: LogoutFilter handles logout. UsernamePasswordAuthenticationFilter, DefaultResourcesFilter, DefaultLoginPageGeneratingFilter and DefaultLogoutPageGeneratingFilter come from formLogin(): they process the login form and generate a simple login and logout page with its styles. BasicAuthenticationFilter comes from httpBasic().
• After authentication: RequestCacheAwareFilter resumes a request that was interrupted by a login, SecurityContextHolderAwareRequestFilter makes servlet methods such as request.isUserInRole() work, and AnonymousAuthenticationFilter sets an anonymous user if nobody authenticated, so that later filters always find someone.
• The decision: AuthorizationFilter, last, checks the rules. ExceptionTranslationFilter, just before it, catches its refusal and turns it into the right response.

How authentication works

• Authentication: the object that represents a user, before and after login. Before, it holds the credentials the caller sent. After, it holds the user's name and authorities (roles and permissions), and is marked authenticated.
• AuthenticationManager: the one entry point, authenticate(Authentication). Its usual implementation, ProviderManager, holds a list of AuthenticationProviders and passes the request to the first one that supports this kind of Authentication: one for passwords, another for tokens, another for LDAP.
• DaoAuthenticationProvider: the provider for usernames and passwords. It loads the user from a UserDetailsService, and checks the password with a PasswordEncoder.
• SecurityContextHolder: where the authenticated user is kept for the rest of the request. By default it is bound to the current thread, so that any code running for this request can ask who the user is.

How authorization decides

The requests

> curl -i http://localhost:8080/public/hello
HTTP/1.1 200
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Pragma: no-cache
X-Frame-Options: DENY
Cache-Control: no-store, must-revalidate, no-cache, max-age=0
Content-Length: 13
Content-Type: text/plain; charset=UTF-8
Expires: 0

Hello, anyone

> curl -i http://localhost:8080/api/books
HTTP/1.1 401
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Pragma: no-cache
X-Frame-Options: DENY
Cache-Control: no-store, must-revalidate, no-cache, max-age=0
Set-Cookie: JSESSIONID=2400A42FAD110FC728B4BE0A22E4743C; Path=/; HttpOnly
WWW-Authenticate: Basic realm="Realm", charset="UTF-8"
Content-Length: 0
Expires: 0

> curl -i http://localhost:8080/api/books -H "Authorization: Basic YW5uOmFubi1wYXNz"
HTTP/1.1 200
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Pragma: no-cache
X-Frame-Options: DENY
Cache-Control: no-store, must-revalidate, no-cache, max-age=0
Content-Length: 31
Content-Type: application/json
Expires: 0

["Effective Java","Clean Code"]

> curl -i http://localhost:8080/api/books -H "Authorization: Basic YW5uOndyb25n"
HTTP/1.1 401
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Pragma: no-cache
X-Frame-Options: DENY
Cache-Control: no-store, must-revalidate, no-cache, max-age=0
Set-Cookie: JSESSIONID=7ED1AFD935EBC362B517FDB4A2668797; Path=/; HttpOnly
WWW-Authenticate: Basic realm="Realm", charset="UTF-8"
Content-Length: 0
Expires: 0

> curl -i http://localhost:8080/api/me -H "Authorization: Basic YW5uOmFubi1wYXNz"
HTTP/1.1 200
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Pragma: no-cache
X-Frame-Options: DENY
Cache-Control: no-store, must-revalidate, no-cache, max-age=0
Content-Length: 151
Content-Type: application/json
Expires: 0

{"thread":"http-nio-8080-exec-N","authorities":["FACTOR_PASSWORD","ROLE_USER"],"authenticationType":"UsernamePasswordAuthenticationToken","name":"ann"}

> curl -i http://localhost:8080/admin/stats -H "Authorization: Basic YW5uOmFubi1wYXNz"
HTTP/1.1 403
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Pragma: no-cache
X-Frame-Options: DENY
Cache-Control: no-store, must-revalidate, no-cache, max-age=0
Content-Type: application/json
Expires: 0

{"timestamp":"2026-11-06T17:46:58.425Z","status":403,"error":"Forbidden","path":"/admin/stats"}

> curl -i http://localhost:8080/admin/stats -H "Authorization: Basic cmFqOnJhai1wYXNz"
HTTP/1.1 200
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Pragma: no-cache
X-Frame-Options: DENY
Cache-Control: no-store, must-revalidate, no-cache, max-age=0
Content-Length: 11
Content-Type: application/json
Expires: 0

{"books":2}

> curl -i http://localhost:8080/api/books -H "Accept: text/html"
HTTP/1.1 302
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Pragma: no-cache
X-Frame-Options: DENY
Cache-Control: no-store, must-revalidate, no-cache, max-age=0
Location: http://localhost:8080/login
Set-Cookie: JSESSIONID=EB8BB5A8BAD929C18836B1219EA04267; Path=/; HttpOnly
Content-Length: 0
Expires: 0

Explanation of the responses

• Security headers on every response, even the public one: X-Content-Type-Options: nosniff, X-Frame-Options: DENY against clickjacking, and Cache-Control: no-store with Pragma and Expires, so that browsers and proxies do not cache possibly private responses. These come from HeaderWriterFilter.
• /public/hello without credentials: 200. The anonymous user passed the permitAll() rule.
• /api/books without credentials: 401, with WWW-Authenticate: Basic realm="Realm" telling the client how to authenticate. The anonymous user was refused, so the entry point of HTTP Basic answered. The response also sets a JSESSIONID cookie: Spring Security saved the refused request in a new session, to resume it after a login.
• With ann's password: 200 and the books. With a wrong password: 401 again. The DaoAuthenticationProvider rejected it at the password check, and the controller never ran.
• /api/me shows what the controller can see in the SecurityContextHolder: the name ann, an Authentication of type UsernamePasswordAuthenticationToken, and two authorities. ROLE_USER comes from roles("USER"), which adds the ROLE_ prefix. FACTOR_PASSWORD is added by Spring Security 7 to record how the user authenticated - with a password - for its multi-factor authentication support. The request ran on a Tomcat worker thread, which is where the thread-bound context lives.
• /admin/stats as ann: 403. Ann is authenticated, but lacks the role ADMIN, so the access-denied handler answered; the JSON body is Spring Boot's standard error response. As raj, who has both roles: 200.
• The browser-like request, with Accept: text/html and no credentials: 302 to /login. Two entry points are configured, form login and HTTP Basic, and Spring Security chose by the kind of client: a browser is sent to the login page, a program gets a 401.

What Spring Boot adds

Summary