diff --git a/docs/downstreamdoc.yaml b/docs/downstreamdoc.yaml index ffb33542a8d58..9d70c61342ed9 100644 --- a/docs/downstreamdoc.yaml +++ b/docs/downstreamdoc.yaml @@ -17,3 +17,4 @@ guides: - src/main/asciidoc/security-openid-connect-client-reference.adoc - src/main/asciidoc/security-overview.adoc - src/main/asciidoc/security-proactive-authentication.adoc + - src/main/asciidoc/security-cors.adoc diff --git a/docs/src/main/asciidoc/http-reference.adoc b/docs/src/main/asciidoc/http-reference.adoc index 1cd8362093229..6f9ce18e86cbd 100644 --- a/docs/src/main/asciidoc/http-reference.adoc +++ b/docs/src/main/asciidoc/http-reference.adoc @@ -336,55 +336,8 @@ value will not be correct. == CORS filter -link:https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-origin resource sharing] (CORS) is a mechanism that -allows restricted resources on a web page to be requested from another domain outside the domain from which the first resource -was served. - -Quarkus comes with a CORS filter which implements the `jakarta.servlet.Filter` interface and intercepts all incoming HTTP -requests. It can be enabled in the Quarkus configuration file, `src/main/resources/application.properties`: - -[source, properties] ----- -quarkus.http.cors=true ----- - -If the filter is enabled and an HTTP request is identified as cross-origin, the CORS policy and headers defined using the -following properties will be applied before passing the request on to its actual target (servlet, Jakarta REST resource, etc.): - - -include::{generated-dir}/config/quarkus-vertx-http-config-group-cors-cors-config.adoc[leveloffset=+1, opts=optional] - -Here's what a full CORS filter configuration could look like, including a regular expression defining an allowed origin: - -[source, properties] ----- -quarkus.http.cors=true -quarkus.http.cors.origins=http://foo.com,http://www.bar.io,/https://([a-z0-9\\-_]+)\\\\.app\\\\.mydomain\\\\.com/ -quarkus.http.cors.methods=GET,PUT,POST -quarkus.http.cors.headers=X-Custom -quarkus.http.cors.exposed-headers=Content-Disposition -quarkus.http.cors.access-control-max-age=24H -quarkus.http.cors.access-control-allow-credentials=true ----- - -`/https://([a-z0-9\\-_]+)\\\\.app\\\\.mydomain\\\\.com/` is treated as a regular expression because it is surrounded by forward slash characters. - -[NOTE] -==== -If you use regular expressions in an `application.properties` file, make sure 4 backward slashes are used to represent `.` and other regular expression metadata characters as normal characters, for example, `\\\\.` represents a `.` character while `\\.` represents a metadata character allowing for any character. -==== - -=== Support all origins in devmode - -Having to configure required origins when you start developing a Quarkus application requiring CORS support can be difficult and, in such cases, you may want to allow all origins in dev mode only in order to focus on the actual development first: - -[source, properties] ----- -quarkus.http.cors=true -%dev.quarkus.http.cors.origins=/.*/ ----- - -It is important that you enable all origins only for the dev profile, allowing all origins in production is not recommended and could expose your applications to serious security issues. +To make your Quarkus application accessible to another application running on a different domain, you need to configure cross-origin resource sharing (CORS). +For more information about the CORS filter that Quarkus provides, see the Quarkus xref:security-cors.adoc#cors-filter[CORS filter] section of the "Cross-origin resource sharing" guide. == HTTP Limits Configuration diff --git a/docs/src/main/asciidoc/openapi-swaggerui.adoc b/docs/src/main/asciidoc/openapi-swaggerui.adoc index e355c05f8d687..22f2de5d34a61 100644 --- a/docs/src/main/asciidoc/openapi-swaggerui.adoc +++ b/docs/src/main/asciidoc/openapi-swaggerui.adoc @@ -529,7 +529,7 @@ For more information on styling, read this blog entry: https://quarkus.io/blog/s === Cross Origin Resource Sharing -If you plan to consume this application from a Single Page Application running on a different domain, you will need to configure CORS (Cross-Origin Resource Sharing). Please read the xref:http-reference.adoc#cors-filter[HTTP CORS documentation] for more details. +If you plan to consume this application from a Single Page Application running on a different domain, you will need to configure CORS (Cross-Origin Resource Sharing). Please read the xref:security-cors.adoc#cors-filter[CORS filter] section of the "Cross-origin resource sharing" guide for more details. == Configuration Reference diff --git a/docs/src/main/asciidoc/resteasy-reactive.adoc b/docs/src/main/asciidoc/resteasy-reactive.adoc index d3e5399bf6cbe..7f3a2bdbb0f1d 100644 --- a/docs/src/main/asciidoc/resteasy-reactive.adoc +++ b/docs/src/main/asciidoc/resteasy-reactive.adoc @@ -1867,7 +1867,7 @@ allows restricted resources on a web page to be requested from another domain ou was served. Quarkus comes with a CORS filter at the HTTP layer level. -Read the xref:http-reference.adoc#cors-filter[HTTP Reference Documentation] to learn +Read the xref:security-cors.adoc#cors-filter[CORS filter] section of the "Cross-origin resource sharing" guide to learn how to use it. == More advanced usage diff --git a/docs/src/main/asciidoc/resteasy.adoc b/docs/src/main/asciidoc/resteasy.adoc index 7a61e59a37da9..129436b4ee8d8 100644 --- a/docs/src/main/asciidoc/resteasy.adoc +++ b/docs/src/main/asciidoc/resteasy.adoc @@ -703,7 +703,7 @@ link:https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-origin re allows restricted resources on a web page to be requested from another domain outside the domain from which the first resource was served. -Quarkus comes with a CORS filter. Read the xref:http-reference.adoc#cors-filter[HTTP Reference Documentation] to learn +Quarkus comes with a CORS filter. Read the xref:security-cors.adoc#cors-filter[CORS filter] section of the "Cross-origin resource sharing" guide to learn how to use it. == GZip Support diff --git a/docs/src/main/asciidoc/security-cors.adoc b/docs/src/main/asciidoc/security-cors.adoc new file mode 100644 index 0000000000000..fb29a50239b16 --- /dev/null +++ b/docs/src/main/asciidoc/security-cors.adoc @@ -0,0 +1,69 @@ +//// +This document is maintained in the main Quarkus repository +and pull requests should be submitted there: +https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc +//// +[id="security-cors"] += Cross-origin resource sharing +include::_attributes.adoc[] +:diataxis-type: concept +:categories: security,web +:keywords: cors,http +:extensions: io.quarkus:quarkus-vertx-http + +Cross-origin resource sharing (CORS) is an HTTP-header based mechanism that allows a server to indicate any origins (domain, scheme, or port) other than its own from which a browser should permit loading resources. + +[[cors-filter]] +== CORS filter + +Quarkus provides a CORS filter which implements the `jakarta.servlet.Filter` interface and intercepts all incoming HTTP +requests. It can be enabled in the Quarkus configuration file, `src/main/resources/application.properties`: + +[source, properties] +---- +quarkus.http.cors=true +---- + +If the filter is enabled and an HTTP request is identified as cross-origin, the CORS policy and headers defined using the +following properties will be applied before passing the request on to its actual target (servlet, Jakarta REST resource, etc.): + +include::{generated-dir}/config/quarkus-vertx-http-config-group-cors-cors-config.adoc[leveloffset=+1, opts=optional] + +Here's what a full CORS filter configuration could look like, including a regular expression defining an allowed origin: + +[source, properties] +---- +quarkus.http.cors=true +quarkus.http.cors.origins=http://foo.com,http://www.bar.io,/https://([a-z0-9\\-_]+)\\\\.app\\\\.mydomain\\\\.com/ +quarkus.http.cors.methods=GET,PUT,POST +quarkus.http.cors.headers=X-Custom +quarkus.http.cors.exposed-headers=Content-Disposition +quarkus.http.cors.access-control-max-age=24H +quarkus.http.cors.access-control-allow-credentials=true +---- + +`/https://([a-z0-9\\-_]+)\\\\.app\\\\.mydomain\\\\.com/` is treated as a regular expression because it is surrounded by forward slash characters. + +[NOTE] +==== +If you use regular expressions in an `application.properties` file, make sure 4 backward slashes are used to represent `.` and other regular expression metadata characters as normal characters, for example, `\\\\.` represents a `.` character while `\\.` represents a metadata character allowing for any character. +==== + +=== Support all origins in devmode + +Having to configure required origins when you start developing a Quarkus application requiring CORS support can be difficult and, in such cases, you may want to allow all origins in dev mode only in order to focus on the actual development first: + +[source, properties] +---- +quarkus.http.cors=true +%dev.quarkus.http.cors.origins=/.*/ +---- + +It is important that you enable all origins only for the dev profile, allowing all origins in production is not recommended and could expose your applications to serious security issues. + + +== References + +* xref:security-overview.adoc[Quarkus Security overview] +* xref:http-reference.adoc[Quarkus HTTP Reference] +* link:https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS[Mozilla HTTP CORS documentation] diff --git a/docs/src/main/asciidoc/security-csrf-prevention.adoc b/docs/src/main/asciidoc/security-csrf-prevention.adoc index e4a68aa44c426..880487683477f 100644 --- a/docs/src/main/asciidoc/security-csrf-prevention.adoc +++ b/docs/src/main/asciidoc/security-csrf-prevention.adoc @@ -170,7 +170,7 @@ quarkus.csrf-reactive.cookie-http-only=false ==== If you would like to enforce CSRF prevention in a Cross-origin environment, please avoid supporting all Origins. -Restrict supported Origins to trusted Origins only, see xref:http-reference.adoc#cors-filter[Cross-origin resource sharing] for more information. +Restrict supported Origins to trusted Origins only, see xref:security-cors.adoc#cors-filter[CORS filter] section of the "Cross-origin resource sharing" guide for more information. ==== == Restrict CSRF token verification @@ -328,5 +328,5 @@ include::{generated-dir}/config/quarkus-csrf-reactive.adoc[leveloffset=+1, opts= * https://owasp.org/www-community/attacks/csrf[OWASP Cross-Site Request Forgery] * xref:resteasy-reactive.adoc[RESTEasy Reactive] * xref:qute-reference.adoc[Qute Reference] -* xref:http-reference.adoc#cors-filter[Cross-origin resource sharing] +* xref:security-cors.adoc#cors-filter[Cross-origin resource sharing] * xref:security-overview.adoc[Quarkus Security overview] diff --git a/docs/src/main/asciidoc/security-oidc-bearer-token-authentication.adoc b/docs/src/main/asciidoc/security-oidc-bearer-token-authentication.adoc index b89f012db42ef..1cde2425bc9f4 100644 --- a/docs/src/main/asciidoc/security-oidc-bearer-token-authentication.adoc +++ b/docs/src/main/asciidoc/security-oidc-bearer-token-authentication.adoc @@ -336,7 +336,7 @@ For example, here is how you can use `keycloak.js` to authenticate the users and === Cross Origin Resource Sharing -If you plan to consume your OpenID Connect `service` application from a Single Page Application running on a different domain, you will need to configure CORS (Cross-Origin Resource Sharing). Please read the xref:http-reference.adoc#cors-filter[HTTP CORS documentation] for more details. +If you plan to consume your OpenID Connect `service` application from a Single Page Application running on a different domain, you will need to configure CORS (Cross-Origin Resource Sharing). Please read the xref:security-cors.adoc#cors-filter[CORS filter] section of the "Cross-origin resource sharing" guide for more details. === Provider Endpoint configuration diff --git a/docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc b/docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc index b0889217339b6..c896b0ac85550 100644 --- a/docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc +++ b/docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc @@ -1235,7 +1235,7 @@ Future callQuarkusService() async { === Cross-origin resource sharing If you plan to consume this application from a single-page application running on a different domain, you need to configure cross-origin resource sharing (CORS). -For more information, see the xref:http-reference.adoc#cors-filter[CORS filter] section of the "HTTP reference" guide. +For more information, see the xref:security-cors.adoc#cors-filter[CORS filter] section of the "Cross-origin resource sharing" guide. === Calling Cloud provider services diff --git a/docs/src/main/asciidoc/security-overview.adoc b/docs/src/main/asciidoc/security-overview.adoc index 181c6887d4bf9..3b3c0cafa1314 100644 --- a/docs/src/main/asciidoc/security-overview.adoc +++ b/docs/src/main/asciidoc/security-overview.adoc @@ -57,7 +57,7 @@ Guidance for testing Quarkus Security features and ensuring that your Quarkus ap === Cross-origin resource sharing To make your Quarkus application accessible to another application running on a different domain, you need to configure cross-origin resource sharing (CORS). -For more information about the CORS filter that Quarkus provides, see the Quarkus xref:http-reference.adoc#cors-filter[CORS filter] section of the "HTTP reference" guide. +For more information about the CORS filter that Quarkus provides, see the Quarkus xref:security-cors.adoc#cors-filter[CORS filter] section of the "Cross-origin resource sharing" guide. [[csrf-prevention]] === Cross-Site Request Forgery (CSRF) prevention