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

`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` です。しかし、これらのヘッダーは誰でも送れます。そのため、サーバーはあなたが信頼するプロキシからのものだけを信じます。

## 例

```yaml
# 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
```

```properties
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` は、クライアントが送ったものを置き換えます。

```nginx
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;
  }
}
```

コントローラーでは、リクエストが公開された姿を示すようになります。

```dart
@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` を意味します。

```text
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`)。各リクエストについて:

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`。ヘッダーの値がログに記録されることはありません。

どのヘッダーか:

- **`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` が未設定の場合)。[セッション](../sessions.md) を参照してください。
- `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` の両方を持つリクエストを、両方のヘッダーが見える書き方の場合にしか拒否しません。そうしたリクエストを拒否するプロキシを使ってください。[組み込みサーバー](index.md) を参照してください。

## ルールと特殊なケース

- **`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) との対応

```properties
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` は読まれません。
- 未知の戦略は起動を止めます。

## 関連項目

- [組み込みサーバー](index.md)
- [TLS (HTTPS)](ssl.md)
- [セッション](../sessions.md)
- [フィルター](../filters.md)
- [CORS](../cors.md)
- [すべてのプロパティ](../properties.md)
