이 콘텐츠는 선택한 언어로 제공되지 않습니다.

Cross-Origin Resource Sharing (CORS) configuration

Red Hat build of Quarkus 3.20

Red Hat Customer Content Services

Abstract

This guide explores how to use Cross-Origin Resource Sharing (CORS) to securely manage cross-origin HTTP requests by using server-defined policies for Red Hat build of Quarkus applications. It emphasizes secure policy enforcement, dynamic origin management, and detailed header customization to control cross-origin HTTP requests. Additionally, it provides step-by-step guidance for configuring CORS filters, using regular expressions for allowed origins, and ensuring security best practices are adhered to in both development and production environments.

Providing feedback on Red Hat build of Quarkus documentation

To report an error or to improve our documentation, log in to your Red Hat Jira account and submit an issue. If you do not have a Red Hat Jira account, then you will be prompted to create an account.

Procedure

Click the following link to create a ticket.
Enter a brief description of the issue in the Summary.
Provide a detailed description of the issue or enhancement in the Description. Include a URL to where the issue occurs in the documentation.
Clicking Submit creates and routes the issue to the appropriate documentation team.

Chapter 1. Cross-Origin Resource Sharing (CORS)

Enable and configure CORS in Quarkus to specify allowed origins, methods, and headers, guiding browsers in handling cross-origin requests safely.

Cross-Origin Resource Sharing (CORS) uses HTTP headers to manage browser requests for resources from external origins securely. By specifying permitted origins, methods, and headers, Quarkus servers can use the CORS filter to enable browsers to request resources across domains while maintaining controlled access. This mechanism enhances security and supports legitimate cross-origin requests. For more on origin definitions, see the Web Origin Concept.

1.1. Enabling the CORS filter

To enforce CORS policies in your application, enable the Quarkus CORS filter by adding the following line to the src/main/resources/application.properties file:

quarkus.http.cors.enabled=true

The filter intercepts all incoming HTTP requests to identify cross-origin requests and applies the configured policy. The filter then adds CORS headers to the HTTP response, informing browsers about allowed origins and access parameters. For preflight requests, the filter returns an HTTP response immediately. For regular CORS requests, the filter denies access with an HTTP 403 status if the request violates the configured policy; otherwise, the filter forwards the request to the destination if the policy allows it.

For detailed configuration options, see the following Configuration Properties section.

lock Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property	Type	Default
`quarkus.http.cors.origins` The origins allowed for CORS. A comma-separated list of valid URLs, such as `http://www.quarkus.io,http://localhost:3000`. URLs enclosed in forward slashes are interpreted as regular expressions. Environment variable: `QUARKUS_HTTP_CORS_ORIGINS`	list of string
`quarkus.http.cors.methods` The HTTP methods allowed for CORS requests. A comma-separated list of valid HTTP methods, such as `GET,PUT,POST`. If not set, the filter allows any HTTP method by default. Default: Any HTTP request method is allowed. Environment variable: `QUARKUS_HTTP_CORS_METHODS`	list of string
`quarkus.http.cors.headers` The HTTP headers allowed for CORS requests. A comma-separated list of valid headers, such as `X-Custom,Content-Disposition`. If not set, the filter allows any header by default. Default: Any HTTP request header is allowed. Environment variable: `QUARKUS_HTTP_CORS_HEADERS`	list of string
`quarkus.http.cors.exposed-headers` The HTTP headers exposed in CORS responses. A comma-separated list of headers to expose, such as `X-Custom,Content-Disposition`. Default: No headers are exposed. Environment variable: `QUARKUS_HTTP_CORS_EXPOSED_HEADERS`	list of string
`quarkus.http.cors.access-control-max-age` The `Access-Control-Max-Age` response header value in `java.time.Duration` format. Informs the browser how long it can cache the results of a preflight request. Environment variable: `QUARKUS_HTTP_CORS_ACCESS_CONTROL_MAX_AGE`	Duration
`quarkus.http.cors.access-control-allow-credentials` The `Access-Control-Allow-Credentials` response header. Tells browsers if front-end JavaScript can be allowed to access credentials when the request’s credentials mode, `Request.credentials`, is set to `include`. Default: `true` if the `quarkus.http.cors.origins` property is set and matches the precise `Origin` header value. Environment variable: `QUARKUS_HTTP_CORS_ACCESS_CONTROL_ALLOW_CREDENTIALS`	boolean

About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

You can also use a simplified format, starting with a number:

If the value is only a number, it represents time in seconds.
If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

If the value is a number followed by h, m, or s, it is prefixed with PT.
If the value is a number followed by d, it is prefixed with P.

1.2. Example CORS configuration

The following example shows a complete CORS filter configuration, including a regular expression to define one of the origins.

quarkus.http.cors.enabled=true 1
quarkus.http.cors.origins=http://example.com,http://www.example.io,/https://([a-z0-9\\-_]+)\\\\.app\\\\.mydomain\\\\.com/ 2
quarkus.http.cors.methods=GET,PUT,POST 3
quarkus.http.cors.headers=X-Custom 4
quarkus.http.cors.exposed-headers=Content-Disposition 5
quarkus.http.cors.access-control-max-age=24H 6
quarkus.http.cors.access-control-allow-credentials=true 7

1: Enables the CORS filter.
2: Specifies allowed origins, including a regular expression.
3: Lists allowed HTTP methods for cross-origin requests.
4: Declares custom headers that clients can include in requests.
5: Identifies response headers that clients can access.
6: Sets how long preflight request results are cached.
7: Allows cookies or credentials in cross-origin requests.

When using regular expressions in an application.properties file, escape special characters with four backward slashes (\\\\) to ensure proper behavior. For example:

\\\\. matches a literal . character.
\\. matches any single character as a regular expression metadata character.

Important

Incorrectly escaped patterns can lead to unintended behavior or security vulnerabilities. Always verify regular expression syntax before deployment.

1.3. Allowing all origins in dev mode

Configuring origins during development can be challenging. To simplify development, consider allowing all origins in development mode only:

quarkus.http.cors.enabled=true
%dev.quarkus.http.cors.origins=/.*/

Warning

Only allow all origins in the development profile (%dev). Allowing unrestricted origins in production environments poses severe security risks, such as unauthorized data access or resource abuse. For production, define explicit origins in the quarkus.http.cors.origins property.

1.4. References

Legal Notice

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

이 콘텐츠는 선택한 언어로 제공되지 않습니다.

Cross-Origin Resource Sharing (CORS) configuration

Providing feedback on Red Hat build of Quarkus documentation

Chapter 1. Cross-Origin Resource Sharing (CORS)

1.1. Enabling the CORS filter

1.2. Example CORS configuration

1.3. Allowing all origins in dev mode

1.4. References

Legal Notice

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat 소개

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links