This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Security 6.1.12!

Handling Logouts

This section covers how to customize the handling of logouts.

Logout Java/Kotlin Configuration

When using the HttpSecurity bean, logout capabilities are automatically applied. The default is that accessing the URL /logout logs the user out by:

  • Invalidating the HTTP Session

  • Cleaning up any RememberMe authentication that was configured

  • Clearing the SecurityContextHolder

  • Clearing the SecurityContextRepository

  • Redirecting to /login?logout

Similar to configuring login capabilities, however, you also have various options to further customize your logout requirements:

Logout Configuration

  • Java

  • Kotlin

public SecurityFilterChain filterChain(HttpSecurity http) {
    http
        .logout(logout -> logout                                                (1)
            .logoutUrl("/my/logout")                                            (2)
            .logoutSuccessUrl("/my/index")                                      (3)
            .logoutSuccessHandler(logoutSuccessHandler)                         (4)
            .invalidateHttpSession(true)                                        (5)
            .addLogoutHandler(logoutHandler)                                    (6)
            .deleteCookies(cookieNamesToClear)                                  (7)
        )
        ...
}
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
    http {
        logout {                                                  (1)
            logoutUrl = "/my/logout"                              (2)
            logoutSuccessUrl = "/my/index"                        (3)
            logoutSuccessHandler = customLogoutSuccessHandler     (4)
            invalidateHttpSession = true                          (5)
            addLogoutHandler(logoutHandler)                       (6)
            deleteCookies(cookieNamesToClear)                     (7)
        }
    }
    // ...
}
1 Provides logout support.
2 The URL that triggers log out to occur (the default is /logout). If CSRF protection is enabled (the default), the request must also be a POST. For more information, see logoutUrl(java.lang.String logoutUrl).
3 The URL to which to redirect after logout has occurred. The default is /login?logout. For more information, see logoutSuccessUrl(java.lang.String logoutSuccessUrl).
4 Let’s you specify a custom LogoutSuccessHandler. If this is specified, logoutSuccessUrl() is ignored. For more information, see LogoutSuccessHandler.
5 Specify whether to invalidate the HttpSession at the time of logout. This is true by default. Configures the SecurityContextLogoutHandler under the covers. For more information, see invalidateHttpSession(boolean invalidateHttpSession).
6 Adds a LogoutHandler. By default, SecurityContextLogoutHandler is added as the last LogoutHandler.
7 Lets specifying the names of cookies be removed on logout success. This is a shortcut for adding a CookieClearingLogoutHandler explicitly.

Logouts can also be configured by using the XML Namespace notation. See the documentation for the logout element in the Spring Security XML Namespace section for further details.

Generally, to customize logout functionality, you can add LogoutHandler or LogoutSuccessHandler implementations. For many common scenarios, these handlers are applied under the covers when using the fluent API.

Logout XML Configuration

The logout element adds support for logging out by navigating to a particular URL. The default logout URL is /logout, but you can set it to something else by setting the logout-url attribute. You can find more information on other available attributes in the namespace appendix.

LogoutHandler

Generally, LogoutHandler implementations indicate classes that are able to participate in logout handling. They are expected to be invoked to perform necessary clean-up. As a result, they should not throw exceptions. Spring Security provides various implementations:

See Remember-Me Interfaces and Implementations for details.

Instead of providing LogoutHandler implementations directly, the fluent API also provides shortcuts that provide the respective LogoutHandler implementations under the covers. For example, deleteCookies() lets you specify the names of one or more cookies to be removed on logout success. This is a shortcut compared to adding a CookieClearingLogoutHandler.

LogoutSuccessHandler

The LogoutSuccessHandler is called after a successful logout by the LogoutFilter, to handle (for example) redirection or forwarding to the appropriate destination. Note that the interface is almost the same as the LogoutHandler but may raise an exception.

Spring Security provides the following implementations:

As mentioned earlier, you need not specify the SimpleUrlLogoutSuccessHandler directly. Instead, the fluent API provides a shortcut by setting the logoutSuccessUrl(). This sets up the SimpleUrlLogoutSuccessHandler under the covers. The provided URL is redirected to after a logout has occurred. The default is /login?logout.

The HttpStatusReturningLogoutSuccessHandler can be interesting in REST API type scenarios. Instead of redirecting to a URL upon the successful logout, this LogoutSuccessHandler lets you provide a plain HTTP status code to be returned. If not configured, a status code 200 is returned by default.

Further Logout-Related References