Merge pull request #36541 from sberyozkin/create-security-cors-doc

Create security cors doc

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

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
 

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
 

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

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

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]

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]

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
 

docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc

@@ -1235,7 +1235,7 @@ Future<void> 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
 

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