Add Support for PreFlightRequestFilter

Closes gh-18926

docs/modules/ROOT/pages/servlet/integrations/cors.adoc

@@ -184,6 +184,23 @@ fun corsConfigurationSource(): UrlBasedCorsConfigurationSource {
 ----
 ======
 
+[[cors-preflight-request-handler]]
+== `PreFlightRequestHandler` and `PreFlightRequestFilter`
+
+Spring Framework defines {spring-framework-api-url}org/springframework/web/cors/PreFlightRequestHandler.html[`PreFlightRequestHandler`] for applications that need to handle CORS preflight (`OPTIONS`) requests outside of `CorsFilter`.
+When Spring Security selects a `PreFlightRequestHandler` for a filter chain, it registers {spring-framework-api-url}org/springframework/web/filter/PreFlightRequestFilter.html[`PreFlightRequestFilter`] in the security filter chain (before `CorsFilter`) so preflight can be handled early in the request lifecycle.
+
+You can supply a handler in either of these ways:
+
+* Pass a handler directly with the `preFlightRequestHandler` attribute.
+* Register a `PreFlightRequestHandler` bean when cors is enabled and when no `CorsConfigurationSource` or `CorsFilter` is chosen for that chain.
+
+You must not configure both `configurationSource` and `preFlightRequestHandler` on the same `CorsConfigurer`; doing so results in an error at startup.
+
+The following example explicitly registers a `PreFlightRequestHandler` using the `preFlightRequestHandler`:
+
+include-code::./CorsPreFlightRequestHandlerExample[tag=preflightRequestHandler,indent=0]
+
 [WARNING]
 ====
 CORS is a browser-based security feature.

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

@@ -8,6 +8,7 @@
 * Added xref:servlet/authorization/architecture.adoc#authz-conditional-authorization-manager[ConditionalAuthorizationManager]
 * Added `when` and `withWhen` conditions to `AuthorizationManagerFactories.multiFactor()` for xref:servlet/authentication/mfa.adoc#programmatic-mfa[Programmatic MFA]
 * Added `MultiFactorCondition.WEBAUTHN_REGISTERED` to `@EnableMultiFactorAuthentication(when = ...)` for xref:servlet/authentication/mfa.adoc#mfa-when-webauthn-registered[conditionally requiring MFA for WebAuthn Users]
+* https://github.com/spring-projects/spring-security/issues/18926[gh-18926] - xref:servlet/integrations/cors.adoc[Add `PreFlightRequestFilter` Support]
 
 == OAuth 2.0
 

docs/src/test/java/org/springframework/security/docs/servlet/integrations/corspreflightrequesthandler/CorsPreFlightRequestHandlerExample.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2004-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.integrations.corspreflightrequesthandler;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.web.cors.PreFlightRequestHandler;
+
+@Configuration
+@EnableWebSecurity
+class CorsPreFlightRequestHandlerExample {
+
+	@Bean
+	PreFlightRequestHandler preFlightRequestHandler() {
+		return (request, response) -> {
+			// custom preflight handling (for example, write CORS headers or complete the response)
+		};
+	}
+
+	@Bean
+	SecurityFilterChain springSecurity(HttpSecurity http, PreFlightRequestHandler preFlightRequestHandler) {
+		// tag::preflightRequestHandler[]
+		http
+			// ..
+			.cors((cors) -> cors
+				.preFlightRequestHandler(preFlightRequestHandler)
+			);
+		return http.build();
+		// end::preflightRequestHandler[]
+	}
+
+}

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/integrations/corspreflightrequesthandler/CorsPreFlightRequestHandlerExample.kt

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2004-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.integrations.corspreflightrequesthandler
+
+import org.springframework.context.annotation.Bean
+import org.springframework.context.annotation.Configuration
+import org.springframework.security.config.annotation.web.builders.HttpSecurity
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity
+import org.springframework.security.config.annotation.web.invoke
+import org.springframework.security.web.SecurityFilterChain
+import org.springframework.web.cors.PreFlightRequestHandler
+
+@Configuration
+@EnableWebSecurity
+class CorsPreFlightRequestHandlerExample {
+
+    @Bean
+    fun preFlightRequestHandler(): PreFlightRequestHandler {
+        return PreFlightRequestHandler { _, _ ->
+            // custom preflight handling (for example, write CORS headers or complete the response)
+        }
+    }
+
+    // tag::preflightRequestHandler[]
+    @Bean
+    fun springSecurity(http: HttpSecurity, preFlightRequestHandler: PreFlightRequestHandler): SecurityFilterChain {
+        http {
+            authorizeHttpRequests {
+                authorize(anyRequest, authenticated)
+            }
+            cors {
+                this.preFlightRequestHandler = preFlightRequestHandler
+            }
+        }
+        return http.build()
+    }
+    // end::preflightRequestHandler[]
+
+}