Add AuthenticationServiceException Reactive Preparation Steps

Issue gh-9429
Issue gh-12132

docs/modules/ROOT/pages/migration.adoc

@@ -1950,3 +1950,87 @@ to:
 @EnableReactiveMethodSecurity(useAuthorizationManager = false)
 ----
 ====
+
+=== Propagate ``AuthenticationServiceException``s
+
+{security-api-url}org/springframework/security/web/server/Webauthentication/AuthenticationWebFilter.html[`AuthenticationFilter`] propagates {security-api-url}org/springframework/security/authentication/AuthenticationServiceException.html[``AuthenticationServiceException``]s to the {security-api-url}org/springframework/security/web/server/ServerAuthenticationEntryPoint.html[`ServerAuthenticationEntryPoint`].
+Because ``AuthenticationServiceException``s  represent a server-side error instead of a client-side error, in 6.0, this changes to propagate them to the container.
+
+==== Configure `ServerAuthenticationFailureHandler` to rethrow ``AuthenticationServiceException``s
+
+To prepare for the 6.0 default, `httpBasic` and `oauth2ResourceServer` should be configured to rethrow ``AuthenticationServiceException``s.
+
+For each, construct the appropriate authentication entry point for `httpBasic` and for `oauth2ResourceServer`:
+
+====
+.Java
+[source,java,role="primary"]
+----
+ServerAuthenticationEntryPoint bearerEntryPoint = new BearerTokenServerAuthenticationEntryPoint();
+ServerAuthenticationEntryPoint basicEntryPoint = new HttpStatusServerEntryPoint(HttpStatus.UNAUTHORIZED);
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+val bearerEntryPoint: ServerAuthenticationEntryPoint = BearerTokenServerAuthenticationEntryPoint()
+val basicEntryPoint: ServerAuthenticationEntryPoint = HttpStatusServerEntryPoint(HttpStatus.UNAUTHORIZED)
+----
+====
+
+[NOTE]
+====
+If you use a custom `AuthenticationEntryPoint` for either or both mechanisms, use that one instead for the remaining steps.
+====
+
+Then, construct and configure a `ServerAuthenticationEntryPointFailureHandler` for each one:
+
+====
+.Java
+[source,java,role="primary"]
+----
+AuthenticationFailureHandler bearerFailureHandler = new ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint);
+bearerFailureHandler.setRethrowAuthenticationServiceException(true);
+AuthenticationFailureHandler basicFailureHandler = new ServerAuthenticationEntryPointFailureHandler(basicEntryPoint);
+basicFailureHandler.setRethrowAuthenticationServiceException(true)
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+val bearerFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint)
+bearerFailureHandler.setRethrowAuthenticationServiceException(true)
+val basicFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(basicEntryPoint)
+basicFailureHandler.setRethrowAuthenticationServiceException(true)
+----
+====
+
+Finally, wire each authentication failure handler into the DSL, like so:
+
+====
+.Java
+[source,java,role="primary"]
+----
+http
+    .httpBasic((basic) -> basic.authenticationFailureHandler(basicFailureHandler))
+    .oauth2ResourceServer((oauth2) -> oauth2.authenticationFailureHandler(bearerFailureHandler))
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+http {
+    httpBasic {
+        authenticationFailureHandler = basicFailureHandler
+    }
+    oauth2ResourceServer {
+        authenticationFailureHandler = bearerFailureHandler
+    }
+}
+----
+====
+
+[[reactive-authenticationfailurehandler-opt-out]]
+==== Opt-out Steps
+
+To opt-out of the 6.0 defaults and instead continue to pass `AuthenticationServiceException` on to ``ServerAuthenticationEntryPoint``s, you can follow the same steps as above, except set `rethrowAuthenticationServiceException` to false.