From 4112adf6a0d1684335f3af742b668ea614684063 Mon Sep 17 00:00:00 2001
From: Rob Winch <rwinch@users.noreply.github.com>
Date: Fri, 28 Oct 2022 15:57:25 -0500
Subject: [PATCH] Document Configure Default CsrfTOken BREACH Protection

Closes gh-12107
---
 docs/modules/ROOT/pages/migration.adoc | 55 +++++++++++++++++++++++++-
 1 file changed, 54 insertions(+), 1 deletion(-)

diff --git a/docs/modules/ROOT/pages/migration.adoc b/docs/modules/ROOT/pages/migration.adoc
index 5a7fea0a4c..47ee3b9148 100644
--- a/docs/modules/ROOT/pages/migration.adoc
+++ b/docs/modules/ROOT/pages/migration.adoc
@@ -73,7 +73,7 @@ open fun springSecurity(http: HttpSecurity): SecurityFilterChain {
 
 If this breaks your application, then you can explicitly opt into the 5.8 defaults using the following configuration:
 
-.Defer Loading `CsrfToken`
+.Explicit Configure `CsrfToken` with 5.8 Defaults
 ====
 .Java
 [source,java,role="primary"]
@@ -125,6 +125,59 @@ open fun springSecurity(http: HttpSecurity): SecurityFilterChain {
 ----
 ====
 
+=== CSRF BREACH Protection
+
+If the steps for <<Defer Loading CsrfToken>> work for you, then you can also opt into Spring Security 6's default support for BREACH protection of the `CsrfToken` using the following configuration:
+
+.`CsrfToken` BREACH Protection
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+DefaultSecurityFilterChain springSecurity(HttpSecurity http) throws Exception {
+	XorCsrfTokenRequestAttributeHandler requestHandler = new XorCsrfTokenRequestAttributeHandler();
+	// set the name of the attribute the CsrfToken will be populated on
+	requestHandler.setCsrfRequestAttributeName("_csrf");
+	http
+		// ...
+		.csrf((csrf) -> csrf
+			.csrfTokenRequestHandler(requestHandler)
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+open fun springSecurity(http: HttpSecurity): SecurityFilterChain {
+	val requestHandler = XorCsrfTokenRequestAttributeHandler()
+	// set the name of the attribute the CsrfToken will be populated on
+	requestHandler.setCsrfRequestAttributeName("_csrf")
+	http {
+		csrf {
+			csrfTokenRequestHandler = requestHandler
+		}
+	}
+	return http.build()
+}
+----
+
+.XML
+[source,xml,role="secondary"]
+----
+<http>
+	<!-- ... -->
+	<csrf request-handler-ref="requestHandler"/>
+</http>
+<b:bean id="requestHandler"
+	class="org.springframework.security.web.csrf.XorCsrfTokenRequestAttributeHandler"
+	p:csrfRequestAttributeName="_csrf"/>
+----
+====
+
 === Explicit Save SecurityContextRepository
 
 In Spring Security 5, the default behavior is for the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontext[`SecurityContext`] to automatically be saved to the xref:servlet/authentication/persistence.adoc#securitycontextrepository[`SecurityContextRepository`] using the xref:servlet/authentication/persistence.adoc#securitycontextpersistencefilter[`SecurityContextPersistenceFilter`].