[[jc-logout]] = Handling Logouts This section covers how to customize the handling of logouts. [[logout-java-configuration]] == Logout Java/Kotlin Configuration When using the `{security-api-url}org/springframework/security/config/annotation/web/builders/HttpSecurity.html[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` - Redirecting to `/login?logout` Similar to configuring login capabilities, however, you also have various options to further customize your logout requirements: .Logout Configuration ==== .Java [source,java,role="primary"] ---- 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> ) ... } ---- .Kotlin [source,kotlin,role="secondary"] ----- 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 {security-api-url}org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutUrl-java.lang.String-[`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 {security-api-url}org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutSuccessUrl-java.lang.String-[`logoutSuccessUrl(java.lang.String logoutSuccessUrl)`]. <4> Let's you specify a custom `LogoutSuccessHandler`. If this is specified, `logoutSuccessUrl()` is ignored. For more information, see {security-api-url}org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutSuccessHandler-org.springframework.security.web.authentication.logout.LogoutSuccessHandler-[`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 {security-api-url}org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#invalidateHttpSession-boolean-[`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. [NOTE] ==== Logouts can also be configured by using the XML Namespace notation. See the documentation for the xref:servlet/appendix/namespace/http.adoc#nsa-logout[ logout element] in the Spring Security XML Namespace section for further details. ==== Generally, to customize logout functionality, you can add `{security-api-url}org/springframework/security/web/authentication/logout/LogoutHandler.html[LogoutHandler]` or `{security-api-url}org/springframework/security/web/authentication/logout/LogoutSuccessHandler.html[LogoutSuccessHandler]` implementations. For many common scenarios, these handlers are applied under the covers when using the fluent API. [[ns-logout]] == 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. [[jc-logout-handler]] == LogoutHandler Generally, `{security-api-url}org/springframework/security/web/authentication/logout/LogoutHandler.html[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: - {security-api-url}org/springframework/security/web/authentication/rememberme/PersistentTokenBasedRememberMeServices.html[PersistentTokenBasedRememberMeServices] - {security-api-url}org/springframework/security/web/authentication/rememberme/TokenBasedRememberMeServices.html[TokenBasedRememberMeServices] - {security-api-url}org/springframework/security/web/authentication/logout/CookieClearingLogoutHandler.html[CookieClearingLogoutHandler] - {security-api-url}org/springframework/security/web/csrf/CsrfLogoutHandler.html[CsrfLogoutHandler] - {security-api-url}org/springframework/security/web/authentication/logout/SecurityContextLogoutHandler.html[SecurityContextLogoutHandler] - {security-api-url}org/springframework/security/web/authentication/logout/HeaderWriterLogoutHandler.html[HeaderWriterLogoutHandler] See xref:servlet/authentication/rememberme.adoc#remember-me-impls[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`. [[jc-logout-success-handler]] == 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: - {security-api-url}org/springframework/security/web/authentication/logout/SimpleUrlLogoutSuccessHandler.html[SimpleUrlLogoutSuccessHandler] - 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. [[jc-logout-references]] == Further Logout-Related References - <> - xref:servlet/test/mockmvc/logout.adoc#test-logout[Testing Logout] - xref:servlet/integrations/servlet-api.adoc#servletapi-logout[`HttpServletRequest.logout()`] - xref:servlet/authentication/rememberme.adoc#remember-me-impls[Remember-Me Interfaces and Implementations] - xref:servlet/exploits/csrf.adoc#servlet-considerations-csrf-logout[Logging Out] in section CSRF Caveats - Documentation for the xref:servlet/appendix/namespace/http.adoc#nsa-logout[logout element] in the Spring Security XML Namespace section