Filter Chains and Security Contexts

The Servlet Filter chain is a foundational security and processing layer in the web tier of LogisticsCore, serving as the mandatory entry point for all HTTP traffic. Its correct configuration is non-negotiable for maintaining application integrity, authentication consistency, and auditability. This document details the mechanics of filter execution, the propagation of security state, and the JVM-level implications of ThreadLocal usage—prerequisites for secure, observable, and maintainable web applications.

Introduction to Servlet Filters

Servlet Filters are part of the Java Servlet API specification [1], designed to intercept requests and responses before they reach the target resource. They operate within the Servlet container’s native lifecycle, which manages filter instantiation, initialization via init(), request processing via doFilter(), and destruction via destroy(). This lifecycle is container-controlled and independent of any application framework.

In LogisticsCore, filters enforce cross-cutting concerns including request tracing, CORS policy enforcement, and security context initialization. Their execution order directly determines the application’s security posture: a misordered filter can expose unprotected endpoints or block legitimate preflight requests.

DelegatingFilterProxy: Bridging Servlet and Spring Contexts

To integrate Spring-managed components into the container-managed filter chain, Spring provides DelegatingFilterProxy, implemented using JDK Dynamic Proxies. This proxy is registered with the Servlet container as a standard Filter, but delegates actual processing to a Spring-managed bean by name (e.g., springSecurityFilterChain).

The proxy resolves the target bean from the ApplicationContext, enabling dependency injection, configuration via @Configuration classes, and lifecycle management by Spring. Without this bridge, Spring Security filters could not leverage framework services such as AuthenticationManager injection or @Value-driven property binding.

This mechanism decouples the Servlet container’s static registration model from Spring’s dynamic component model. Programmatic equivalent:

// Equivalent programmatic filter registration with Spring lookup
Dynamic filterRegistration = servletContext.addFilter("delegatingProxy",
    (request, response, chain) -> {
        Filter delegate = applicationContext.getBean("targetFilterBean", Filter.class);
        delegate.doFilter(request, response, chain);
    });

SecurityContextHolder and SecurityContext

The SecurityContextHolder is the central store for the SecurityContext, which encapsulates the authenticated principal, credentials, and authorization authorities for the current execution thread. By default, it uses a ThreadLocal strategy—SecurityContextHolder.MODE_THREADLOCAL—to bind the context to the current thread.

ThreadLocal and SecurityContextHolder

ThreadLocal is a JVM mechanism that provides thread-isolated storage. Each thread holds a private copy of the variable, preventing interference across concurrent requests. In LogisticsCore, this ensures that User A’s SecurityContext cannot be accidentally accessed during User B’s request on a different thread.

However, this isolation breaks down during asynchronous processing. When a request spawns a new thread (e.g., via @Async, CompletableFuture, or virtual threads), the new thread does not inherit the parent’s ThreadLocal values. Consequently, SecurityContextHolder.getContext() returns null unless explicitly propagated.

This is not a Spring limitation but a consequence of JVM semantics: ThreadLocal is not automatically inherited across thread boundaries unless the InheritableThreadLocal variant is used.

Filter Chain Ordering and Security

Filter order is a security invariant. The sequence determines which components can observe or modify the request before authentication, and which require an established SecurityContext.

• Filters that must run before authentication (e.g., CORS, tracing) must precede security filters.
• Filters that depend on authentication state (e.g., authorization, audit logging) must follow.

Failure to enforce this ordering results in unhandled preflight requests, missing correlation IDs in logs, or NullPointerException on SecurityContextHolder.getContext().getAuthentication().

CorsFilter and Its Placement

The CorsFilter must be among the first filters in the chain. It handles OPTIONS preflight requests, which are unauthenticated by design. If placed after UsernamePasswordAuthenticationFilter, preflight requests will be rejected due to missing credentials, violating CORS protocol [1].

Moreover, error responses (e.g., 401 Unauthorized) must include CORS headers to allow proper client-side handling. Only a pre-authentication CorsFilter can ensure this.

Correct placement in LogisticsCore:

@Order(Ordered.HIGHEST_PRECEDENCE + 10) // After tracing, before security
@Component
public class CorsFilter implements Filter { ... }

Implementing Custom Filters

Custom filters must be designed with thread-safety, ordering, and context propagation in mind. They operate within the same JVM and Spring constraints as framework-provided filters.

Example: Request Tracing Filter

The following filter implements request tracing using MDC (Mapped Diagnostic Context) and Java 21+ syntax, compatible with virtual threads:

