90 lines
4.5 KiB
Plaintext
90 lines
4.5 KiB
Plaintext
[[servlet-authentication-securitycontextholder]]
|
|
= SecurityContextHolder
|
|
|
|
:figures: images/servlet/authentication/architecture
|
|
|
|
At the heart of Spring Security's authentication model is the `SecurityContextHolder`.
|
|
It contains the <<servlet-authentication-securitycontext>>.
|
|
|
|
image::{figures}/securitycontextholder.png[]
|
|
|
|
The `SecurityContextHolder` is where Spring Security stores the details of who is <<authentication,authenticated>>.
|
|
Spring Security does not care how the `SecurityContextHolder` is populated.
|
|
If it contains a value, then it is used as the currently authenticated user.
|
|
|
|
The simplest way to indicate a user is authenticated is to set the `SecurityContextHolder` directly.
|
|
|
|
.Setting `SecurityContextHolder`
|
|
====
|
|
.Java
|
|
[source,java,role="primary"]
|
|
----
|
|
SecurityContext context = SecurityContextHolder.createEmptyContext(); // <1>
|
|
Authentication authentication =
|
|
new TestingAuthenticationToken("username", "password", "ROLE_USER"); // <2>
|
|
context.setAuthentication(authentication);
|
|
|
|
SecurityContextHolder.setContext(context); // <3>
|
|
----
|
|
|
|
.Kotlin
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
val context: SecurityContext = SecurityContextHolder.createEmptyContext() // <1>
|
|
val authentication: Authentication = TestingAuthenticationToken("username", "password", "ROLE_USER") // <2>
|
|
context.authentication = authentication
|
|
|
|
SecurityContextHolder.setContext(context) // <3>
|
|
----
|
|
====
|
|
|
|
<1> We start by creating an empty `SecurityContext`.
|
|
It is important to create a new `SecurityContext` instance instead of using `SecurityContextHolder.getContext().setAuthentication(authentication)` to avoid race conditions across multiple threads.
|
|
<2> Next we create a new <<servlet-authentication-authentication,`Authentication`>> object.
|
|
Spring Security does not care what type of `Authentication` implementation is set on the `SecurityContext`.
|
|
Here we use `TestingAuthenticationToken` because it is very simple.
|
|
A more common production scenario is `UsernamePasswordAuthenticationToken(userDetails, password, authorities)`.
|
|
<3> Finally, we set the `SecurityContext` on the `SecurityContextHolder`.
|
|
Spring Security will use this information for <<servlet-authorization,authorization>>.
|
|
|
|
If you wish to obtain information about the authenticated principal, you can do so by accessing the `SecurityContextHolder`.
|
|
|
|
.Access Currently Authenticated User
|
|
====
|
|
.Java
|
|
[source,java,role="primary"]
|
|
----
|
|
SecurityContext context = SecurityContextHolder.getContext();
|
|
Authentication authentication = context.getAuthentication();
|
|
String username = authentication.getName();
|
|
Object principal = authentication.getPrincipal();
|
|
Collection<? extends GrantedAuthority> authorities = authentication.getAuthorities();
|
|
----
|
|
|
|
.Kotlin
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
val context = SecurityContextHolder.getContext()
|
|
val authentication = context.authentication
|
|
val username = authentication.name
|
|
val principal = authentication.principal
|
|
val authorities = authentication.authorities
|
|
----
|
|
====
|
|
|
|
// FIXME: add links to HttpServletRequest.getRemoteUser() and @CurrentSecurityContext @AuthenticationPrincipal
|
|
|
|
By default the `SecurityContextHolder` uses a `ThreadLocal` to store these details, which means that the `SecurityContext` is always available to methods in the same thread, even if the `SecurityContext` is not explicitly passed around as an argument to those methods.
|
|
Using a `ThreadLocal` in this way is quite safe if care is taken to clear the thread after the present principal's request is processed.
|
|
Spring Security's <<servlet-filterchainproxy,FilterChainProxy>> ensures that the `SecurityContext` is always cleared.
|
|
|
|
Some applications aren't entirely suitable for using a `ThreadLocal`, because of the specific way they work with threads.
|
|
For example, a Swing client might want all threads in a Java Virtual Machine to use the same security context.
|
|
`SecurityContextHolder` can be configured with a strategy on startup to specify how you would like the context to be stored.
|
|
For a standalone application you would use the `SecurityContextHolder.MODE_GLOBAL` strategy.
|
|
Other applications might want to have threads spawned by the secure thread also assume the same security identity.
|
|
This is achieved by using `SecurityContextHolder.MODE_INHERITABLETHREADLOCAL`.
|
|
You can change the mode from the default `SecurityContextHolder.MODE_THREADLOCAL` in two ways.
|
|
The first is to set a system property, the second is to call a static method on `SecurityContextHolder`.
|
|
Most applications won't need to change from the default, but if you do, take a look at the Javadoc for `SecurityContextHolder` to learn more.
|