选择指南版本

Cross-Origin 资源共享

Cross-origin resource sharing (CORS) is an HTTP-header-based mechanism that allows a server to indicate any origins other than its own, from which a browser should permit loading resources.

These origins consist of a single domain, scheme, and port. For the complete origin definition, see the Web Origin Concept page.

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:

quarkus.http.cors=true

When the filter is enabled and identifies an HTTP request as cross-origin, it will enforce the CORS policy. It will also add headers configured with the following properties before forwarding the request to its intended destination, like a servlet, Jakarta REST resource, or other endpoints.

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

Configuration property	类型	默认
`quarkus.http.cors.origins` Origins allowed for CORS Comma separated list of valid URLs, e.g.: http://www.quarkus.io,http://localhost:3000 In case an entry of the list is surrounded by forward slashes, it is interpreted as a regular expression. Environment variable: `QUARKUS_HTTP_CORS_ORIGINS` Show more	list of string
`quarkus.http.cors.methods` HTTP methods allowed for CORS Comma separated list of valid methods. ex: GET,PUT,POST The filter allows any method if this is not set. default: returns any requested method as valid Environment variable: `QUARKUS_HTTP_CORS_METHODS` Show more	list of string
`quarkus.http.cors.headers` HTTP headers allowed for CORS Comma separated list of valid headers. ex: X-Custom,Content-Disposition The filter allows any header if this is not set. default: returns any requested header as valid Environment variable: `QUARKUS_HTTP_CORS_HEADERS` Show more	list of string
`quarkus.http.cors.exposed-headers` HTTP headers exposed in CORS Comma separated list of valid headers. ex: X-Custom,Content-Disposition default: empty Environment variable: `QUARKUS_HTTP_CORS_EXPOSED_HEADERS` Show more	list of string
`quarkus.http.cors.access-control-max-age` The `Access-Control-Max-Age` response header value indicating how long the results of a pre-flight request can be cached. Environment variable: `QUARKUS_HTTP_CORS_ACCESS_CONTROL_MAX_AGE` Show more	Duration
`quarkus.http.cors.access-control-allow-credentials` The `Access-Control-Allow-Credentials` header is used to tell the browsers to expose the response to front-end JavaScript code when the request’s credentials mode Request.credentials is “include”. The value of this header will default to `true` if `quarkus.http.cors.origins` property is set and there is a match with the precise `Origin` header. Environment variable: `QUARKUS_HTTP_CORS_ACCESS_CONTROL_ALLOW_CREDENTIALS` Show more	boolean

Configuration property

类型

默认

quarkus.http.cors.origins

Origins allowed for CORS Comma separated list of valid URLs, e.g.: http://www.quarkus.io,http://localhost:3000 In case an entry of the list is surrounded by forward slashes, it is interpreted as a regular expression.

Environment variable: QUARKUS_HTTP_CORS_ORIGINS

list of string

quarkus.http.cors.methods

HTTP methods allowed for CORS Comma separated list of valid methods. ex: GET,PUT,POST The filter allows any method if this is not set. default: returns any requested method as valid

Environment variable: QUARKUS_HTTP_CORS_METHODS

list of string

quarkus.http.cors.headers

HTTP headers allowed for CORS Comma separated list of valid headers. ex: X-Custom,Content-Disposition The filter allows any header if this is not set. default: returns any requested header as valid

Environment variable: QUARKUS_HTTP_CORS_HEADERS

list of string

quarkus.http.cors.exposed-headers

HTTP headers exposed in CORS Comma separated list of valid headers. ex: X-Custom,Content-Disposition default: empty

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 indicating how long the results of a pre-flight request can be cached.

Environment variable: QUARKUS_HTTP_CORS_ACCESS_CONTROL_MAX_AGE

Duration

quarkus.http.cors.access-control-allow-credentials

The Access-Control-Allow-Credentials header is used to tell the browsers to expose the response to front-end JavaScript code when the request’s credentials mode Request.credentials is “include”. The value of this header will default to true if quarkus.http.cors.origins property is set and there is a match with the precise Origin header.

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.

An example of a full CORS filter configuration that includes a regular expression defining an allowed origin

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 forward slash characters surround it.

If you use regular expressions in an application.properties file, make sure four 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 dev mode

Configuring required origins when developing a Quarkus application requiring CORS support can be difficult. In such cases, consider allowing all origins in dev mode only in order to focus on the actual development first:

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

Enable all origins exclusively for the dev profile. It is not advisable to permit all origins in a production environment, as it can lead to significant security risks.

参考文献

CORS filter
- Support all origins in dev mode
参考文献

Cross-Origin 资源共享

CORS filter

Support all origins in dev mode

参考文献

Related content

On the same extensions