// Example: Custom Filter for Request Tracing with MDC (Java 21+)
package com.logistics.core.filter;

import jakarta.servlet.*;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import java.io.IOException;
import java.util.UUID;

@Component
@Order(Ordered.HIGHEST_PRECEDENCE) // Earliest possible execution
public class RequestTracingFilter implements Filter {
    private static final Logger LOG = LoggerFactory.getLogger(RequestTracingFilter.class);
    public static final String CORRELATION_ID_HEADER = "X-Correlation-ID";
    public static final String CORRELATION_ID_MDC_KEY = "correlationId";

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        HttpServletResponse httpResponse = (HttpServletResponse) response;

        String correlationId = extractOrGenerateCorrelationId(httpRequest);

        MDC.put(CORRELATION_ID_MDC_KEY, correlationId);
        httpResponse.setHeader(CORRELATION_ID_HEADER, correlationId);

        LOG.info("Request started: {} {}", httpRequest.getMethod(), httpRequest.getRequestURI());

        try {
            chain.doFilter(request, response);
        } finally {
            MDC.remove(CORRELATION_ID_MDC_KEY);
            LOG.info("Request completed: {} {} - Status: {}", 
                    httpRequest.getMethod(), httpRequest.getRequestURI(), httpResponse.getStatus());
        }
    }

    private String extractOrGenerateCorrelationId(HttpServletRequest request) {
        String header = request.getHeader(CORRELATION_ID_HEADER);
        return (header != null && !header.isBlank()) ? header : UUID.randomUUID().toString();
    }

    @Override
    public void init(FilterConfig filterConfig) throws ServletException {}

    @Override
    public void destroy() {}
}

This filter uses @Order to enforce early execution, ensuring correlation ID availability for downstream components. It cleans up MDC in finally to prevent memory leaks in thread-pooled environments.

SecurityContextHolder and Async Processing

Asynchronous operations in LogisticsCore—such as inventory status polling or shipment event broadcasting—require explicit security context propagation. The default ThreadLocal strategy does not transfer context to new threads, including virtual threads in Java 21+.

Spring Security does not automatically use InheritableThreadLocal. Instead, developers must opt into context inheritance via SecurityContextHolder.MODE_INHERITABLETHREADLOCAL, or use a TaskDecorator to manually propagate the context.

Example: TaskDecorator for SecurityContext Propagation

The following TaskDecorator ensures both MDC and SecurityContext are propagated to async threads, including virtual threads:

// Example: Fixing ThreadLocal Propagation with TaskDecorator (Java 21 Virtual Threads compatible)
package com.logistics.core.config;

import org.slf4j.MDC;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.task.TaskDecorator;
import org.springframework.security.core.context.SecurityContext;
import org.springframework.security.core.context.SecurityContextHolder;
import java.util.Map;

@Configuration
public class AsyncConfig {

    @Bean
    public TaskDecorator mdcAndSecurityContextTaskDecorator() {
        return runnable -> {
            Map<String, String> mdcContext = MDC.getCopyOfContextMap();
            SecurityContext securityContext = SecurityContextHolder.getContext();

            return () -> {
                try {
                    if (mdcContext != null) {
                        MDC.setContextMap(mdcContext);
                    }
                    SecurityContextHolder.setContext(securityContext);
                    runnable.run();
                } finally {
                    MDC.clear();
                    SecurityContextHolder.clearContext();
                }
            };
        };
    }
}

This decorator captures the current thread’s diagnostic and security state, restores it in the executing thread, and ensures cleanup. It is registered with TaskExecutor beans to wrap all submitted tasks.

Conclusion

The Servlet Filter chain in LogisticsCore is not a passive pipeline but an active enforcement point for security, observability, and correctness. Developers must understand the underlying JVM mechanisms—ThreadLocal, Servlet lifecycle, and thread inheritance—before relying on Spring abstractions such as DelegatingFilterProxy or TaskDecorator.

Spring Framework provides the building blocks; Spring Boot configures them via opinionated defaults (e.g., auto-configured FilterChainProxy). However, in high-assurance systems like LogisticsCore, these defaults must be audited, not assumed. Filter order, context propagation, and thread safety are not optional concerns—they are failure modes waiting to be exploited.

Sources

[1] Spring Security Documentation. [Online]. Available: https://docs.spring.io/spring-security/reference/index.html [2] Java Servlet API Documentation. [Online]. Available: https://javaee.github.io/javaee-spec/javadocs/javax/servlet/package-summary.html [3] Spring Framework Documentation. [Online]. Available: https://docs.spring.io/spring/docs/current/spring-framework-reference/index.html