Security Context

The SecurityContext is the container for the Authentication of the current execution, meaning who the caller is and what they are allowed to do. It is a small interface with getAuthentication and setAuthentication. Code reaches it through SecurityContextHolder, which by default stores it in a ThreadLocal, so any component running in the request can read the identity without passing it through method signatures. Spring Security creates or loads a context for each request, authentication filters populate it, authorisation rules and method security read it, and FilterChainProxy clears it when the request ends. For browser sessions it is persisted between requests; for stateless APIs it is rebuilt from the token on every request.

Let Spring MVC inject it rather than calling the static holder. Declaring an Authentication parameter gives the whole authentication, including name and authorities, while @AuthenticationPrincipal gives just the principal in its concrete type: a Jwt for a resource server, an OidcUser after OIDC login, or your UserDetails implementation for form login. The annotation also accepts a SpEL expression, so expression = "claims['customer_id']" extracts a single claim, and it can be wrapped in a custom meta-annotation such as @CurrentCustomerId for readability. @CurrentSecurityContext injects the whole context if needed. Injection keeps controllers easy to test, because MockMvc request post-processors such as jwt() can supply the principal directly.

In Spring Security an authority is any GrantedAuthority string attached to the Authentication, and a role is simply an authority that follows the ROLE_ prefix convention. hasAuthority('orders:approve') compares the string exactly, while hasRole('ADMIN') adds the prefix and checks for ROLE_ADMIN, so hasRole should be given the role name without the prefix. Conceptually, roles describe coarse groups of users, while authorities often represent fine-grained permissions or OAuth2 scopes, which Spring maps to SCOPE_ prefixed authorities. Mixing conventions is a frequent cause of 403 responses after switching from form login to JWTs, so decide on naming once, map claims to authorities at the edge, and use hasAuthority for permissions.

Within a request it lives in a ThreadLocal, because SecurityContextHolder uses the MODE_THREADLOCAL strategy by default, and code should ideally reach it through the SecurityContextHolderStrategy bean. Between requests, persistence is the job of a SecurityContextRepository. SecurityContextHolderFilter loads a deferred context from that repository at the start of each request, and since Spring Security 6 authentication mechanisms save it explicitly on success. For form login the default is HttpSessionSecurityContextRepository, which stores it in the HTTP session, combined with RequestAttributeSecurityContextRepository for the current request. Stateless chains, such as JWT resource servers, persist nothing and authenticate every request from its token. In every case the ThreadLocal is cleared at the end.

Because the context is stored in a ThreadLocal on the request thread, and @Async runs the method on a different thread from the task executor, which starts with an empty context. Authorisation checks inside the async method then fail, and auditing records no user or the wrong one. The fix is to propagate the context at the moment the task is submitted. Wrap the executor in a DelegatingSecurityContextAsyncTaskExecutor, or set a ContextPropagatingTaskDecorator on the ThreadPoolTaskExecutor so that the security context, MDC and trace context travel together. The wrapper copies the context into the worker thread and clears it afterwards. Avoid inheritable-thread-local mode as a shortcut, because pooled threads keep stale identities.

Configure a JwtAuthenticationConverter bean, which the resource server uses to turn a validated Jwt into a JwtAuthenticationToken. By default its JwtGrantedAuthoritiesConverter reads the scope or scp claim and prefixes each value with SCOPE_. For roles held in a custom claim, create a second JwtGrantedAuthoritiesConverter with setAuthoritiesClaimName("roles") and setAuthorityPrefix("ROLE_"), and combine both results in the converter's authorities function. For nested structures, such as Keycloak's realm_access.roles, write a small Converter<Jwt, Collection<GrantedAuthority>> that reads the map. setPrincipalClaimName lets you use a claim other than sub as the name. Unit test the converter directly with a Jwt built through Jwt.withTokenValue and assert the resulting authorities.

MODE_INHERITABLETHREADLOCAL copies the parent's context into a child thread only at the moment the child thread is created, which does not match how modern applications use threads. Executor pools create threads once and reuse them, so a worker created during Alice's request keeps Alice's context and later runs Bob's tasks under her identity, or under a stale identity long after her session ended. That is both a security failure and an audit failure, and because it is intermittent it rarely shows up in tests. Explicit propagation with delegating executors or context-propagating task decorators copies the correct context for each task and clears it afterwards, which is predictable, testable and easy to review.

Treat identity as data that must be carried explicitly, because there is no ThreadLocal across a broker. At publication, the producer adds identity metadata to message headers: at minimum the authenticated subject, the tenant and a correlation id, and, where downstream authorisation needs it, a signed token, preferably a short-lived one obtained through token exchange rather than the user's original access token. Consumers validate that metadata and establish a SecurityContext for the duration of processing, then clear it. System-initiated work such as schedulers and retries runs under explicit service principals, never as no user. Every service audits the acting principal and the original requester, so actions can be attributed across the whole chain.