リバースプロキシの背後で

server.forward-headers-strategy=native (または framework) を設定すると、アプリケーションには各リクエストが、プロキシが渡した形ではなく、クライアントが送った形で見えます。スキーム、ホスト、ポート、クライアントのアドレスです。

使う理由

サーバーの前段にあるプロキシ (nginx、Traefik、Caddy、クラウドのロードバランサー) は、通常 TLS を終端し、平文の 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

値 動作
none ヘッダーを読まない。リクエストはサーバーに届いたとおりのもの。フィルターは追加されず、ヘッダーは届いたままリクエストに残る。
native forwardedHeaderFilter Bean が追加され、信頼するプロキシのヘッダーが適用される。Spring Boot では、サーバー自身のサポート (Tomcat の RemoteIpValve)。
framework ここでは native とまったく同じ。Spring Boot では Spring の ForwardedHeaderFilter。

server.forward-headers.trusted-proxies

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) アドレスです。

ヘッダーの読み方

forwardedHeaderFilter は、すべてのフィルターの最初に実行されます (順序 -10000。セッションフィルターは -1000、セキュリティチェーンは -100)。各リクエストについて:

  1. フォワードヘッダーがない: リクエストはそのまま通ります。
  2. 相手が信頼されていない: ヘッダーは無視されます。debug ログ: Forwarded headers from 203.0.113.99 ignored: not a trusted proxy (server.forward-headers.trusted-proxies)。
  3. 相手が信頼されている: ヘッダーが適用され、その後チェーンの残りのためにリクエストから取り除かれます。debug ログ: Forwarded headers applied: https://shop.example.com。ヘッダーの値がログに記録されることはありません。

どのヘッダーか:

変わるもの:

リクエストのメンバー 元
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 リテラルなどです。残りは引き続き適用されます。

影響を受けるもの

セキュリティ

ルールと特殊なケース

Spring (Java) との対応

server.forward-headers-strategy=native
server.tomcat.remoteip.internal-proxies=10\\.0\\.12\\.\\d{1,3}

重要な違い:

関連項目