From 4ed131f6ab89ec5082fb78a1cfcc75258451e681 Mon Sep 17 00:00:00 2001
From: Josh Cummings <3627351+jzheaux@users.noreply.github.com>
Date: Tue, 3 Jun 2025 12:19:56 -0600
Subject: [PATCH] Add shouldConvertGetRequests Migration Steps

Issue gh-17099
---
 .../ROOT/pages/migration/servlet/oauth2.adoc  | 39 +++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/modules/ROOT/pages/migration/servlet/oauth2.adoc b/docs/modules/ROOT/pages/migration/servlet/oauth2.adoc
index 3caeec4133..e80e0a916e 100644
--- a/docs/modules/ROOT/pages/migration/servlet/oauth2.adoc
+++ b/docs/modules/ROOT/pages/migration/servlet/oauth2.adoc
@@ -78,3 +78,42 @@ fun jwtDecoder(): JwtDecoder {
 ======
 <1> - `validateTypes` now defaults to `false`
 <2> - `JwtTypeValidator#jwt` is added by all `createDefaultXXX` methods
+
+== Do Not Process `<saml2:Response>` GET Requests with `Saml2AuthenticationTokenConverter`
+
+Spring Security does not support processing `<saml2:Response>` payloads over GET as this is not supported by the SAML 2.0 spec.
+
+To better comply with this, `Saml2AuthenticationTokenConverter` will not process GET requests by default as of Spring Security 8.
+To prepare for this, the property `shouldConvertGetRequests` is available.
+To use it, publish your own `Saml2AuthenticationTokenConverter` like so:
+
+[tabs]
+======
+Java::
++
+[source,java,role="primary"]
+----
+@Bean
+Saml2AuthenticationTokenConverter authenticationConverter(RelyingPartyRegistrationRepository registrations) {
+	Saml2AuhenticationTokenConverter authenticationConverter = new Saml2AuthenticationTokenConverter(
+		new DefaultRelyingPartyRegistrationResolver(registrations));
+	authenticationConverter.setShouldConvertGetRequests(false);
+	return authenticationConverter;
+}
+----
+
+Kotlin::
++
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun authenticationConverter(val registrations: RelyingPartyRegistrationRepository): Saml2AuthenticationTokenConverter {
+	val authenticationConverter = new Saml2AuthenticationTokenConverter(
+        DefaultRelyingPartyRegistrationResolver(registrations))
+	authenticationConverter.setShouldConvertGetRequests(false)
+	return authenticationConverter
+}
+----
+======
+
+If you must continue using `Saml2AuthenticationTokenConverter` to process GET requests, you can call `setShouldConvertGetRequests` to `true.`