For the latest stable version, please use Spring Security 6.1.11!

Servlet API integration

Servlet 2.5+ Integration

This section describes how Spring Security integrates with the Servlet 2.5 specification.

HttpServletRequest.getRemoteUser()

HttpServletRequest.getRemoteUser() returns 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, you can check this for null to determine whether a user has authenticated or is anonymous. Knowing whether the user is authenticated or not can be useful for determining if certain UI elements should be shown or not (for example, a logout link that should be displayed only if the user is authenticated).

HttpServletRequest.getUserPrincipal()

HttpServletRequest.getUserPrincipal() returns the result of SecurityContextHolder.getContext().getAuthentication(). This means that 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

  • Kotlin

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();
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

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.

HttpServletRequest.isUserInRole(String)

HttpServletRequest.isUserInRole(String) determines if SecurityContextHolder.getContext().getAuthentication().getAuthorities() contains a GrantedAuthority with the role passed into isUserInRole(String). Typically, users should not pass the ROLE_ prefix to 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

  • Kotlin

boolean isAdmin = httpServletRequest.isUserInRole("ADMIN");
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.

Servlet 3+ Integration

The following section describes the Servlet 3 methods with which Spring Security integrates.

HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse)

You can use the HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse) method to ensure that a user is authenticated. If they are not authenticated, the configured AuthenticationEntryPoint is used to request the user to authenticate (redirect to the login page).

HttpServletRequest.login(String,String)

You can use the HttpServletRequest.login(String,String) method to authenticate the user with the current AuthenticationManager. For example, the following would attempt to authenticate with a username of user and a password of password:

  • Java

  • Kotlin

try {
httpServletRequest.login("user","password");
} catch(ServletException ex) {
// fail to authenticate
}
try {
    httpServletRequest.login("user", "password")
} catch (ex: ServletException) {
    // fail to authenticate
}

You need not catch the ServletException if you want Spring Security to process the failed authentication attempt.

HttpServletRequest.logout()

You can use the HttpServletRequest.logout() method to log out the current user.

Typically, this means that the SecurityContextHolder is cleared out, the HttpSession is invalidated, any “Remember Me” authentication is cleaned up, and so on. However, the configured LogoutHandler implementations vary, depending on your Spring Security configuration. Note that, after HttpServletRequest.logout() has been invoked, you are still in charge of writing out a response. Typically, this would involve a redirect to the welcome page.

AsyncContext.start(Runnable)

The AsyncContext.start(Runnable) method ensures your credentials are propagated to the new Thread. By using Spring Security’s concurrency support, Spring Security overrides AsyncContext.start(Runnable) to ensure that the current SecurityContext is used when processing the Runnable. The following example outputs the current user’s Authentication:

  • Java

  • Kotlin

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);
		}
	}
});
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)
    }
}

Async Servlet Support

If you use Java-based configuration, you are ready to go. If you use XML configuration, a few updates are necessary. The first step is to ensure that you have updated your web.xml file to use at least the 3.0 schema:

<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 set up for processing asynchronous requests:

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

Now Spring Security ensures 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 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 properly with asynchronous requests. 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 asynchronous environment. Consider the following example:

  • Java

  • Kotlin

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();
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 that, when we commit the HttpServletResponse, there is no SecurityContext. When Spring Security automatically saved the SecurityContext on committing the HttpServletResponse, it would lose a 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.

Servlet 3.1+ Integration

The following section describes the Servlet 3.1 methods that Spring Security integrates with.

HttpServletRequest#changeSessionId()

HttpServletRequest.changeSessionId() is the default method for protecting against Session Fixation attacks in Servlet 3.1 and higher.