Reactive Security Context Propagation

## The problem In classic Spring MVC (Servlet stack), each HTTP request is bound to one thread for its whole lifetime. Spring Security stores the authenticated user in a **`ThreadLocal`** via `SecurityContextHolder` (default strategy `MODE_THREADLOCAL`). Anywhere in that call stack you can call `SecurityContextHolder.getContext().getAuthentication()` and get the right user, because you're guaranteed to be on the same thread the filter set it on. Spring WebFlux is different. It runs on a small pool of **event-loop threads** (Reactor Netty, typically one per CPU core). A single request is processed as a chain of asynchronous operators, and work can **hop between threads** (e.g. after a `flatMap` that switches schedulers). One event-loop thread also serves **many requests interleaved**. A `ThreadLocal` therefore cannot reliably carry per-request state: it may be empty, or worse, hold *another* request's data. So `SecurityContextHolder.getContext()` on WebFlux returns an empty/incorrect context. ## The reactive solution Spring Security stores the authenticated user in the **Reactor Context** — an immutable key/value map attached to the *subscription*, not to a thread — and exposes it through **`ReactiveSecurityContextHolder`**. ```java ReactiveSecurityContextHolder.getContext() // Mono<SecurityContext> .map(SecurityContext::getAuthentication) // Authentication .map(Authentication::getName) // e.g. the username ``` Key facts: - `getContext()` returns a **`Mono<SecurityContext>`**, never a plain value — reading the principal is itself an async step in the chain. - If there is no authenticated user, the Mono is **empty** (it does not emit), so `.map(...)` is simply skipped. Use `.switchIfEmpty(...)` or `.defaultIfEmpty(...)` to handle anonymous access. - You **must return** the resulting Mono/Flux from your controller so it stays connected to the request's reactive chain — that's how it can read the context. ## Convenience alternatives You usually don't call the holder directly. Spring's argument resolvers read the same reactive context: - **`@AuthenticationPrincipal`** on a method parameter (resolved by `AuthenticationPrincipalArgumentResolver`). - Declaring a parameter of type `Mono<Principal>`, `Authentication`, or `Principal` — WebFlux injects it. ```java @GetMapping("/me") Mono<String> me(@AuthenticationPrincipal UserDetails user) { return Mono.just(user.getUsername()); } ``` ## When to use what - Simple 'who am I' in a controller: `@AuthenticationPrincipal` or a `Mono<Principal>` param. - Needing the full `Authentication`/authorities deep inside a service chain: `ReactiveSecurityContextHolder.getContext()`. - Method security (`@PreAuthorize`) works the same way reactively; it reads the reactive context, not the ThreadLocal. ## Gotcha Calling `SecurityContextHolder.getContext()` (the blocking one) inside WebFlux is a classic bug: it compiles, sometimes even 'works' in a naive test, then returns null/wrong data under load. Always use the `Reactive*` variant on the reactive stack.