From 9071f1075981a24ffd3da255f8ad93505996263d Mon Sep 17 00:00:00 2001
From: Steve Riesenberg <sriesenberg@vmware.com>
Date: Wed, 9 Nov 2022 11:46:51 -0600
Subject: [PATCH] Document DelegatingSecurityContextRepository

Closes gh-12069
---
 .../servlet/authentication/persistence.adoc   | 66 +++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/docs/modules/ROOT/pages/servlet/authentication/persistence.adoc b/docs/modules/ROOT/pages/servlet/authentication/persistence.adoc
index 3f17e9b39a..441f6a528f 100644
--- a/docs/modules/ROOT/pages/servlet/authentication/persistence.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/persistence.adoc
@@ -114,6 +114,72 @@ public SecurityFilterChain filterChain(HttpSecurity http) {
 ----
 ====
 
+[[delegatingsecuritycontextrepository]]
+=== DelegatingSecurityContextRepository
+
+The {security-api-url}org/springframework/security/web/context/DelegatingSecurityContextRepository.html[`DelegatingSecurityContextRepository`] saves the `SecurityContext` to multiple `SecurityContextRepository` delegates and allows retrieval from any of the delegates in a specified order.
+
+The most useful arrangement for this is configured with the following example, which allows the use of both xref:requestattributesecuritycontextrepository[`RequestAttributeSecurityContextRepository`] and xref:httpsecuritycontextrepository[`HttpSessionSecurityContextRepository`] simultaneously.
+
+.Configure DelegatingSecurityContextRepository
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+	http
+		// ...
+		.securityContext((securityContext) -> securityContext
+			.securityContextRepository(new DelegatingSecurityContextRepository(
+				new RequestAttributeSecurityContextRepository(),
+				new HttpSessionSecurityContextRepository()
+			))
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
+	http {
+		// ...
+		securityContext {
+			securityContextRepository = DelegatingSecurityContextRepository(
+				RequestAttributeSecurityContextRepository(),
+				HttpSessionSecurityContextRepository()
+			)
+		}
+	}
+	return http.build()
+}
+----
+
+.XML
+[source,xml,role="secondary"]
+----
+<http security-context-repository-ref="contextRepository">
+	<!-- ... -->
+</http>
+<bean name="contextRepository"
+	class="org.springframework.security.web.context.DelegatingSecurityContextRepository">
+		<constructor-arg>
+			<bean class="org.springframework.security.web.context.RequestAttributeSecurityContextRepository" />
+		</constructor-arg>
+		<constructor-arg>
+			<bean class="org.springframework.security.web.context.HttpSessionSecurityContextRepository" />
+		</constructor-arg>
+</bean>
+----
+====
+
+[NOTE]
+====
+In Spring Security 6, the example shown above is the default configuration.
+====
 
 [[securitycontextpersistencefilter]]
 == SecurityContextPersistenceFilter