Filter Chain Architecture

It's a filter that catches two security exceptions thrown further down the chain — AuthenticationException (not logged in) and AccessDeniedException (logged in but not allowed) — and turns them into an HTTP response instead of an error page.

FilterChainProxy is the single servlet filter Spring Security registers. For each request it picks the first matching SecurityFilterChain and runs that chain's security filters in order.

Spring Security is a chain of servlet filters run in a fixed order. Each filter does one job (load context, check CSRF, authenticate, authorize). Order matters because later filters depend on what earlier ones set up — e.g. you must load the user before checking permissions.

You write a method annotated with @Bean that takes an HttpSecurity object, configures the rules on it, and returns http.build(), which produces a SecurityFilterChain. Spring registers it to secure your HTTP requests.

SecurityContextHolder is a static holder that stores the SecurityContext for the current request/thread. Inside it lives an Authentication object describing who is logged in. You read it via SecurityContextHolder.getContext().getAuthentication().

DelegatingFilterProxy is the container-registered bridge that forwards to a Spring bean. FilterChainProxy is that bean — the Spring-managed filter that holds the security filter chains and runs the ordered security filters.

An AuthenticationEntryPoint decides how to ask an unauthenticated user to log in. A browser app usually redirects to a login page (302); a REST API usually returns 401 Unauthorized instead of redirecting.

It iterates its ordered list of SecurityFilterChains and calls each chain's matches(request), which uses a RequestMatcher. The first chain that matches is used; the rest are ignored.

Order: SecurityContextHolderFilter loads the current user; CsrfFilter checks the CSRF token; UsernamePasswordAuthenticationFilter authenticates form logins; ExceptionTranslationFilter catches security errors from below it; AuthorizationFilter (last) decides if the user may access the resource.

The Lambda DSL configures each area by passing a lambda (a Customizer) into methods like authorizeHttpRequests(auth -> ...). It groups related settings clearly and avoids the ambiguous .and() chaining of the old style, which is now deprecated.

MODE_THREADLOCAL (default) stores the SecurityContext per-thread, so child threads don't see it. MODE_INHERITABLETHREADLOCAL uses an InheritableThreadLocal so a thread you spawn inherits the parent's context. The risk: with pooled threads inheritance is unreliable and can leak stale identities.

It checks the current authentication. If the user is only anonymous or remembered (remember-me), it treats the denial as 'not really logged in' and calls the AuthenticationEntryPoint (prompt to log in). If the user is fully authenticated, it delegates to the AccessDeniedHandler (403).

Wrap the task or executor with Spring's delegating helpers: DelegatingSecurityContextRunnable / Callable for a single task, or DelegatingSecurityContextExecutor / DelegatingSecurityContextAsyncTaskExecutor for @Async. They capture the caller's context at submit time and install it on the worker thread for that task.

In Boot, SecurityFilterAutoConfiguration registers a DelegatingFilterProxyRegistrationBean pointing at the springSecurityFilterChain bean. Without Boot you register it via web.xml or AbstractSecurityWebApplicationInitializer with the same bean name and a /* mapping.

It uses AnyRequestMatcher, so the chain matches every request. That makes it a catch-all, which must be ordered last or it will shadow more specific chains.

authorizeHttpRequests defines authorization rules by matching request paths to access rules like permitAll() or authenticated(). Rules are evaluated top-to-bottom and the first match wins, so specific rules must come before broad ones like anyRequest().

The proxy is created by the container at startup but doesn't fetch its delegate bean until the first request, giving the Spring context time to initialize. By default it looks in the root WebApplicationContext.

ExceptionTranslationFilter is placed just before AuthorizationFilter. Because it only wraps the filters after it in a try/catch, the authorization filter's AccessDeniedException is thrown downstream and caught by it. If it came after, it couldn't catch that exception.

FilterChainProxy wraps the selected chain's filters in a VirtualFilterChain. Each filter calls chain.doFilter(...) to advance; after the last security filter, it delegates back to the container's original FilterChain to reach the controller.

They insert your custom filter relative to a known Spring Security filter. addFilterBefore(f, X) runs f before filter X; addFilterAfter(f, X) after X; addFilterAt(f, X) at X's position (order among same-position filters is undefined). Use them because you can't hand-number Spring's built-in filters.

CsrfFilter runs early so a forged, state-changing request is rejected before any authentication or business logic acts on it. If a custom filter that mutates state runs before CsrfFilter, it executes on requests that CSRF validation would have blocked — reintroducing the CSRF vulnerability.

Declare several SecurityFilterChain beans, each scoped with http.securityMatcher(...) to a URL subset, and order them with @Order. The FilterChainProxy tries them in order and the first chain whose matcher matches handles the request — only one chain runs per request.

SecurityContextHolderStrategy is the interface behind SecurityContextHolder that actually stores the context (ThreadLocal, inheritable, or global). Modern code injects/obtains it via SecurityContextHolder.getContextHolderStrategy() so the strategy can be swapped and mocked, instead of hardcoding static calls.

Before commencing the entry point, ExceptionTranslationFilter saves the current request in a RequestCache. After the user logs in, a SavedRequestAware success handler pulls that saved request out and redirects them back to where they were originally going.

Define two SecurityFilterChain beans: one with securityMatcher("/api/**"), stateless + JWT + CSRF off, ordered first; one catch-all with sessions + form login + CSRF, ordered last. Order matters because the first matching chain wins.

FilterChainProxy tries each SecurityFilterChain in bean order and uses the FIRST one whose request matcher matches — only that chain's filters run. So a broad or unordered chain declared first can shadow a more specific one. Order the beans with @Order and give each a securityMatcher.

Identity leaks come from stale ThreadLocal state on reused threads: forgetting to clear the context, or using MODE_INHERITABLETHREADLOCAL with a pool so a worker keeps a context from an earlier request. Fix it with per-task propagation (DelegatingSecurityContext*) and ensuring the context is always cleared after each unit of work.

Register a DelegatingFilterProxy pointing at your Spring-managed filter bean. The container manages the proxy while Spring injects and lifecycle-manages your real filter, so it gets dependencies and AOP even though the container owns filter registration.

permitAll() lets a request through but still runs the security filter chain (CSRF, headers, etc.). web.ignoring() (WebSecurityCustomizer) tells Spring to skip the entire chain for those paths. Prefer permitAll(); reserve ignoring() for truly static, security-irrelevant resources.