From c892ce5537748b0c1a05dd1ceacc71e4fc374b1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Deleuze?= Date: Mon, 11 Sep 2023 17:00:32 +0200 Subject: [PATCH] Refine CORS documentation for wildcard processing This commit adds a reference documentation section dedicated to CORS credentialed requests and related wildcard processing. Closes gh-31143 --- .../modules/ROOT/pages/web/webflux-cors.adoc | 29 +++++++++++++++++++ .../modules/ROOT/pages/web/webmvc-cors.adoc | 29 +++++++++++++++++++ 2 files changed, 58 insertions(+) diff --git a/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc b/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc index 8aefc7d58e8a..845976b8e02c 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc @@ -75,6 +75,35 @@ To learn more from the source or to make advanced customizations, see: +[[webflux-cors-credentialed-requests]] +== Credentialed Requests +[.small]#xref:web/webmvc-cors.adoc#mvc-cors-credentialed-requests[See equivalent in the Servlet stack]# + +Using CORS with credentialed requests requires enabling `allowedCredentials`. Be aware that +this option establishes a high level of trust with the configured domains and also increases +the surface of attack of the web application by exposing sensitive user-specific information +such as cookies and CSRF tokens. + +Enabling credentials also impacts how the configured `"*"` CORS wildcards are processed: + +* Wildcards are not authorized in `allowOrigins`, but alternatively +the `allowOriginPatterns` property may be used to match to a dynamic set of origins. +* When set on `allowedHeaders` or `allowedMethods`, the `Access-Control-Allow-Headers` +and `Access-Control-Allow-Methods` response headers are handled by copying the related +headers and method specified in the CORS preflight request. +* When set on `exposedHeaders`, `Access-Control-Expose-Headers` response header is set +either to the configured list of headers or to the wildcard character. While the CORS spec +does not allow the wildcard character when `Access-Control-Allow-Credentials` is set to +`true`, most browsers support it and the response headers are not all available during the +CORS processing, so as a consequence the wildcard character is the header value used when +specified regardless of the value of the `allowCredentials` property. + +WARNING: While such wildcard configuration can be handy, it is recommended when possible to configure +a finite set of values instead to provide a higher level of security. + + + + [[webflux-cors-controller]] == `@CrossOrigin` [.small]#xref:web/webmvc-cors.adoc#mvc-cors-controller[See equivalent in the Servlet stack]# diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc index e959c141a1f6..3a8596d8250a 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc @@ -25,6 +25,35 @@ powerful workarounds based on IFRAME or JSONP. +[[mvc-cors-credentialed-requests]] +== Credentialed Requests +[.small]#xref:web/webflux-cors.adoc#webflux-cors-credentialed-requests[See equivalent in the Reactive stack]# + +Using CORS with credentialed requests requires enabling `allowedCredentials`. Be aware that +this option establishes a high level of trust with the configured domains and also increases +the surface of attack of the web application by exposing sensitive user-specific information +such as cookies and CSRF tokens. + +Enabling credentials also impacts how the configured `"*"` CORS wildcards are processed: + +* Wildcards are not authorized in `allowOrigins`, but alternatively +the `allowOriginPatterns` property may be used to match to a dynamic set of origins. +* When set on `allowedHeaders` or `allowedMethods`, the `Access-Control-Allow-Headers` +and `Access-Control-Allow-Methods` response headers are handled by copying the related +headers and method specified in the CORS preflight request. +* When set on `exposedHeaders`, `Access-Control-Expose-Headers` response header is set +either to the configured list of headers or to the wildcard character. While the CORS spec +does not allow the wildcard character when `Access-Control-Allow-Credentials` is set to +`true`, most browsers support it and the response headers are not all available during the +CORS processing, so as a consequence the wildcard character is the header value used when +specified regardless of the value of the `allowCredentials` property. + +WARNING: While such wildcard configuration can be handy, it is recommended when possible to configure +a finite set of values instead to provide a higher level of security. + + + + [[mvc-cors-processing]] == Processing [.small]#xref:web/webflux-cors.adoc#webflux-cors-processing[See equivalent in the Reactive stack]#