Spring Security Custom Logout Handler

1. Overview

The Spring Security framework provides very flexible and powerful support for authentication. Together with user identification, we’ll typically want to handle user logout events and, in some cases, add some custom logout behavior. One such use case could be for invalidating a user cache or closing authenticated sessions.

For this very purpose, Spring provides the LogoutHandler interface, and in this tutorial, we’ll take a look at how to implement our own custom logout handler.

2. Handling Logout Requests

Every web application that logs users in must log them out someday. Spring Security handlers usually control the logout process. Basically, we have two ways of handling logout. As we’re going to see, one of them is implementing the LogoutHandler interface.

2.1. LogoutHandler Interface

The LogoutHandler interface has the following definition:

public interface LogoutHandler {
    void logout(HttpServletRequest request, HttpServletResponse response,Authentication authentication);
}

It is possible to add as many logout handlers as we need to our application. The one requirement for the implementation is that no exceptions are thrown. This is because handler actions must not break the application state on logout.

For example, one of the handlers may do some cache cleanup, and its method must complete successfully. In the tutorial example, we’ll show exactly this use case.

2.2. LogoutSuccessHandler Interface

On the other hand, we can use exceptions to control the user logout strategy. For this, we have the LogoutSuccessHandler interface and the onLogoutSuccess method. This method may raise an exception to set user redirection to an appropriate destination.

Furthermore, it’s not possible to add multiple handlers when using a LogoutSuccessHandler type, so there is only one possible implementation for the application. Generally speaking, it turns out that it’s the last point of the logout strategy.

3. LogoutHandler Interface in Practice

Now, let’s create a simple web application to demonstrate the logout handling process. We’ll implement some simple caching logic to retrieve user data to avoid unnecessary hits on the database.

Let’s start with the application.properties file, which contains the database connection properties for our sample application:

spring.datasource.url=jdbc:postgresql://localhost:5432/test
spring.datasource.username=test
spring.datasource.password=test
spring.jpa.hibernate.ddl-auto=create

3.1. Web Application Setup

Next, we’ll add a simple User entity that we’ll use for login purposes and data retrieval. As we can see, the User class maps to the users table in our database:

@Entity
@Table(name = "users")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    @Column(unique = true)
    private String login;

    private String password;

    private String role;

    private String language;

    // standard setters and getters
}

For the caching purposes of our application, we’ll implement a cache service that uses a ConcurrentHashMap internally to store users:

@Service
public class UserCache {
    @PersistenceContext
    private EntityManager entityManager;

    private final ConcurrentMap<String, User> store = new ConcurrentHashMap<>(256);
}

Using this service, we can retrieve a user by user name (login) from the database and store it internally in our map:

public User getByUserName(String userName) {
    return store.computeIfAbsent(userName, k -> 
      entityManager.createQuery("from User where login=:login", User.class)
        .setParameter("login", k)
        .getSingleResult());
}

Furthermore, it is possible to evict the user from the store. As we’ll see later, this will be the main action that we’ll invoke from our logout handler:

public void evictUser(String userName) {
    store.remove(userName);
}

To retrieve user data and language information we’ll use a standard Spring Controller:

@Controller
@RequestMapping(path = "/user")
public class UserController {

    private final UserCache userCache;

    public UserController(UserCache userCache) {
        this.userCache = userCache;
    }

    @GetMapping(path = "/language")
    @ResponseBody
    public String getLanguage() {
        String userName = UserUtils.getAuthenticatedUserName();
        User user = userCache.getByUserName(userName);
        return user.getLanguage();
    }
}

3.2. Web Security Configuration

There are two simple actions we’ll focus on in the application — login and logout. First, we need to set up our MVC configuration class to allow users to authenticate using Basic HTTP Auth:

@Configuration
@EnableWebSecurity
public class MvcConfiguration {

    @Autowired
    private DataSource dataSource;

