150 lines
8.2 KiB
Plaintext
150 lines
8.2 KiB
Plaintext
[[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
|
|
|
|
- <<ns-logout, Logout Handling>>
|
|
- 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
|