diff --git a/docs/modules/ROOT/pages/migration/servlet/session-management.adoc b/docs/modules/ROOT/pages/migration/servlet/session-management.adoc index 0b1533ab3c..c7409b9e07 100644 --- a/docs/modules/ROOT/pages/migration/servlet/session-management.adoc +++ b/docs/modules/ROOT/pages/migration/servlet/session-management.adoc @@ -13,8 +13,14 @@ In Spring Security 6, the default behavior is that the xref:servlet/authenticati Users now must explicitly save the `SecurityContext` with the `SecurityContextRepository` if they want the `SecurityContext` to persist between requests. This removes ambiguity and improves performance by only requiring writing to the `SecurityContextRepository` (i.e. `HttpSession`) when it is necessary. +[NOTE] +==== +Saving the context is also needed when clearing it out, for example during logout. Refer to this section to xref:servlet/authentication/session-management.adoc#properly-clearing-authentication[know more about that]. +==== + If you are explicitly opting into Spring Security 6's new defaults, the following configuration can be removed to accept the Spring Security 6 defaults. + include::partial$servlet/architecture/security-context-explicit.adoc[] == Multiple SecurityContextRepository diff --git a/docs/modules/ROOT/pages/servlet/authentication/logout.adoc b/docs/modules/ROOT/pages/servlet/authentication/logout.adoc index fe6f3449c6..cc030ea94a 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/logout.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/logout.adoc @@ -141,6 +141,7 @@ If not configured, a status code 200 is returned by default. [[jc-logout-references]] == Further Logout-Related References +- xref:servlet/authentication/session-management.adoc#properly-clearing-authentication[Properly Clearing Authentication When Explicit Save Is Enabled] - <> - xref:servlet/test/mockmvc/logout.adoc#test-logout[Testing Logout] - xref:servlet/integrations/servlet-api.adoc#servletapi-logout[`HttpServletRequest.logout()`] diff --git a/docs/modules/ROOT/pages/servlet/authentication/session-management.adoc b/docs/modules/ROOT/pages/servlet/authentication/session-management.adoc index f1d7f83e51..3b7115f815 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/session-management.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/session-management.adoc @@ -12,6 +12,7 @@ But before you leave, consider if any of these use cases fit your application: * I want to <> * I want to <> a user can be logged in concurrently * I want <> myself instead of Spring Security doing it for me +* I am storing the authentication manually and I want <> * I am using <> and I need <> * I want to store the authentication <> * I am using a <>, but <> @@ -84,12 +85,6 @@ By default, Spring Security stores the security context for you in the HTTP sess First, you need to create an implementation of `SecurityContextRepository` or use an existing implementation like `HttpSessionSecurityContextRepository`, then you can set it in `HttpSecurity`. -[NOTE] -==== -The above configuration sets the `SecurityContextRepository` on the `SecurityContextHolderFilter` and **participating** authentication filters, like `UsernamePasswordAuthenticationFilter`. -To also set it in stateless filters, please see <>. -==== - [[customizing-the-securitycontextrepository]] .Customizing the `SecurityContextRepository` ==== @@ -134,6 +129,12 @@ open fun filterChain(http: HttpSecurity): SecurityFilterChain { ---- ==== +[NOTE] +==== +The above configuration sets the `SecurityContextRepository` on the `SecurityContextHolderFilter` and **participating** authentication filters, like `UsernamePasswordAuthenticationFilter`. +To also set it in stateless filters, please see <>. +==== + If you are using a custom authentication mechanism, you might want to <>. [[store-authentication-manually]] @@ -181,6 +182,32 @@ class LoginRequest { And that's it. If you are not sure what `securityContextHolderStrategy` is in the above example, you can read more about it in the <>. +[[properly-clearing-authentication]] +=== Properly Clearing an Authentication + +If you are using Spring Security's xref:servlet/authentication/logout.adoc[Logout Support] then it handles a lot of stuff for you including clearing and saving the context. +But, let's say you need to manually log users out of your app. In that case, you'll need to make sure you're clearing and saving the context properly. + +Now, you might already be familiar with clearing the `SecurityContextHolder` by doing `SecurityContextHolderStrategy#clearContext()`. +That's great, but if your app requires an xref:migration/servlet/session-management.adoc#_require_explicit_saving_of_securitycontextrepository[explicit save of the context], simply clearing it isn't enough. +The reason is that it doesn't remove it from the `SecurityContextRepository`, which means the `SecurityContext` could still be available for the next requests, and we definitely don't want that. + +To make sure the authentication is properly cleared and saved, you can invoke {security-api-url}/org/springframework/security/web/authentication/logout/SecurityContextLogoutHandler.html[the `SecurityContextLogoutHandler`] which does that for us, like so: + +==== +.Java +[source,java,role="primary"] +---- +SecurityContextLogoutHandler handler = new SecurityContextLogoutHandler(); <1> +handler.logout(httpServletRequest, httpServletResponse, null); <2> +---- +==== + +<1> Create a new instance of `SecurityContextLogoutHandler` +<2> Call the `logout` method passing in the `HttpServletRequest`, `HttpServletResponse` and a `null` authentication because it is not required for this handler. + +It's important to remember that clearing and saving the context is just one piece of the logout process, therefore we recommend having Spring Security take care of it. + [[stateless-authentication]] === Configuring Persistence for Stateless Authentication