Add SecurityContextHolderFilter

Closes gh-9635

docs/modules/ROOT/pages/servlet/appendix/namespace/http.adoc

@@ -125,6 +125,12 @@ A request pattern can be mapped to an empty filter chain, by setting this attrib
 No security will be applied and none of Spring Security's features will be available.
 
 
+[[nsa-http-security-context-explicit-save]]
+* **security-context-explicit-save**
+If true, use `SecurityContextHolderFilter` instead of `SecurityContextPersistenceFilter`.
+Requires explicit save
+
+
 [[nsa-http-security-context-repository-ref]]
 * **security-context-repository-ref**
 Allows injection of a custom `SecurityContextRepository` into the `SecurityContextPersistenceFilter`.

docs/modules/ROOT/pages/servlet/authentication/persistence.adoc

@@ -88,6 +88,34 @@ Depending on the servlet container implementation, the error means that any `Sec
 When the error dispatch is made, there is no `SecurityContext` established.
 This means that the error page cannot use the `SecurityContext` for authorization or displaying the current user unless the `SecurityContext` is persisted somehow.
 
+.Use RequestAttributeSecurityContextRepository
+====
+.Java
+[source,java,role="primary"]
+----
+public SecurityFilterChain filterChain(HttpSecurity http) {
+	http
+		// ...
+		.securityContext((securityContext) -> securityContext
+			.securityContextRepository(new RequestAttributeSecurityContextRepository())
+		);
+	return http.build();
+}
+----
+
+.XML
+[source,xml,role="secondary"]
+----
+<http security-context-repository-ref="contextRepository">
+	<!-- ... -->
+</http>
+<b:bean name="contextRepository"
+	class="org.springframework.security.web.context.RequestAttributeSecurityContextRepository" />
+----
+====
+
+
+[[securitycontextpersistencefilter]]
 == SecurityContextPersistenceFilter
 
 The {security-api-url}org/springframework/security/web/context/SecurityContextPersistenceFilter.html[`SecurityContextPersistenceFilter`] is responsible for persisting the `SecurityContext` between requests using the xref::servlet/authentication/persistence.adoc#securitycontextrepository[`SecurityContextRepository`].
@@ -104,4 +132,41 @@ For example, if a redirect is sent to the client the response is immediately wri
 This means that establishing an `HttpSession` would not be possible in step 3 because the session id could not be included in the already written response.
 Another situation that can happen is that if a client authenticates successfully, the response is committed before `SecurityContextPersistenceFilter` completes, and the client makes a second request before the `SecurityContextPersistenceFilter` completes the wrong authentication could be present in the second request.
 
-To avoid these problems, the `SecurityContextPersistenceFilter` wraps both the `HttpServletRequest` and the `HttpServletResponse` to detect if the `SecurityContext` has changed and if so save the `SecurityContext` just before the response is committed.
+To avoid these problems, the `SecurityContextPersistenceFilter` wraps both the `HttpServletRequest` and the `HttpServletResponse` to detect if the `SecurityContext` has changed and if so save the `SecurityContext` just before the response is committed.
+
+[[securitycontextholderfilter]]
+== SecurityContextHolderFilter
+
+The {security-api-url}org/springframework/security/web/context/SecurityContextHolderFilter.html[`SecurityContextHolderFilter`] is responsible for loading the `SecurityContext` between requests using the xref::servlet/authentication/persistence.adoc#securitycontextrepository[`SecurityContextRepository`].
+
+image::{figures}/securitycontextholderfilter.png[]
+
+<1> Before running the rest of the application, `SecurityContextHolderFilter` loads the `SecurityContext` from the `SecurityContextRepository` and sets it on the `SecurityContextHolder`.
+<2> Next, the application is ran.
+
+Unlike, xref:servlet/authentication/persistence.adoc#securitycontextpersistencefilter[`SecurityContextPersisteneFilter`], `SecurityContextHolderFilter` only loads the `SecurityContext` it does not save the `SecurityContext`.
+This means that when using `SecurityContextHolderFilter`, it is required that the `SecurityContext` is explicitly saved.
+
+.Explicit Saving of SecurityContext
+====
+.Java
+[source,java,role="primary"]
+----
+public SecurityFilterChain filterChain(HttpSecurity http) {
+	http
+		// ...
+		.securityContext((securityContext) -> securityContext
+			.requireExplicitSave(true)
+		);
+	return http.build();
+}
+----
+
+.XML
+[source,xml,role="secondary"]
+----
+<http security-context-explicit-save="true">
+	<!-- ... -->
+</http>
+----
+====

docs/modules/ROOT/pages/whats-new.adoc

@@ -3,3 +3,6 @@
 
 Spring Security 5.7 provides a number of new features.
 Below are the highlights of the release.
+
+* xref:servlet/authentication/persistence.adoc#requestattributesecuritycontextrepository[`RequestAttributeSecurityContextRepository`]
+* xref:servlet/authentication/persistence.adoc#securitycontextholderfilter[`SecurityContextHolderFilter`] - Ability to require explicit saving of the `SecurityContext`.