HTTPリファレンス
このドキュメントでは、 Quarkus で使用できるさまざまな HTTP 機能について説明します。
HTTPは、ベースとなるHTTPレイヤーとしてEclipse Vert.xを使用して提供されます。サーブレットは、Vert.x上で動作するUndertowの修正バージョンを使用してサポートされ、RESTEasyは、Jakarta RESTサポートを提供するために使用されます。Undertowが存在する場合、RESTEasyはServletフィルターとして実行され、そうでない場合は、Servletの関与なしにVert.xの上で直接実行されます。
1. 静的リソースの提供
1.1. アプリケーションjarから
アプリケーションjarから静的リソースを提供するには、それらをアプリケーションの META-INF/resources
ディレクトリに配置する必要があります。この場所は、Servlet仕様で定義されている jar
ファイルのリソースの標準的な場所として選択されています。QuarkusはServletなしで使用できますが、この規約に従って、リソースをこの場所に配置する既存のコードを正しく機能させることができます。
1.2. WebJarsから
以下の JQuery のように webjar を使用している場合を考えます。
<dependency>
<groupId>org.webjars</groupId>
<artifactId>jquery</artifactId>
<version>3.1.1</version>
</dependency>
implementation("org.webjars:jquery:3.1.1")
これはどちらかといえば、 HTML ファイルに /webjars/jquery/3.1.1/jquery.min.js
の代わりに /webjars/jquery/jquery.min.js
を記述し、プロジェクトに quarkus-webjars-locator
エクステンションを追加することができます。 これを使用するには、以下をプロジェクトの依存関係に追加します。
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-webjars-locator</artifactId>
</dependency>
implementation("io.quarkus:quarkus-webjars-locator")
1.3. ローカルディレクトリから
Vert.xルーターに追加ルートをインストールすることで、静的リソースをローカルディレクトリから提供できます。
例えば、 http://localhost:8080/static/ でカレントパスから相対的に、 static/
ディレクトリからリソースを提供するには、以下のルートをインストールします:
package org.acme;
import io.quarkus.runtime.StartupEvent;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.handler.StaticHandler;
import jakarta.enterprise.event.Observes;
public class StaticResources {
void installRoute(@Observes StartupEvent startupEvent, Router router) {
router.route()
.path("/static/*")
.handler(StaticHandler.create("static/"));
}
}
1.4. HTTP圧縮
静的リソースのレスポンスボディは、デフォルトでは圧縮されません。 HTTP 圧縮のサポートは quarkus.http.enable-compression=true
によって有効にすることができます。 圧縮サポートが有効な場合、リソースのファイル名から得られる Content-Type
ヘッダーが quarkus.http.compress-media-types
で設定された圧縮メディアタイプであれば、レスポンスボディは圧縮されます。
デフォルトでは、 text/html , text/plain , text/xml , text/css , text/javascript , application/javascript のメディアタイプが圧縮されます。
|
クライアントが HTTP 圧縮をサポートしていない場合、レスポンスボディは圧縮されません。 |
1.5. その他の設定
さらに、静的リソースのインデックスページをデフォルトの index.html
から変更すること、隠しファイル(ドットファイルなど)を提供しないことを示すこと、範囲要求を無効にすること、キャッシュ対応(ヘッダーのキャッシュ、ファイルのプロパティのキャッシュなど)を設定することができます。
ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。
型 |
デフォルト |
|
---|---|---|
Set the index page when serving static resources. Environment variable: Show more |
string |
|
Set whether hidden files should be served. Environment variable: Show more |
boolean |
|
Set whether range requests (resumable downloads; media streaming) should be enabled. Environment variable: Show more |
boolean |
|
Set whether cache handling is enabled. Environment variable: Show more |
boolean |
|
Set the cache entry timeout. The default is Environment variable: Show more |
|
|
Set value for max age in caching headers. The default is Environment variable: Show more |
|
|
Set the max cache size. Environment variable: Show more |
int |
|
期間フォーマットについて
To write duration values, use the standard You can also use a simplified format, starting with a number:
In other cases, the simplified format is translated to the
|
2. コンテキストパスの設定
デフォルトでは、 Quarkus はルートコンテキストの下からコンテンツを提供します。これを変更したい場合は、 quarkus.http.root-path
設定キーを使用してコンテキストパスを設定することができます。
サーブレットを使用している場合は、quarkus.servlet.context-path
を通して Servlet のコンテキストパスを制御することができます。この項目は、上記の HTTP ルートからの相対パスであり、サーブレットと、サーブレット の上で実行されるものにのみ影響します。多くのアプリケーションでは、 Quarkus が提供するすべてのサービスに影響するため、 HTTP ルートを使用することをお勧めします。
両方を指定した場合、サーブレット以外のすべてのウェブエンドポイントは quarkus.http.root-path
からの相対的なものになり、サーブレットは {quarkus.http.root-path}/{quarkus.servlet.context-path}
からの相対的なものになります。
テストに REST Assured を使用し、quarkus.http.root-path
が設定されている場合、 Quarkus は自動的に Quarkus テストで使用するためのベース URL を設定します。そのため、テストの URL はルートパスには含めないでください。
一般に、ウェブコンテンツのパス設定は、 quarkus.http.root-path
( デフォルトでは / ) からの相対パスとして解釈されます。
-
このコンテキストルート内のパスを指定するには、スラッシュで始まらない相対パスを使用します。
-
URIを明示的に指定し、
quarkus.http.root-path
の値にかかわらず常に同じになるようにしたい場合は、スラッシュで始まる絶対パスを使用します。
例として、エクステンションが service
というパスを設定した場合、そのエンドポイントは ${quarkus.http.root-path}/service
から提供されます。 そのパスの設定を /service
に変更した場合、そのエンドポイントは /service
から提供されるようになります。
Quarkus のパス解決に関するブログ記事では、ユーザー定義パスとエクステンション定義パスの両方に対するパス解決の仕組みについて詳しく説明しています。
マネジメントインターフェース
詳しくは、 マネジメントインターフェイスのリファレンス を参照してください。 |
3. SSL によるセキュアな接続のサポート
Quarkus でセキュアな接続をサポートするには、証明書と関連するキーファイルを提供するか、キーストアを提供する必要があります。
いずれの場合も、パスワードを提供する必要があります。提供方法の詳細については、提供方法に関する段落を参照してください。
ネイティブ実行可能ファイルで SSL サポートを有効にするには、 ネイティブ実行可能ファイルでの SSL 利用ガイドを参照してください。 |
3.1. 証明書とキーファイルの提供
証明書がキーストアにロードされていない場合は、以下のプロパティーを使用して直接提供することができます。Quarkus はまず、与えられたファイルをリソースとしてロードしようとし、ファイルシステムをフォールバックとして使用します。証明書/キーペアは、起動時に新しく作成されたキーストアにロードされます。
application.properties
は次のようになります。
quarkus.http.ssl.certificate.files=/path/to/certificate
quarkus.http.ssl.certificate.key-files=/path/to/key
3.2. キーストアの提供
別の解決策としては、すでに証明書付きのデフォルトのエントリーを含むキーストアを直接提供する方法もあります。 少なくともファイルとパスワードを提供する必要があります。
証明書とキーファイルの組み合わせと同様に、 Quarkus はまず、ファイルシステムからの読み込みを試みる前に、指定されたパスをリソースとして解決しようとします。
次のプロパティーを application.properties
に追加します。
quarkus.http.ssl.certificate.key-store-file=/path/to/keystore
オプションのヒントとして、キーストアのタイプをリストのオプションの1つとして提供することができます。タイプが指定されていない場合、 Quarkus はファイル拡張子からキーストアのタイプの推測を試行し、デフォルトでは JKS タイプになります。
quarkus.http.ssl.certificate.key-store-file-type=[one of JKS, JCEKS, P12, PKCS12, PFX]
3.3. パスワードの設定
前述のいずれのシナリオでも、キーストアを作成 / ロードするためにパスワードを指定する必要があります。パスワードは、以下のプロパティーを使用して application.properties
で (平分で) 設定することができます。
quarkus.http.ssl.certificate.key-store-password=your-password
しかし、パスワードを設定ファイルに平文で提供する代わりに ( これは悪い習慣と考えられています ) 、環境変数 QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD
として ( MicroProfile Config を使用して ) パスワードを提供することができます。これは、 Kubernetes secrets と連動します。
注意: Quarkus の以前のバージョン ( 0.16 以前 ) との互換性を維持するために、デフォルトのパスワードは "password" に設定されています。したがって、これは必須のパラメーターではありません。
3.4. HTTP ポートの設定
デフォルトでは、Quarkusは、SSLで保護された接続にポート8443を、テストの実行時にはポート8444をリッスンします。
これらのポートは、 application.properties
のプロパティ quarkus.http.ssl-port
と quarkus.http.test-ssl-port
で設定することができます。
3.5. HTTP ポートの無効化
HTTP ポートを無効化して、セキュアなリクエストのみをサポートすることも可能です。これは application.properties
の quarkus.http.insecure-requests
プロパティーで行います。3 つの値を利用できます。
enabled
-
デフォルトでは、 HTTP は通常通りに動作します。
redirect
-
HTTP リクエストは HTTPS ポートにリダイレクトされます。
disabled
-
HTTP ポートは開放されません。
redirect または disabled を使用していて、SSL 証明書またはキーストアを追加していない場合は、サーバーは起動しません。
|
4. 追加の HTTP ヘッダー
すべてのレスポンスに HTTP ヘッダーを送信するようにするには、以下のプロパティーを追加します。
quarkus.http.header."X-Content-Type-Options".value=nosniff
これにより、アプリケーション内の任意のリソースに対して実行されるリクエストのレスポンスに、 X-Content-Type-Options: nosniff
HTTP ヘッダーが含まれます。
また、ヘッダーを適用する必要がある path
パターンと HTTP methods
を指定することもできます。
quarkus.http.header.Pragma.value=no-cache
quarkus.http.header.Pragma.path=/headers/pragma
quarkus.http.header.Pragma.methods=GET,HEAD
これにより、 /headers/pragma
リソースが GET
または HEAD
メソッドで呼び出された場合にのみ、 Pragma
ヘッダーが適用されます。
ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。
型 |
デフォルト |
|
---|---|---|
The path this header should be applied Environment variable: Show more |
string |
|
The value for this header configuration Environment variable: Show more |
string |
required |
The HTTP methods for this header configuration Environment variable: Show more |
list of string |
|
The path this header should be applied Environment variable: Show more |
string |
|
The value for this header configuration Environment variable: Show more |
string |
required |
The HTTP methods for this header configuration Environment variable: Show more |
list of string |
4.1. パスごとの追加の HTTP ヘッダー
パスによって異なるヘッダー値が必要な場合は、以下のように設定することができます。
quarkus.http.filter.index.header."Cache-Control"=none
quarkus.http.filter.index.matches=/index.html
これにより、 /index.html
が呼び出されたときに、 Cache-Control
のヘッダに none
が設定されます。
キーの quarkus.http.filter の後の index はグループ分けに使用され、 ( 例として ) 好きな名前を付けることができます。
|
パスには正規表現を使用でき、また HTTP ヘッダーが設定される HTTP メソッドを指定することもできます。
quarkus.http.filter.static.header."Cache-Control"=max-age=31536000
quarkus.http.filter.static.methods=GET,HEAD
quarkus.http.filter.static.matches=/static/.*
設定でパスが重複している場合、順序を指定することができます ( 値の大きい方が優先されます ) 。例えば、以下のような設定を持つ場合を考えます。
quarkus.http.filter.just-order.order=10
quarkus.http.filter.just-order.header."Cache-Control"=max-age=5000
quarkus.http.filter.just-order.matches=/paths/order
quarkus.http.filter.any-order.order=11
quarkus.http.filter.any-order.header."Cache-Control"=max-age=1
quarkus.http.filter.any-order.matches=/paths/order.*
/paths/order
が要求されたときに Cache-Control: max-age=1
ヘッダを含めます。
ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。
型 |
デフォルト |
|
---|---|---|
A regular expression for the paths matching this configuration Environment variable: Show more |
string |
required |
Additional HTTP Headers always sent in the response Environment variable: Show more |
|
|
The HTTP methods for this path configuration Environment variable: Show more |
list of string |
|
Environment variable: |
int |
|
A regular expression for the paths matching this configuration Environment variable: Show more |
string |
required |
Additional HTTP Headers always sent in the response Environment variable: Show more |
|
|
The HTTP methods for this path configuration Environment variable: Show more |
list of string |
|
Environment variable: |
int |
5. Vert.xにおける 100-continue のサポート
100-continue
をサポートするためには、 quarkus.http.handle-100-continue-automatically
オプションを明示的に有効にする必要があります。その他の情報については、 100-continue および関連する Vert.xドキュメント を参照してください。
quarkus.http.handle-100-continue-automatically=true
6. HTTP/2 サポート
HTTP/2 はデフォルトで有効になっており、 JDK11 以降で SSL が使用されている場合はブラウザーで使用されます。 JDK8 は ALPN をサポートしていないため、SSL 上で HTTP/2 を実行するために使用することはできません。 SSL が使用されていない場合でも、平分のアップグレードによる HTTP/2 はサポートされており、ブラウザー以外のクライアントでも使用することができます。
HTTP/2 を無効にしたい場合は、以下を設定します。
quarkus.http.http2=false
いくつかの設定属性はHTTP/2に固有であることに注意してください。例えば、最大ヘッダーリストサイズ (~ヘッダー) を設定するには、 quarkus.http.limits.max-header-list-size
属性を設定する必要があります。また、 quarkus.http.http2-push-enabled
を使用して、HTTP/2プッシュを有効または無効にすることもできます。
7. ランダムポートでの待ち受け
ポートを指定したくない場合は、quarkus.http.port=0
または quarkus.http.test-port=0
を指定することができます。ランダムに開いているポートが OS によって選ばれ、コンソールにログメッセージが表示されます。ポートがバインドされると、quarkus.http.port
システムプロパティーには選択された実際のポートが設定されます。そのため、これを利用して、アプリケーション内から実際のポート番号を取得できます。テスト中の場合は通常通りに URL を注入すると実際のポートで設定され、REST Assured も適切に設定されます。
これはシステムプロパティを設定するものであるため、 MicroProfile Config から quarkus.http.port にアクセスできます。ただし、注入を使用した場合は、注入される値が常に正しいとは限りません。このポート割り当ては、 Quarkus の起動時に最後に行われるものの 1 つであるため、注入されるオブジェクトがポートが開く前に待ちきれずに作成された場合、注入された値は正しくなりません。
|
8. CORS フィルター
オリジン間リソース共有 ( CORS ) は、ウェブページ上の制限されたリソースを、最初のリソースが提供されたドメイン以外の別のドメインから要求できるようにするメカニズムです。
Quarkusには、 jakarta.servlet.Filter
インターフェイスを実装し、すべての着信HTTPリクエストをインターセプトするCORSフィルターが付属しています。このフィルタは、Quarkusの設定ファイル( src/main/resources/application.properties
)で有効にすることができます:
quarkus.http.cors=true
フィルターが有効で、HTTPリクエストがクロスオリジンとして識別された場合、リクエストを実際のターゲット(サーブレット、Jakarta RESTリソースなど)に渡す前に、以下のプロパティで定義されたCORSポリシーとヘッダーが適用されます:
ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。
型 |
デフォルト |
|
---|---|---|
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: Show more |
list of string |
|
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: Show more |
list of string |
|
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: Show more |
list of string |
|
HTTP headers exposed in CORS Comma separated list of valid headers. ex: X-Custom,Content-Disposition default: empty Environment variable: Show more |
list of string |
|
The Environment variable: Show more |
||
The Environment variable: Show more |
boolean |
期間フォーマットについて
To write duration values, use the standard You can also use a simplified format, starting with a number:
In other cases, the simplified format is translated to the
|
以下は、許可されるオリジンを定義する正規表現を含む、完全な CORS フィルタ設定の例です。
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 it is surrounded by forward slash characters.
If you use regular expressions in an |
9. HTTP 制限の設定
ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。
型 |
デフォルト |
|
---|---|---|
The maximum length of all headers. Environment variable: Show more |
|
|
The maximum size of a request body. Environment variable: Show more |
|
|
The max HTTP chunk size Environment variable: Show more |
|
|
The maximum length of the initial line (e.g. Environment variable: Show more |
int |
|
The maximum length of a form attribute. Environment variable: Show more |
|
|
The maximum number of connections that are allowed at any one time. If this is set it is recommended to set a short idle timeout. Environment variable: Show more |
int |
|
Set the SETTINGS_HEADER_TABLE_SIZE HTTP/2 setting. Allows the sender to inform the remote endpoint of the maximum size of the header compression table used to decode header blocks, in octets. The encoder can select any size equal to or less than this value by using signaling specific to the header compression format inside a header block. The initial value is Environment variable: Show more |
long |
|
Set SETTINGS_MAX_CONCURRENT_STREAMS HTTP/2 setting. Indicates the maximum number of concurrent streams that the sender will allow. This limit is directional: it applies to the number of streams that the sender permits the receiver to create. Initially, there is no limit to this value. It is recommended that this value be no smaller than 100, to not unnecessarily limit parallelism. Environment variable: Show more |
long |
|
Set the SETTINGS_MAX_FRAME_SIZE HTTP/2 setting. Indicates the size of the largest frame payload that the sender is willing to receive, in octets. The initial value is Environment variable: Show more |
int |
|
Set the SETTINGS_MAX_HEADER_LIST_SIZE HTTP/2 setting. This advisory setting informs a peer of the maximum size of header list that the sender is prepared to accept, in octets. The value is based on the uncompressed size of header fields, including the length of the name and value in octets plus an overhead of 32 octets for each header field. The default value is Environment variable: Show more |
long |
|
The maximum length of all headers. Environment variable: Show more |
|
|
The maximum size of a request body. Environment variable: Show more |
|
|
The max HTTP chunk size Environment variable: Show more |
|
|
The maximum length of the initial line (e.g. Environment variable: Show more |
int |
|
The maximum length of a form attribute. Environment variable: Show more |
|
|
The maximum number of connections that are allowed at any one time. If this is set it is recommended to set a short idle timeout. Environment variable: Show more |
int |
|
Set the SETTINGS_HEADER_TABLE_SIZE HTTP/2 setting. Allows the sender to inform the remote endpoint of the maximum size of the header compression table used to decode header blocks, in octets. The encoder can select any size equal to or less than this value by using signaling specific to the header compression format inside a header block. The initial value is Environment variable: Show more |
long |
|
Set SETTINGS_MAX_CONCURRENT_STREAMS HTTP/2 setting. Indicates the maximum number of concurrent streams that the sender will allow. This limit is directional: it applies to the number of streams that the sender permits the receiver to create. Initially, there is no limit to this value. It is recommended that this value be no smaller than 100, to not unnecessarily limit parallelism. Environment variable: Show more |
long |
|
Set the SETTINGS_MAX_FRAME_SIZE HTTP/2 setting. Indicates the size of the largest frame payload that the sender is willing to receive, in octets. The initial value is Environment variable: Show more |
int |
|
Set the SETTINGS_MAX_HEADER_LIST_SIZE HTTP/2 setting. This advisory setting informs a peer of the maximum size of header list that the sender is prepared to accept, in octets. The value is based on the uncompressed size of header fields, including the length of the name and value in octets plus an overhead of 32 octets for each header field. The default value is Environment variable: Show more |
long |
About the MemorySize format
A size configuration option recognises string in this format (shown as a regular expression): |
10. HTTP アクセスログの設定
application.properties
を設定することで、 HTTP リクエストのロギングを追加することができます。ロギングには、標準の JBoss ロギング出力にロギングするか、専用ファイルにロギングするかの 2 つのオプションがあります。
ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。
型 |
デフォルト |
|
---|---|---|
If access logging is enabled. By default this will log via the standard logging facility Environment variable: Show more |
boolean |
|
A regular expression that can be used to exclude some paths from logging. Environment variable: Show more |
string |
|
The access log pattern. If this is the string
Otherwise, consult the Quarkus documentation for the full list of variables that can be used. Environment variable: Show more |
string |
|
If logging should be done to a separate file. Environment variable: Show more |
boolean |
|
The access log file base name, defaults to 'quarkus' which will give a log file name of 'quarkus.log'. Environment variable: Show more |
string |
|
The log directory to use when logging access to a file If this is not set then the current working directory is used. Environment variable: Show more |
string |
|
The log file suffix Environment variable: Show more |
string |
|
The log category to use if logging is being done via the standard log mechanism (i.e. if base-file-name is empty). Environment variable: Show more |
string |
|
If the log should be rotated daily Environment variable: Show more |
boolean |
|
属性 | 短い形式m | 長い形式 |
---|---|---|
リモート IP アドレス |
|
|
ローカル IP アドレス |
|
|
HTTP ヘッダーを除く送信済みバイト数。送信されなかった場合は '-' 。 |
|
|
HTTP ヘッダーを除く送信済みバイト数 |
|
|
リモートホスト名 |
|
|
リクエストプロトコル |
|
|
リクエストメソッド |
|
|
ローカルポート |
|
|
クエリー文字列 ( 存在する場合は '?' が前に付き、そうでない場合は空文字列 ) |
|
|
リクエストの最初の行 |
|
|
レスポンスの HTTP ステータスコード |
|
|
Common Log Format 形式の日時 |
|
|
認証されたリモートユーザー |
|
|
リクエストされた URL パス |
|
|
リクエストされた相対パス |
|
|
ローカルサーバー名 |
|
|
リクエストの処理にかかった時間 (ミリ秒 ) |
|
|
リクエストの処理にかかった時間 ( 秒単位 ) |
|
|
リクエストの処理にかかった時間 ( マイクロ秒 ) |
|
|
リクエストの処理にかかった時間 ( ナノ秒 ) |
|
|
現在のリクエストスレッド名 |
|
|
SSL 暗号 |
|
|
SSL クライアント証明書 |
|
|
SSL セッション ID |
|
|
すべてのリクエストヘッダー |
|
|
クッキーの値 |
|
|
クエリーパラメーター |
|
|
リクエストヘッダー |
|
|
レスポンスヘッダー |
|
|
Vert.x Routing Context の内部データ |
|
|
Vert.x Mapped Diagnostic Context ( MDC ) データ ( OpenTelemetry の 'traceId' など) |
|
Set |
|
11. Arbitrary customizations
Quarkus allows users to arbitrarily customize the options of HTTP servers started by Quarkus via the use of io.quarkus.vertx.http.HttpServerOptionsCustomizer
. For example, if the HTTP port needs to be set programmatically, then the following code could be used:
import jakarta.inject.Singleton;
import io.quarkus.vertx.http.HttpServerOptionsCustomizer;
@Singleton (1)
public static class MyCustomizer implements HttpServerOptionsCustomizer {
@Override
public void customizeHttpServer(HttpServerOptions options) { (2)
options.setPort(9998);
}
}
1 | By making the class a managed bean, Quarkus will take the customizer into account when it starts the Vert.x servers |
2 | In this case, we only care about customizing the HTTP server, so we just override the customizeHttpServer method, but users should be aware that HttpServerOptionsCustomizer allows configuring the HTTPS and Domain Socket servers as well |
12. リバースプロキシーの背後での実行
Quarkus は、プロキシーサーバーが関与すると変更されたり失われたりするクライアント側の情報を保持するために、追加でヘッダー ( 例: X-Forwarded-Host
) を生成するプロキシーを介してアクセスされる可能性があります。このようなシナリオでは、 Quarkus は、これらのヘッダーの値を反映して、プロトコル、ホスト、ポート、 URI などの情報を自動的に更新するように設定することができます。
この機能を有効にすると、サーバーはいくつかのセキュリティ上の問題(情報の偽装など)にさらされます。リバースプロキシーを利用している場合のみ、この機能を有効にすることを検討してください。 |
この機能を設定するには、 src/main/resources/application.properties
に以下の行を記述してください。
quarkus.http.proxy.proxy-address-forwarding=true
デファクトスタンダードのヘッダー ( Forwarded
header ) だけを考慮するためには、 src/main/resources/application.properties
に以下の行を記述してください。
quarkus.http.proxy.allow-forwarded=true
非標準のヘッダーのみを考慮するには、代わりに以下の行を src/main/resources/application.properties
に記述してください。
quarkus.http.proxy.proxy-address-forwarding=true
quarkus.http.proxy.allow-x-forwarded=true
quarkus.http.proxy.enable-forwarded-host=true
quarkus.http.proxy.enable-forwarded-prefix=true
quarkus.http.proxy.trusted-proxies=127.0.0.1 (1)
1 | 信頼できるプロキシをIPアドレス 127.0.0.1 で設定します。それ以外のアドレスからのリクエストヘッダーは無視されます。 |
標準ヘッダーと非標準ヘッダーに関連する設定はどちらも組み合わせることが できるますが、標準ヘッダーの設定が優先されます。しかしながら、これらを組み合わせることは、クライアントがプロキシにーよって上書きされない転送 ( forward ) ヘッダーを持つリクエストを偽造することができるため、セキュリティ上の影響があります。したがって、プロキシーはクライアントから予期しない X-Forwarded
ヘッダまたは X-Forwarded-*
ヘッダを取り除く必要があります。
サポートされている転送アドレスヘッダーは以下の通りです。
-
Forwarded
-
X-Forwarded-Proto
-
X-Forwarded-Host
-
X-Forwarded-Port
-
X-Forwarded-Ssl
-
X-Forwarded-Prefix
13. SameSite クッキー
例えば、クッキー名と SameSite
属性を記載することで、 Quarkus のエンドポイントによって設定された任意のクッキーに SameSite クッキープロパティを簡単に追加することができます。
quarkus.http.same-site-cookie.jwt.value=Lax
quarkus.http.same-site-cookie.session.value=Strict
この設定では、 jwt
クッキーは SameSite=Lax
属性を持ち、 session
クッキーは SameSite=Strict
属性を持つことになります。
14. サーブレットの設定
サーブレットを使用するには、明示的に quarkus-undertow
を含める必要があります。
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-undertow</artifactId>
</dependency>
implementation("io.quarkus:quarkus-undertow")
14.1. undertow-handlers.conf
undertow-handlers.conf
ファイルを使用することで、 Undertow 述語言語を利用することができます。このファイルは、アプリケーション jar の META-INF
ディレクトリーに配置する必要があります。このファイルには、Undertow 述語言語 を使用して定義されたハンドラーが含まれています。