servlet-authentication-logout.md

# Handling Logouts

## Logout Java/Kotlin Configuration

When using the `[WebSecurityConfigurerAdapter](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/config/annotation/web/configuration/WebSecurityConfigurerAdapter.html)`, 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?logout`

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

Example 1. Logout Configuration

Java

```
protected void configure(HttpSecurity http) throws Exception {
    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

```
override fun configure(http: HttpSecurity) {
    http {
        logout {
            logoutUrl = "/my/logout"                              (1)
            logoutSuccessUrl = "/my/index"                        (2)
            logoutSuccessHandler = customLogoutSuccessHandler     (3)
            invalidateHttpSession = true                          (4)
            addLogoutHandler(logoutHandler)                       (5)
            deleteCookies(cookieNamesToClear)                     (6)
        }
    }
}
```

|**1**|                                                                                                                                                         Provides logout support.<br/>This is automatically applied when using `WebSecurityConfigurerAdapter`.                                                                                                                                                          |
|-----|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|**2**|                 The URL that triggers log out to occur (default is `/logout`).<br/>If CSRF protection is enabled (default), then the request must also be a POST.<br/>For more information, please consult the [Javadoc](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutUrl-java.lang.String-).                 |
|**3**|                                           The URL to redirect to after logout has occurred.<br/>The default is `/login?logout`.<br/>For more information, please consult the [Javadoc](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutSuccessUrl-java.lang.String-).                                            |
|**4**|Let’s you specify a custom `LogoutSuccessHandler`.<br/>If this is specified, `logoutSuccessUrl()` is ignored.<br/>For more information, please consult the [Javadoc](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutSuccessHandler-org.springframework.security.web.authentication.logout.LogoutSuccessHandler-).|
|**5**|  Specify whether to invalidate the `HttpSession` at the time of logout.<br/>This is **true** by default.<br/>Configures the `SecurityContextLogoutHandler` under the covers.<br/>For more information, please consult the [Javadoc](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#invalidateHttpSession-boolean-).   |
|**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.<br/>This is a shortcut for adding a `CookieClearingLogoutHandler` explicitly.                                                                                                                                  |

|   |Logouts can of course also be configured using the XML Namespace notation.<br/>Please see the documentation for the [ logout element](../appendix/namespace/http.html#nsa-logout) in the Spring Security XML Namespace section for further details.|
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

Generally, in order to customize logout functionality, you can add`[LogoutHandler](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/web/authentication/logout/LogoutHandler.html)`and/or`[LogoutSuccessHandler](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/web/authentication/logout/LogoutSuccessHandler.html)`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 using the `logout-url` attribute.
More information on other available attributes may be found in the namespace appendix.

## LogoutHandler

Generally, `[LogoutHandler](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/web/authentication/logout/LogoutHandler.html)`implementations indicate classes that are able to participate in logout handling.
They are expected to be invoked to perform necessary clean-up.
As such they should
not throw exceptions.
Various implementations are provided:

* [PersistentTokenBasedRememberMeServices](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/web/authentication/rememberme/PersistentTokenBasedRememberMeServices.html)

* [TokenBasedRememberMeServices](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/web/authentication/rememberme/TokenBasedRememberMeServices.html)

* [CookieClearingLogoutHandler](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/web/authentication/logout/CookieClearingLogoutHandler.html)

* [CsrfLogoutHandler](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/web/csrf/CsrfLogoutHandler.html)

* [SecurityContextLogoutHandler](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/web/authentication/logout/SecurityContextLogoutHandler.html)

* [HeaderWriterLogoutHandler](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/web/authentication/logout/HeaderWriterLogoutHandler.html)

Please see [Remember-Me Interfaces and Implementations](rememberme.html#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`.

## 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:

* [SimpleUrlLogoutSuccessHandler](https://docs.spring.io/spring-security/site/docs/5.6.2/api/org/springframework/security/web/authentication/logout/SimpleUrlLogoutSuccessHandler.html)

* 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.

## Further Logout-Related References

* [Logout Handling](#ns-logout)

* [ Testing Logout](../test/mockmvc/logout.html#test-logout)

* [ HttpServletRequest.logout()](../integrations/servlet-api.html#servletapi-logout)

* [Remember-Me Interfaces and Implementations](rememberme.html#remember-me-impls)

* [ Logging Out](../exploits/csrf.html#servlet-considerations-csrf-logout) in section CSRF Caveats

* Section [ Single Logout](cas.html#cas-singlelogout) (CAS protocol)

* Documentation for the [ logout element](../appendix/namespace/http.html#nsa-logout) in the Spring Security XML Namespace section

[Run-As](runas.html)[Authentication Events](events.html)