mirror of
https://github.com/spring-projects/spring-security.git
synced 2025-10-31 14:48:54 +00:00
289 lines
11 KiB
Plaintext
289 lines
11 KiB
Plaintext
[[servletapi]]
|
|
= Servlet API integration
|
|
This section describes how Spring Security is integrated with the Servlet API.
|
|
|
|
|
|
[[servletapi-25]]
|
|
== Servlet 2.5+ Integration
|
|
|
|
|
|
[[servletapi-remote-user]]
|
|
=== HttpServletRequest.getRemoteUser()
|
|
The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[HttpServletRequest.getRemoteUser()] will return the result of `SecurityContextHolder.getContext().getAuthentication().getName()` which is typically the current username.
|
|
This can be useful if you want to display the current username in your application.
|
|
Additionally, checking if this is null can be used to indicate if a user has authenticated or is anonymous.
|
|
Knowing if the user is authenticated or not can be useful for determining if certain UI elements should be shown or not (i.e. a log out link should only be displayed if the user is authenticated).
|
|
|
|
|
|
[[servletapi-user-principal]]
|
|
=== HttpServletRequest.getUserPrincipal()
|
|
The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[HttpServletRequest.getUserPrincipal()] will return the result of `SecurityContextHolder.getContext().getAuthentication()`.
|
|
This means it is an `Authentication` which is typically an instance of `UsernamePasswordAuthenticationToken` when using username and password based authentication.
|
|
This can be useful if you need additional information about your user.
|
|
For example, you might have created a custom `UserDetailsService` that returns a custom `UserDetails` containing a first and last name for your user.
|
|
You could obtain this information with the following:
|
|
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
Authentication auth = httpServletRequest.getUserPrincipal();
|
|
// assume integrated custom UserDetails called MyCustomUserDetails
|
|
// by default, typically instance of UserDetails
|
|
MyCustomUserDetails userDetails = (MyCustomUserDetails) auth.getPrincipal();
|
|
String firstName = userDetails.getFirstName();
|
|
String lastName = userDetails.getLastName();
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
val auth: Authentication = httpServletRequest.getUserPrincipal()
|
|
// assume integrated custom UserDetails called MyCustomUserDetails
|
|
// by default, typically instance of UserDetails
|
|
val userDetails: MyCustomUserDetails = auth.principal as MyCustomUserDetails
|
|
val firstName: String = userDetails.firstName
|
|
val lastName: String = userDetails.lastName
|
|
----
|
|
======
|
|
|
|
[NOTE]
|
|
====
|
|
It should be noted that it is typically bad practice to perform so much logic throughout your application.
|
|
Instead, one should centralize it to reduce any coupling of Spring Security and the Servlet API's.
|
|
====
|
|
|
|
[[servletapi-user-in-role]]
|
|
=== HttpServletRequest.isUserInRole(String)
|
|
The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[HttpServletRequest.isUserInRole(String)] will determine if `SecurityContextHolder.getContext().getAuthentication().getAuthorities()` contains a `GrantedAuthority` with the role passed into `isUserInRole(String)`.
|
|
Typically users should not pass in the "ROLE_" prefix into this method since it is added automatically.
|
|
For example, if you want to determine if the current user has the authority "ROLE_ADMIN", you could use the following:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
boolean isAdmin = httpServletRequest.isUserInRole("ADMIN");
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
val isAdmin: Boolean = httpServletRequest.isUserInRole("ADMIN")
|
|
----
|
|
======
|
|
|
|
This might be useful to determine if certain UI components should be displayed.
|
|
For example, you might display admin links only if the current user is an admin.
|
|
|
|
[[servletapi-3]]
|
|
== Servlet 3+ Integration
|
|
The following section describes the Servlet 3 methods that Spring Security integrates with.
|
|
|
|
|
|
[[servletapi-authenticate]]
|
|
=== HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse)
|
|
The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#authenticate%28javax.servlet.http.HttpServletResponse%29[HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse)] method can be used to ensure that a user is authenticated.
|
|
If they are not authenticated, the configured AuthenticationEntryPoint will be used to request the user to authenticate (i.e. redirect to the login page).
|
|
|
|
|
|
[[servletapi-login]]
|
|
=== HttpServletRequest.login(String,String)
|
|
The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#login%28java.lang.String,%20java.lang.String%29[HttpServletRequest.login(String,String)] method can be used to authenticate the user with the current `AuthenticationManager`.
|
|
For example, the following would attempt to authenticate with the username "user" and password "password":
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
try {
|
|
httpServletRequest.login("user","password");
|
|
} catch(ServletException ex) {
|
|
// fail to authenticate
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
try {
|
|
httpServletRequest.login("user", "password")
|
|
} catch (ex: ServletException) {
|
|
// fail to authenticate
|
|
}
|
|
----
|
|
======
|
|
|
|
[NOTE]
|
|
====
|
|
It is not necessary to catch the ServletException if you want Spring Security to process the failed authentication attempt.
|
|
====
|
|
|
|
[[servletapi-logout]]
|
|
=== HttpServletRequest.logout()
|
|
The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#logout%28%29[HttpServletRequest.logout()] method can be used to log the current user out.
|
|
|
|
Typically this means that the SecurityContextHolder will be cleared out, the HttpSession will be invalidated, any "Remember Me" authentication will be cleaned up, etc.
|
|
However, the configured LogoutHandler implementations will vary depending on your Spring Security configuration.
|
|
It is important to note that after HttpServletRequest.logout() has been invoked, you are still in charge of writing a response out.
|
|
Typically this would involve a redirect to the welcome page.
|
|
|
|
[[servletapi-start-runnable]]
|
|
=== AsyncContext.start(Runnable)
|
|
The https://docs.oracle.com/javaee/6/api/javax/servlet/AsyncContext.html#start%28java.lang.Runnable%29[AsyncContext.start(Runnable)] method that ensures your credentials will be propagated to the new Thread.
|
|
Using Spring Security's concurrency support, Spring Security overrides the AsyncContext.start(Runnable) to ensure that the current SecurityContext is used when processing the Runnable.
|
|
For example, the following would output the current user's Authentication:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
final AsyncContext async = httpServletRequest.startAsync();
|
|
async.start(new Runnable() {
|
|
public void run() {
|
|
Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
|
|
try {
|
|
final HttpServletResponse asyncResponse = (HttpServletResponse) async.getResponse();
|
|
asyncResponse.setStatus(HttpServletResponse.SC_OK);
|
|
asyncResponse.getWriter().write(String.valueOf(authentication));
|
|
async.complete();
|
|
} catch(Exception ex) {
|
|
throw new RuntimeException(ex);
|
|
}
|
|
}
|
|
});
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
val async: AsyncContext = httpServletRequest.startAsync()
|
|
async.start {
|
|
val authentication: Authentication = SecurityContextHolder.getContext().authentication
|
|
try {
|
|
val asyncResponse = async.response as HttpServletResponse
|
|
asyncResponse.status = HttpServletResponse.SC_OK
|
|
asyncResponse.writer.write(String.valueOf(authentication))
|
|
async.complete()
|
|
} catch (ex: Exception) {
|
|
throw RuntimeException(ex)
|
|
}
|
|
}
|
|
----
|
|
======
|
|
|
|
[[servletapi-async]]
|
|
=== Async Servlet Support
|
|
If you are using Java Based configuration, you are ready to go.
|
|
If you are using XML configuration, there are a few updates that are necessary.
|
|
The first step is to ensure you have updated your web.xml to use at least the 3.0 schema as shown below:
|
|
|
|
[source,xml]
|
|
----
|
|
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee https://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
|
|
version="3.0">
|
|
|
|
</web-app>
|
|
----
|
|
|
|
Next you need to ensure that your springSecurityFilterChain is setup for processing asynchronous requests.
|
|
|
|
[source,xml]
|
|
----
|
|
<filter>
|
|
<filter-name>springSecurityFilterChain</filter-name>
|
|
<filter-class>
|
|
org.springframework.web.filter.DelegatingFilterProxy
|
|
</filter-class>
|
|
<async-supported>true</async-supported>
|
|
</filter>
|
|
<filter-mapping>
|
|
<filter-name>springSecurityFilterChain</filter-name>
|
|
<url-pattern>/*</url-pattern>
|
|
<dispatcher>REQUEST</dispatcher>
|
|
<dispatcher>ASYNC</dispatcher>
|
|
</filter-mapping>
|
|
----
|
|
|
|
That's it!
|
|
Now Spring Security will ensure that your SecurityContext is propagated on asynchronous requests too.
|
|
|
|
So how does it work? If you are not really interested, feel free to skip the remainder of this section, otherwise read on.
|
|
Most of this is built into the Servlet specification, but there is a little bit of tweaking that Spring Security does to ensure things work with asynchronous requests properly.
|
|
Prior to Spring Security 3.2, the SecurityContext from the SecurityContextHolder was automatically saved as soon as the HttpServletResponse was committed.
|
|
This can cause issues in an Async environment.
|
|
For example, consider the following:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
httpServletRequest.startAsync();
|
|
new Thread("AsyncThread") {
|
|
@Override
|
|
public void run() {
|
|
try {
|
|
// Do work
|
|
TimeUnit.SECONDS.sleep(1);
|
|
|
|
// Write to and commit the httpServletResponse
|
|
httpServletResponse.getOutputStream().flush();
|
|
} catch (Exception ex) {
|
|
ex.printStackTrace();
|
|
}
|
|
}
|
|
}.start();
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
httpServletRequest.startAsync()
|
|
object : Thread("AsyncThread") {
|
|
override fun run() {
|
|
try {
|
|
// Do work
|
|
TimeUnit.SECONDS.sleep(1)
|
|
|
|
// Write to and commit the httpServletResponse
|
|
httpServletResponse.outputStream.flush()
|
|
} catch (ex: java.lang.Exception) {
|
|
ex.printStackTrace()
|
|
}
|
|
}
|
|
}.start()
|
|
----
|
|
======
|
|
|
|
The issue is that this Thread is not known to Spring Security, so the SecurityContext is not propagated to it.
|
|
This means when we commit the HttpServletResponse there is no SecurityContext.
|
|
When Spring Security automatically saved the SecurityContext on committing the HttpServletResponse it would lose our logged in user.
|
|
|
|
Since version 3.2, Spring Security is smart enough to no longer automatically save the SecurityContext on committing the HttpServletResponse as soon as HttpServletRequest.startAsync() is invoked.
|
|
|
|
[[servletapi-31]]
|
|
== Servlet 3.1+ Integration
|
|
The following section describes the Servlet 3.1 methods that Spring Security integrates with.
|
|
|
|
[[servletapi-change-session-id]]
|
|
=== HttpServletRequest#changeSessionId()
|
|
The https://docs.oracle.com/javaee/7/api/javax/servlet/http/HttpServletRequest.html#changeSessionId()[HttpServletRequest.changeSessionId()] is the default method for protecting against xref:servlet/authentication/session-management.adoc#ns-session-fixation[Session Fixation] attacks in Servlet 3.1 and higher.
|