    @Autowired
    private CustomLogoutHandler logoutHandler;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.httpBasic(Customizer.withDefaults())
            .authorizeHttpRequests(authorizationManagerRequestMatcherRegistry ->
                    authorizationManagerRequestMatcherRegistry.requestMatchers(HttpMethod.GET, "/user/**").hasRole("USER"))
            .logout(httpSecurityLogoutConfigurer ->
                    httpSecurityLogoutConfigurer.logoutUrl("/user/logout")
                            .addLogoutHandler(logoutHandler)
                            .logoutSuccessHandler(new HttpStatusReturningLogoutSuccessHandler(HttpStatus.OK)).permitAll())
                .securityContext(httpSecuritySecurityContextConfigurer -> httpSecuritySecurityContextConfigurer.requireExplicitSave(false))
            .csrf(AbstractHttpConfigurer::disable)
            .formLogin(AbstractHttpConfigurer::disable);
        return http.build();
    }
}

The important part to note from the above configuration is the addLogoutHandler method. We pass and trigger our CustomLogoutHandler at the end of logout processing. The remaining settings fine-tune the HTTP Basic Auth.

3.3. Custom Logout Handler

Finally, and most importantly, we’ll write our custom logout handler that handles the necessary user cache cleanup:

@Service
public class CustomLogoutHandler implements LogoutHandler {

    private final UserCache userCache;

    public CustomLogoutHandler(UserCache userCache) {
        this.userCache = userCache;
    }

    @Override
    public void logout(HttpServletRequest request, HttpServletResponse response, 
      Authentication authentication) {
        String userName = UserUtils.getAuthenticatedUserName();
        userCache.evictUser(userName);
    }
}

As we can see, we override the logout method and simply evict the given user from the user cache.

4. Integration Testing

Let’s now test the functionality. To begin with, we need to verify that the cache works as intended — that is, it loads authorized users into its internal store:

@Test
public void whenLogin_thenUseUserCache() {
    assertThat(userCache.size()).isZero();

    ResponseEntity<String> response = restTemplate.withBasicAuth("user", "pass")
        .getForEntity(getLanguageUrl(), String.class);

    assertThat(response.getBody()).contains("english");

    assertThat(userCache.size()).isEqualTo(1);

    HttpHeaders requestHeaders = new HttpHeaders();
    requestHeaders.add("Cookie", response.getHeaders()
        .getFirst(HttpHeaders.SET_COOKIE));

    response = restTemplate.exchange(getLanguageUrl(), HttpMethod.GET, 
      new HttpEntity<String>(requestHeaders), String.class);
    assertThat(response.getBody()).contains("english");

    response = restTemplate.exchange(getLogoutUrl(), HttpMethod.GET, 
      new HttpEntity<String>(requestHeaders), String.class);
    assertThat(response.getStatusCode()
        .value()).isEqualTo(200);
}

Let’s decompose the steps to understand what we’ve done::

• First, we check that the cache is empty
• Next, we authenticate a user via the withBasicAuth method
• Now we can verify the user data and language value retrieved
• Consequently, we can verify that the user must now be in the cache
• Again, we check the user data by hitting the language endpoint and using a session cookie
• Finally, we verify logging out the user

In our second test, we’ll verify that the user cache is cleaned when we logout. This is the moment when our logout handler will be invoked:

@Test
public void whenLogout_thenCacheIsEmpty() {
    assertThat(userCache.size()).isZero();

    ResponseEntity<String> response = restTemplate.withBasicAuth("user", "pass")
        .getForEntity(getLanguageUrl(), String.class);

    assertThat(response.getBody()).contains("english");

    assertThat(userCache.size()).isEqualTo(1);

    HttpHeaders requestHeaders = new HttpHeaders();
    requestHeaders.add("Cookie", response.getHeaders()
        .getFirst(HttpHeaders.SET_COOKIE));

    response = restTemplate.exchange(getLogoutUrl(), HttpMethod.GET, 
      new HttpEntity<String>(requestHeaders), String.class);
    assertThat(response.getStatusCode()
        .value()).isEqualTo(200);

    assertThat(userCache.size()).isZero();

    response = restTemplate.exchange(getLanguageUrl(), HttpMethod.GET, 
      new HttpEntity<String>(requestHeaders), String.class);
    assertThat(response.getStatusCode()
        .value()).isEqualTo(401);
}

Again, step by step:

• As before, we begin by checking that the cache is empty
• Then we authenticate a user and check the user is in the cache
• Next, we perform a logout and check that the user has been removed from the cache
• Finally, an attempt to hit the language endpoint results with 401 HTTP unauthorized response code

5. Conclusion

It this tutorial, we learned how to implement a custom logout handler for evicting users from a user cache using Spring’s LogoutHandler interface.