spring-security/docs/modules/ROOT/pages/servlet/integrations/servlet-api.adoc

[[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:


====
.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:

====
.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":

====
.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:

====
.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:

====
.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.