Behind a reverse proxy

Set server.forward-headers-strategy=native (or framework), and the application sees each request as the client sent it, not as the proxy passed it: the scheme, the host, the port and the client's address.

Why

A proxy in front of the server (nginx, Traefik, Caddy, a cloud load balancer) usually ends TLS and passes plain HTTP to the application. Without help, the application sees:

The proxy tells the truth in headers: Forwarded (RFC 7239) or X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port and X-Forwarded-For. But anyone can send these headers. So the server believes them only from the proxies you trust.

Example

# lib/resources/application.yml
server:
  port: 8080
  address: 127.0.0.1               # only the proxy on this host can connect
  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

The nginx side. Each proxy_set_header replaces what the client sent:

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

In a controller, the request now shows the public view:

@GetMapping('/whoami')
Map<String, Object?> whoami(ServerHttpRequest request) => {
  'uri': '${request.uri}',            // https://shop.example.com/whoami
  'secure': request.isSecure,         // true
  'client': request.remoteAddress,    // the browser's address, not 127.0.0.1
};

Properties

Key Type Default Meaning
server.forward-headers-strategy none / native / framework none Whether the forwarded headers are applied.
server.forward-headers.trusted-proxies List<String> loopback and private networks Whose forwarded headers are believed: addresses and CIDR ranges.

server.forward-headers-strategy

Value What happens
none The headers are not read. The request is what reached the server. No filter is added; the headers stay in the request as they came.
native The forwardedHeaderFilter bean is added: the headers of trusted proxies are applied. In Spring Boot: the server's own support (Tomcat's RemoteIpValve).
framework Exactly the same as native here. In Spring Boot: Spring's 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

That is loopback, the private networks, link-local addresses and shared (CGNAT) addresses.

How the headers are read

The forwardedHeaderFilter runs first of all filters (order -10000; the session filter is at -1000, the security chain at -100). For each request:

  1. No forwarded header: the request passes as it is.
  2. The peer is not trusted: the headers are ignored. Debug log: Forwarded headers from 203.0.113.99 ignored: not a trusted proxy (server.forward-headers.trusted-proxies).
  3. The peer is trusted: the headers are applied, then removed from the request for the rest of the chain. Debug log: Forwarded headers applied: https://shop.example.com. Header values are never logged.

Which headers:

What changes:

Request member From
uri scheme proto / X-Forwarded-Proto: only http or https. A new scheme without a host or port takes its own default port (443, 80).
uri host and port host / X-Forwarded-Host (host, host:port, [v6], [v6]:port), then X-Forwarded-Port (1 to 65535).
isSecure true when the scheme is https (or wss).
remoteAddress the client, from the address chain (below).

The path and the query never change.

The client's address. The chain is read from the right: the rightmost entry was added by the proxy nearest to the server. Each trusted proxy is skipped. The first address that is not a trusted proxy is the client. So with X-Forwarded-For: 6.6.6.6, 198.51.100.4, 10.0.0.9, the client is 198.51.100.4: the 6.6.6.6 on the left was written by the client itself and is not believed. An entry that is no address (unknown, an obfuscated name) stops the walk at the last address found.

Invalid values are ignored, one by one: a scheme other than http and https, a host with a path, a space or a line break, a port out of range, a broken IPv6 literal. The rest still applies.

What it affects

Security

Rules and edge cases

In Spring (Java)

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

Differences that matter:

See also