For the latest stable version, please use Spring Security 6.1.11! |
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:
-
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:
-
HttpStatusReturningLogoutSuccessHandler
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
-
Properly Clearing Authentication When Explicit Save Is Enabled
-
Logging Out in section CSRF Caveats
-
Documentation for the logout element in the Spring Security XML Namespace section