SEC-2951: Document Logouthandler and LogoutSuccesshandler
Jira: https://jira.spring.io/browse/SEC-2951
This commit is contained in:
Gunnar Hillert
Rob Winch
parent
600927def6
commit
013177c644
|
|
@ -495,6 +495,7 @@ mvc
|
|||
.perform(formLogin("/auth").user("a","admin").password("p","pass"))
|
||||
----
|
||||
|
||||
[[test-logout]]
|
||||
==== Testing Logout
|
||||
|
||||
While fairly trivial using standard Spring MVC Test, you can use Spring Security's testing support to make testing log out easier.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
= Spring Security Reference
|
||||
Ben Alex; Luke Taylor; Rob Winch
|
||||
Ben Alex; Luke Taylor; Rob Winch; Gunnar Hillert
|
||||
:include-dir: _includes
|
||||
|
||||
Spring Security is a powerful and highly customizable authentication and access-control framework. It is the de-facto standard for securing Spring-based applications.
|
||||
|
|
@ -688,6 +688,113 @@ protected void configure(HttpSecurity http) throws Exception {
|
|||
<4> Any URL that starts with "/db/" requires the user to have both "ROLE_ADMIN" and "ROLE_DBA". You will notice that since we are using the `hasRole` expression we do not need to specify the "ROLE_" prefix.
|
||||
<5> Any URL that has not already been matched on only requires that the user be authenticated
|
||||
|
||||
[[jc-logout]]
|
||||
=== Handling Logouts
|
||||
|
||||
When using the
|
||||
`http://docs.spring.io/spring-security/site/docs/current/apidocs/org/springframework/security/config/annotation/web/configuration/WebSecurityConfigurerAdapter.html[WebSecurityConfigurerAdapter]`,
|
||||
logout capabilities are automatically applied. The default is that accessing the
|
||||
URL `/logout` will log the user out by:
|
||||
|
||||
- Invalidating the HTTP Session
|
||||
- Cleaning up any RememberMe authentication that was configured
|
||||
- Clearing the `SecurityContextHolder`
|
||||
- Redirect to `/login?success`
|
||||
|
||||
Similar to configuring login capabilities, however, you also have various options
|
||||
to further customize your logout requirements:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
protected void configure(HttpSecurity http) throws Exception {
|
||||
http
|
||||
.logout() <1>
|
||||
.logoutUrl("/my/logout") <2>
|
||||
.logoutSuccessUrl("/my/index") <3>
|
||||
.logoutSuccessHandler(logoutSuccessHandler) <4>
|
||||
.invalidateHttpSession(true) <5>
|
||||
.addLogoutHandler(logoutHandler) <6>
|
||||
.deleteCookies(cookieNamesToClear) <7>
|
||||
.and()
|
||||
...
|
||||
}
|
||||
----
|
||||
|
||||
<1> Provides logout support. This is automatically applied when using `WebSecurityConfigurerAdapter`.
|
||||
<2> The URL that triggers log out to occur (default is `/logout`). If CSRF protection is enabled (default), then the request must also be a POST. For for information, please consult the http://docs.spring.io/spring-security/site/docs/current/apidocs/org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutUrl(java.lang.String)[JavaDoc].
|
||||
<3> The URL to redirect to after logout has occurred. The default is `/login?logout`. For for information, please consult the http://docs.spring.io/spring-security/site/docs/current/apidocs/org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutSuccessUrl(java.lang.String)[JavaDoc].
|
||||
<4> Let's you specify a custom `LogoutSuccessHandler`. If this is specified, `logoutSuccessUrl()` is ignored. For for information, please consult the http://docs.spring.io/spring-security/site/docs/current/apidocs/org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutSuccessHandler(org.springframework.security.web.authentication.logout.LogoutSuccessHandler)[JavaDoc].
|
||||
<5> Specify whether to invalidate the `HttpSession` at the time of logout. This is *true* by default. Configures the `SecurityContextLogoutHandler` under the covers. For for information, please consult the http://docs.spring.io/spring-security/site/docs/current/apidocs/org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#invalidateHttpSession(boolean)[JavaDoc].
|
||||
<6> Adds a `LogoutHandler`. `SecurityContextLogoutHandler` is added as the last `LogoutHandler` by default.
|
||||
<7> Allows specifying the names of cookies to be removed on logout success. This is a shortcut for adding a `CookieClearingLogoutHandler` explicitly.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
Logouts can of course also be configured using the XML Namespace notation. Please see the documentation for the <<nsa-logout, logout element>> in the Spring Security XML Namespace section for further details.
|
||||
====
|
||||
|
||||
Generally, in order to customize logout functionality, you can add
|
||||
`http://docs.spring.io/spring-security/site/docs/current/apidocs/org/springframework/security/web/authentication/logout/LogoutHandler.html[LogoutHandler]`
|
||||
and/or
|
||||
`http://docs.spring.io/spring-security/site/docs/current/apidocs/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.
|
||||
|
||||
[[jc-logout-handler]]
|
||||
==== LogoutHandler
|
||||
|
||||
Generally, `http://docs.spring.io/spring-security/site/docs/current/apidocs/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 cleanup. As such they should
|
||||
not throw exceptions. Various implementations are provided:
|
||||
|
||||
- http://docs.spring.io/spring-security/site/docs/current/apidocs/org/springframework/security/web/authentication/rememberme/PersistentTokenBasedRememberMeServices.html[PersistentTokenBasedRememberMeServices]
|
||||
- http://docs.spring.io/spring-security/site/docs/current/apidocs/org/springframework/security/web/authentication/rememberme/TokenBasedRememberMeServices.html[TokenBasedRememberMeServices]
|
||||
- http://docs.spring.io/spring-security/site/docs/current/apidocs/org/springframework/security/web/authentication/logout/CookieClearingLogoutHandler.html[CookieClearingLogoutHandler]
|
||||
- http://docs.spring.io/spring-security/site/docs/current/apidocs/org/springframework/security/web/csrf/CsrfLogoutHandler.html[CsrfLogoutHandler]
|
||||
- http://docs.spring.io/spring-security/site/docs/current/apidocs/org/springframework/security/web/authentication/logout/SecurityContextLogoutHandler.html[SecurityContextLogoutHandler]
|
||||
|
||||
Please see <<remember-me-impls>> for details.
|
||||
|
||||
Instead of providing `LogoutHandler` implementations directly, the fluent API
|
||||
also provides shortcuts that provide the respective `LogoutHandler` implementations
|
||||
under the covers. E.g. `deleteCookies()` allows specifying 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 e.g. redirection or forwarding to the appropriate destination. Note that the
|
||||
interface is almost the same as the `LogoutHandler` but may raise an exception.
|
||||
|
||||
The following implementations are provided:
|
||||
|
||||
- http://docs.spring.io/spring-security/site/docs/current/apidocs/org/springframework/security/web/authentication/logout/SimpleUrlLogoutSuccessHandler.html[SimpleUrlLogoutSuccessHandler]
|
||||
- HttpStatusReturningLogoutSuccessHandler
|
||||
|
||||
As mentioned above, you don't need to specify the `SimpleUrlLogoutSuccessHandler` directly.
|
||||
Instead, the fluent API provides a shortcut by setting the `logoutSuccessUrl()`.
|
||||
This will setup the `SimpleUrlLogoutSuccessHandler` under the covers. The provided URL will
|
||||
be 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`
|
||||
allows you to provide a plain HTTP status code to be returned. If not configured
|
||||
a status code 200 will be returned by default.
|
||||
|
||||
[[jc-logout-references]]
|
||||
==== Further Logout-Related References
|
||||
|
||||
- <<ns-logout, Logout Handling>>
|
||||
- <<test-logout, Testing Logout>>
|
||||
- <<servletapi-logout, HttpServletRequest.logout()>>
|
||||
- <<remember-me-impls>>
|
||||
- <<csrf-logout, Logging Out>> in section CSRF Caveats
|
||||
- Section <<cas-singlelogout, Single Logout>> (CAS protocol)
|
||||
- Documentation for the <<nsa-logout, logout element>> in the Spring Security XML Namespace section
|
||||
|
||||
[[jc-authentication]]
|
||||
=== Authentication
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue