リバースプロキシの背後で
server.forward-headers-strategy=native (または framework) を設定すると、アプリケーションには各リクエストが、プロキシが渡した形ではなく、クライアントが送った形で見えます。スキーム、ホスト、ポート、クライアントのアドレスです。
使う理由
サーバーの前段にあるプロキシ (nginx、Traefik、Caddy、クラウドのロードバランサー) は、通常 TLS を終端し、平文の HTTP をアプリケーションに渡します。何もしなければ、アプリケーションには次のように見えます。
- すべてのリクエストが
http://に見えます。そのためセッション Cookie にSecureが付かず、アプリケーションが作る URI (リダイレクト、Locationヘッダー、OAuth2 のリダイレクト URI) はhttp://で始まります。 - 公開されたホストとポートではなく、プロキシのホストとポートが見えます。
- ログやアドレスを見るルールで、プロキシのアドレスがクライアントのアドレスとして見えます。
プロキシは、ヘッダーで本当のことを伝えます。Forwarded (RFC 7239)、または X-Forwarded-Proto、X-Forwarded-Host、X-Forwarded-Port、X-Forwarded-For です。しかし、これらのヘッダーは誰でも送れます。そのため、サーバーはあなたが信頼するプロキシからのものだけを信じます。
例
# lib/resources/application.yml
server:
port: 8080
address: 127.0.0.1 # このホスト上のプロキシだけが接続できる
forward-headers-strategy: native
forward-headers:
trusted-proxies:
- 127.0.0.1
- ::1
server.port=8080
server.address=127.0.0.1
server.forward-headers-strategy=native
server.forward-headers.trusted-proxies=127.0.0.1,::1
nginx 側です。各 proxy_set_header は、クライアントが送ったものを置き換えます。
server {
listen 443 ssl;
server_name shop.example.com;
# ssl_certificate ... ;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-For $remote_addr;
}
}
コントローラーでは、リクエストが公開された姿を示すようになります。
@GetMapping('/whoami')
Map<String, Object?> whoami(ServerHttpRequest request) => {
'uri': '${request.uri}', // https://shop.example.com/whoami
'secure': request.isSecure, // true
'client': request.remoteAddress, // 127.0.0.1 ではなくブラウザーのアドレス
};
プロパティ
| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
server.forward-headers-strategy |
none / native / framework |
none |
フォワードヘッダーを適用するかどうか。 |
server.forward-headers.trusted-proxies |
List<String> |
ループバックとプライベートネットワーク | フォワードヘッダーを信じる相手。アドレスと CIDR 範囲。 |
server.forward-headers-strategy
- 型: enum。デフォルト:
none。
| 値 | 動作 |
|---|---|
none |
ヘッダーを読まない。リクエストはサーバーに届いたとおりのもの。フィルターは追加されず、ヘッダーは届いたままリクエストに残る。 |
native |
forwardedHeaderFilter Bean が追加され、信頼するプロキシのヘッダーが適用される。Spring Boot では、サーバー自身のサポート (Tomcat の RemoteIpValve)。 |
framework |
ここでは native とまったく同じ。Spring Boot では Spring の ForwardedHeaderFilter。 |
- 変更する理由: TLS を終端する、またはホストを変更するプロキシの背後でアプリケーションを動かす場合。
- 例:
server.forward-headers-strategy=native。 - 誤った値:
server.forward-headers-strategy=alwaysは、キーを名指しするバインディングの失敗で起動を止めます。 - 設定しないでください: クライアントがサーバーに直接アクセスし、どのプロキシもヘッダーを設定しない場合。デフォルトの信頼リストでは、プライベートネットワーク上のクライアントが別のアドレスや HTTPS を名乗れてしまいます。
server.forward-headers.trusted-proxies
- 型: IP アドレスと CIDR 範囲のリスト (カンマ区切りまたは YAML のリスト)。IPv4 と IPv6。デフォルト: 未設定。これは Tomcat の
internalProxiesを意味します。
127.0.0.0/8 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16
169.254.0.0/16 100.64.0.0/10 ::1/128 fc00::/7 fe80::/10
つまり、ループバック、プライベートネットワーク、リンクローカルアドレス、共有 (CGNAT) アドレスです。
- 動作: フォワードヘッダーは、直接の相手 (TCP 接続の送信元アドレス) がこのリストに含まれる場合にだけ適用されます。
X-Forwarded-Forからクライアントを見つけるためにも使われます (後述)。 - 設定するとデフォルトのリストが置き換わります。 追加されるわけではありません。プロキシが同じホストで動いているなら、ループバックを自分で含めてください。
- 単一のアドレス は一つだけの範囲です。
192.168.1.10は192.168.1.10/32です。 - IPv6 の中の IPv4 (
::ffff:10.1.2.3) は IPv4 の範囲に一致します。 - 変更する理由: 実際のプロキシに絞り込む (デフォルトはすべてのプライベートネットワークのすべてのマシンを信頼します)。またはプライベートネットワーク上にないロードバランサーのアドレスを追加する。
- 例:
server.forward-headers.trusted-proxies=10.0.12.0/24,10.0.13.7。 - 誤った値: アドレスでも範囲でもない要素は起動を止めます。たとえば
Not an address or range: 10.0.0.0/99。 - 戦略がある場合のみ。
server.forward-headers-strategy=noneでは、リストは読まれません。 - Spring Boot にはない。 Spring Boot は、正規表現である
server.tomcat.remoteip.internal-proxiesで Tomcat のリストを設定します。
ヘッダーの読み方
forwardedHeaderFilter は、すべてのフィルターの最初に実行されます (順序 -10000。セッションフィルターは -1000、セキュリティチェーンは -100)。各リクエストについて:
- フォワードヘッダーがない: リクエストはそのまま通ります。
- 相手が信頼されていない: ヘッダーは無視されます。debug ログ:
Forwarded headers from 203.0.113.99 ignored: not a trusted proxy (server.forward-headers.trusted-proxies)。 - 相手が信頼されている: ヘッダーが適用され、その後チェーンの残りのためにリクエストから取り除かれます。debug ログ:
Forwarded headers applied: https://shop.example.com。ヘッダーの値がログに記録されることはありません。
どのヘッダーか:
Forwardedがあれば、それだけが使われます。その場合X-Forwarded-*ヘッダーは無視されます。最初の要素がprotoとhost(ポート付き:host=shop.example.com:8443) を与えます。すべての要素のforがアドレスチェーンを作ります。引用符付きの値 (for="[2001:db8::7]:4711") も理解されます。- そうでなければ
X-Forwarded-Proto、X-Forwarded-Host、X-Forwarded-Port(それぞれカンマ区切りの最初の値)、そしてX-Forwarded-For(そうしたすべてのヘッダーのすべての値) です。
変わるもの:
| リクエストのメンバー | 元 |
|---|---|
uri のスキーム |
proto / X-Forwarded-Proto。http または https のみ。ホストもポートもない新しいスキームは、自身のデフォルトポート (443、80) をとる。 |
uri のホストとポート |
host / X-Forwarded-Host (host、host:port、[v6]、[v6]:port)、その後 X-Forwarded-Port (1 から 65535)。 |
isSecure |
スキームが https (または wss) なら true。 |
remoteAddress |
アドレスチェーンから得たクライアント (後述)。 |
パスとクエリは決して変わりません。
クライアントのアドレス。 チェーンは右から読みます。最も右のエントリーは、サーバーに最も近いプロキシが追加したものです。信頼するプロキシは一つずつ飛ばします。信頼するプロキシでない最初のアドレスがクライアントです。そのため X-Forwarded-For: 6.6.6.6, 198.51.100.4, 10.0.0.9 では、クライアントは 198.51.100.4 です。左の 6.6.6.6 はクライアント自身が書いたもので、信じられません。アドレスでないエントリー (unknown、難読化された名前) は、最後に見つかったアドレスで走査を止めます。
不正な値は一つずつ無視されます。 http と https 以外のスキーム、パス・空白・改行を含むホスト、範囲外のポート、壊れた IPv6 リテラルなどです。残りは引き続き適用されます。
影響を受けるもの
- TLS プロキシの背後で、セッション Cookie に
Secureが付きます (server.session.cookie.secureが未設定の場合)。セッション を参照してください。 request.uriから作る URI は、公開されたスキームとホストを使います。セキュリティスターターの OAuth2 ログインのリダイレクト URI、ログイン前に保存した URL、そしてあなたのコードがリクエストから作るすべての URI です。- CORS と WebSocket のオリジンのチェックは、
Originを公開されたオリジンと比較します。 remoteAddressを読むログやルールには、クライアントが見えます。
セキュリティ
- プロキシはヘッダーを置き換える必要があります。 クライアントが送ったものに追加するのではありません。nginx の
proxy_set_headerは置き換えます。Traefik やクラウドのロードバランサーは設定します。$proxy_add_x_forwarded_forを使うと nginx は追記します。クライアントのアドレスについては安全です (右から読まれるため) が、X-Forwarded-ProtoとX-Forwarded-Hostは、そのまま通すのではなく設定する必要があります。 - リストは小さく保ってください。 信頼するアドレスはそれぞれ、アプリケーションに何でも信じ込ませることができます。
0.0.0.0/0や::/0を入れてはいけません。 - プロキシを唯一の入口にしてください。 プロキシが同じホストで動くなら
127.0.0.1で待ち受けるか、ファイアウォールでアプリケーションのポートを塞いでください。そうしないと、プライベートネットワーク上のクライアントが直接接続し、デフォルトのリストによって信頼されてしまいます。 dart:ioの制限。 サーバーはパス中の生の\を/として読み、Content-LengthとTransfer-Encodingの両方を持つリクエストを、両方のヘッダーが見える書き方の場合にしか拒否しません。そうしたリクエストを拒否するプロキシを使ってください。組み込みサーバー を参照してください。
ルールと特殊なケース
X-Forwarded-Prefixは読まれません。 プロキシが接頭辞の下でアプリケーションを提供する場合は、プロキシに完全なパスを渡させ、server.context-pathにその接頭辞を設定してください。X-Forwarded-SslとFront-End-Httpsは読まれません。X-Forwarded-ProtoまたはForwardedを使ってください。- 複数のインスタンス。 セッションは一つのプロセスのメモリにあります。各クライアントを同じインスタンスに振り分けてください (スティッキー Cookie)。セキュリティスターターがログイン前に保持する Cookie は署名されています。すべてのインスタンスに同じ
spring.security.cookie.secretを与えてください。 - サーバーでも TLS を使う場合 (
server.ssl.*)、スキームはすでにhttpsです。ヘッダーは引き続きホストとクライアントのアドレスを変更できます。
Spring (Java) との対応
server.forward-headers-strategy=native
server.tomcat.remoteip.internal-proxies=10\\.0\\.12\\.\\d{1,3}
重要な違い:
- ここでは
nativeとframeworkは同じことをします。Tomcat のRemoteIpValveと同じく、信頼するプロキシのヘッダーだけを適用します。Spring のForwardedHeaderFilter(framework) はすべての相手を信じます。 - 信頼するプロキシは、Tomcat の正規表現 (
server.tomcat.remoteip.internal-proxies) ではなく、アドレスと CIDR 範囲のリスト (server.forward-headers.trusted-proxies) です。 X-Forwarded-PrefixとX-Forwarded-Sslは読まれません。- 未知の戦略は起動を止めます。