バージョン:

Cross-Origin Resource Sharing (CORS)

Quarkus で CORS を有効にして設定し、許可されたオリジン、メソッド、ヘッダーを指定して、ブラウザーがクロスオリジンリクエストを安全に処理できるようにします。

Cross-Origin Resource Sharing (CORS) は、HTTP ヘッダーを使用して、外部オリジンからのリソースに対するブラウザーリクエストを安全に管理します。許可されたオリジン、メソッド、ヘッダーを指定して、Quarkus サーバーは CORS フィルターを使用して、制御されたアクセスを維持しながらブラウザーがドメイン間でリソースを要求できるようします。このメカニズムにより、セキュリティーが強化され、正当なクロスオリジンリクエストがサポートされます。オリジン定義の詳細は、 Web Origin Concept を参照してください。

CORS フィルターの有効化

アプリケーションで CORS ポリシーを適用するには、src/main/resources/application.properties ファイルに次の行を追加して、Quarkus CORS フィルターを有効にします。

quarkus.http.cors.enabled=true

フィルターは、すべての受信 HTTP リクエストをインターセプトしてクロスオリジンリクエストを識別し、設定されたポリシーを適用します。次に、フィルターは HTTP 応答に CORS ヘッダーを追加し、許可されたオリジンとアクセスパラメーターについてブラウザーに通知します。プリフライトリクエストの場合、フィルターは HTTP 応答を直ちに返します。通常の CORS リクエストの場合、リクエストが設定されたポリシーに違反すると、フィルターは HTTP 403 ステータスでアクセスを拒否します。それ以外の場合、ポリシーで許可されていれば、フィルターはリクエストを宛先に転送します。

詳細な設定オプションについては、次の設定プロパティーセクションを参照してください。

ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。

Configuration property	タイプ	デフォルト
`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	ブーリアン

Configuration property

タイプ

デフォルト

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

ブーリアン

期間フォーマットについて

期間の値を書くには、標準の java.time.Duration フォーマットを使います。詳細は Duration#parse() Java API documentation を参照してください。

数字で始まる簡略化した書式を使うこともできます:

数値のみの場合は、秒単位の時間を表します。
数値の後に ms が続く場合は、ミリ秒単位の時間を表します。

その他の場合は、簡略化されたフォーマットが解析のために java.time.Duration フォーマットに変換されます：

数値の後に h 、 m 、 s が続く場合は、その前に PT が付けられます。
数値の後に d が続く場合は、その前に P が付けられます。

CORS 設定の例

次の例は、オリジンの 1 つを定義する正規表現など、完全な CORS フィルター設定を示しています。

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	CORS フィルターを有効にします。
2	正規表現など、使用可能なオリジンを指定します。
3	クロスオリジンリクエストに使用可能な HTTP メソッドを表示します。
4	クライアントがリクエストに含めることができるカスタムヘッダーを宣言します。
5	クライアントがアクセスできる応答ヘッダーを識別します。
6	プリフライトリクエストの結果をキャッシュする期間を設定します。
7	クロスオリジンリクエストで Cookie または認証情報を許可します。

application.properties ファイルで正規表現を使用する場合は、適切な動作を確保するために、特殊文字を 4 つのバックスラッシュ (\\\\) でエスケープします。たとえば:

\\\\. はリテラルの . 文字として解釈されます。
\\. は、正規表現メタデータ文字として任意の 1 文字として解釈されます。

誤ってエスケープされたパターンは、意図しない動作やセキュリティーの脆弱性につながる可能性があります。デプロイメントする前に必ず正規表現の構文を確認してください。

開発モードでの全オリジンの許可

開発中にオリジンを設定するのは困難な場合があります。開発を簡素化するには、開発モードでのみすべてのオリジンを許可することを検討してください。

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

開発プロファイル (%dev) では、すべてのオリジンを許可できます。ただし、実稼働環境でオリジンを無制限に許可すると、不正なデータアクセスやリソースの不正利用など、深刻なセキュリティリスクを引き起こす可能性があります。実稼働環境では、quarkus.http.cors.origins プロパティーで明示的に許可するオリジンを定義してください。

参考資料

CORS フィルターの有効化
CORS 設定の例
開発モードでの全オリジンの許可
参考資料

Cross-Origin Resource Sharing (CORS)

CORS フィルターの有効化

CORS 設定の例

開発モードでの全オリジンの許可

参考資料

関連コンテンツ

同じエクステンションについて