From 8d76ae0844d3b679a852ca73a3b7c01f6b6eae04 Mon Sep 17 00:00:00 2001 From: wonderfulrosemari Date: Thu, 19 Feb 2026 02:06:19 +0900 Subject: [PATCH] Document multipart CSRF header option Closes gh-4265 Signed-off-by: wonderfulrosemari --- .../ROOT/pages/features/exploits/csrf.adoc | 15 ++++++++++++--- .../ROOT/pages/reactive/exploits/csrf.adoc | 3 ++- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/modules/ROOT/pages/features/exploits/csrf.adoc b/docs/modules/ROOT/pages/features/exploits/csrf.adoc index 34184006af..553719407b 100644 --- a/docs/modules/ROOT/pages/features/exploits/csrf.adoc +++ b/docs/modules/ROOT/pages/features/exploits/csrf.adoc @@ -337,8 +337,9 @@ Protecting multipart requests (file uploads) from CSRF attacks causes a https:// To prevent a CSRF attack from occurring, the body of the HTTP request must be read to obtain the actual CSRF token. However, reading the body means that the file is uploaded, which means an external site can upload a file. -There are two options to using CSRF protection with multipart/form-data: +There are three options to using CSRF protection with multipart/form-data: +* <> * <> * <> @@ -350,9 +351,17 @@ Before you integrate Spring Security's CSRF protection with multipart file uploa More information about using multipart forms with Spring, see the https://docs.spring.io/spring/docs/5.2.x/spring-framework-reference/web.html#mvc-multipart[1.1.11. Multipart Resolver] section of the Spring reference and the https://docs.spring.io/spring/docs/5.2.x/javadoc-api/org/springframework/web/multipart/support/MultipartFilter.html[`MultipartFilter` Javadoc]. ==== +[[csrf-considerations-multipart-header]] +==== Include CSRF Token in an HTTP Request Header +When JavaScript is available, you can submit multipart requests by sending the CSRF token in an HTTP request header. +This avoids placing the token in the URL and avoids processing multipart request bodies before CSRF validation. +This is generally the preferred approach for browser applications with JavaScript clients. + +See xref:servlet/exploits/csrf.adoc#csrf-integration-javascript-other[JavaScript applications] for Servlet applications and xref:reactive/exploits/csrf.adoc#webflux-csrf-include-ajax[AJAX and JSON Requests] for Reactive applications. + [[csrf-considerations-multipart-body]] ==== Place CSRF Token in the Body -The first option is to include the actual CSRF token in the body of the request. +Another option is to include the actual CSRF token in the body of the request. By placing the CSRF token in the body, the body is read before authorization is performed. This means that anyone can place temporary files on your server. However, only authorized users can submit a file that is processed by your application. @@ -360,7 +369,7 @@ In general, this is the recommended approach, because the temporary file upload [[csrf-considerations-multipart-url]] ==== Include CSRF Token in URL -If letting unauthorized users upload temporary files is not acceptable, an alternative is to include the expected CSRF token as a query parameter in the action attribute of the form. +If letting unauthorized users upload temporary files is not acceptable and JavaScript is not available, an alternative is to include the expected CSRF token as a query parameter in the action attribute of the form. The disadvantage to this approach is that query parameters can be leaked. More generally, it is considered best practice to place sensitive data within the body or headers to ensure it is not leaked. You can find additional information in https://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15.1.3[RFC 2616 Section 15.1.3 Encoding Sensitive Information in URI's]. diff --git a/docs/modules/ROOT/pages/reactive/exploits/csrf.adoc b/docs/modules/ROOT/pages/reactive/exploits/csrf.adoc index f4a1ca0d1e..121ae713d9 100644 --- a/docs/modules/ROOT/pages/reactive/exploits/csrf.adoc +++ b/docs/modules/ROOT/pages/reactive/exploits/csrf.adoc @@ -391,7 +391,8 @@ For details, see the <> section. [[webflux-csrf-considerations-multipart]] === Multipart (file upload) We have xref:features/exploits/csrf.adoc#csrf-considerations-multipart[already discussed] how protecting multipart requests (file uploads) from CSRF attacks causes a https://en.wikipedia.org/wiki/Chicken_or_the_egg[chicken and the egg] problem. -This section discusses how to implement placing the CSRF token in the <> and <> within a WebFlux application. +When JavaScript is available, we _recommend_ including the CSRF token in an HTTP request header (see <>) to side-step the issue. +If JavaScript is not available, this section discusses how to place the CSRF token in the <> and <> within a WebFlux application. [NOTE] ====