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

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

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

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

## References

- Quarkus Security overview

- Quarkus HTTP Reference

- Mozilla HTTP CORS documentation