Por Versão

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.

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=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.

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

Configuration property	Tipo	Padrão
`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` Show more	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` Show more	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` Show more	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` Show more	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` Show more	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` Show more	boolean

Configuration property

Tipo

Padrão

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.

Você também pode usar um formato simplificado, começando com um número:

Se o valor for apenas um número, ele representará o tempo em segundos.
Se o valor for um número seguido de 'ms', ele representa o tempo em milissegundos.

Em outros casos, o formato simplificado é traduzido para o formato 'java.time.Duration' para análise:

Se o valor for um número seguido de 'h', 'm' ou 's', ele é prefixado com 'PT'.
Se o valor for um número seguido de 'd', ele é prefixado com 'P'.

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=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.

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

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=true
%dev.quarkus.http.cors.origins=/.*/

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.

Referências

Enabling the CORS filter
Example CORS configuration
Allowing all origins in dev mode
Referências

Cross-Origin Resource Sharing (CORS)

Enabling the CORS filter

Example CORS configuration

Allowing all origins in dev mode

Referências

Conteúdo Relacionado

Nas mesmas extensões