Forwarded headers: native strategy vs framework in Spring Boot
Forwarded headers are how a reverse proxy tells the backend what the original request looked like. The problem is that anyone can send them. Whether the backend believes them is a trust decision, and the two Spring Boot
Forwarded headers are how a reverse proxy tells the backend what the original request looked like. The problem is that anyone can send them. Whether the backend believes them is a trust decision, and the two Spring Boot strategies make opposite choices.
The news this month keeps landing on that boundary. On 5 November 2026, Lauri Koskela published a write-up on lkoskela.fi showing that Rails, Jetty, Spring Boot before 4.2, Symfony, and the Gorilla ProxyHeaders handler all read the RFC 7239 Forwarded header and trust it, while almost no proxy or CDN strips it by default (Envoy, ingress-nginx, Traefik, Apache, Caddy, Kong, Cloudflare, CloudFront all pass it through). On dev.to, a 17 November 2026 post on host headers makes the same point for X-Forwarded-Host: if the proxy forwards an attacker-controlled value and the application trusts it, absolute URLs, password-reset links, and cache keys follow the attacker. The concrete failure modes are IP allowlists and rate limits bypassed, audit logs poisoned, and password-reset links pointing at an attacker domain.
artivisi/balaka#58, merged 12 November 2026 by maintainer Endy Muhardin, is one small, deliberate choice on that boundary. It sets server.forward-headers-strategy=native as the packaged default and documents why it must not be framework. The change is 3 files, +120, -2, and replaces a property-read test with one that boots a real Tomcat connector.
What the two strategies actually do
Spring Boot offers three values for server.forward-headers-strategy: none, native, and framework.
-
none: ignore forwarded headers. Correct when the app is reached directly. -
native: hand the headers to Tomcat'sRemoteIpValve. It rewrites scheme, host, and remote address, but only when the peer is internal or loopback. -
framework: Spring'sForwardedHeaderFilterdoes the same rewrite, but trustsX-Forwarded-*from any peer that reaches the servlet container.
The difference is one line in the trust check. framework is more complete (it also handles X-Forwarded-Prefix, which native drops), so tutorials often recommend it. The balaka PR chooses native anyway, and the reason is in the next section.
Why native and not framework
ForwardedHeaderFilter trusts headers from any client. If a client can reach port 10000 directly, it can send X-Forwarded-Proto: https and X-Forwarded-For: 127.0.0.1 and the application believes it. Two concrete consequences in balaka:
- Scheme. Without a trusted proxy, the application builds
http://verification URLs and redirects the device login to the wrong scheme. The test in the PR boots a real Tomcat connector on a random port and POSTs/api/device/codefrom loopback, the position a reverse proxy occupies. WithX-Forwarded-Proto: httpsthe response'sverificationUriishttps://<host>:<port>/device; without the header it stayshttp://. - Identity. The rate limiter keys on client IP and the audit log records it. With
framework, a direct client spoofs both.nativeuses Tomcat'sRemoteIpValve, which applies the rewrite only for internal and loopback peers, so a direct client's headers are ignored.
The Ansible template deploy/ansible/roles/app/templates/application.properties.j2 already set native, so the packaged default now matches the deployment instead of disagreeing with it.
The storage path half of the same PR
The same PR makes document storage configurable without editing a packaged file:
app.storage.documents.path=${APP_DOCUMENT_STORAGE_PATH:data/documents}
A container or a hand-written systemd unit sets APP_DOCUMENT_STORAGE_PATH=/var/lib/balaka/documents and the uploads land there. The default is unchanged, so existing deployments keep working. DocumentStorageServiceTest already covers where uploads land, so the PR documents the override without adding a property-read test.
What the tests actually prove
The PR replaces ApplicationPropertiesTest, which only started a Spring context to read two property strings back. Its storage assertion was also shadowed by app.storage.documents.path in src/test/resources/application-test.properties, so it was not testing what it claimed. The replacement, DeviceAuthForwardedHeadersTest, talks HTTP to a running server:
@SpringBootTest(webEnvironment = RANDOM_PORT)@ActiveProfiles("test")- 2 tests, 0 failures, BUILD SUCCESS
- Command:
./mvnw -Dtest=DeviceAuthForwardedHeadersTest test
The difference matters for the trust question. A property-read test proves a string; a connector test proves that a header from a loopback peer changes the URL the application emits. The second is the one that catches a regression in which strategy is active.
Limits
-
nativeignoresX-Forwarded-Prefix, so URL prefixes are lost if you rely on them. balaka does not use a path prefix, so this is acceptable. If you do, you needframeworkand you must guarantee that no client reaches the container port directly, for example by binding the app to loopback and putting the proxy on the same host. -
nativetrusts loopback. If untrusted code runs on the same host as the app, it can still spoof. The trust boundary is the host, not the process. - This PR does not address the RFC 7239
Forwardedheader. Spring Boot'sForwardedHeaderFilterand Tomcat'sRemoteIpValveboth handleX-Forwarded-*by default; theForwardedheader is a separate path that the Koskela write-up flags. If your proxy passesForwardedthrough, drop or overwrite it at the proxy regardless of which strategy you choose.
The flow
native applies the rewrite only for internal and loopback peers; framework applies it for any peer.
Sources
- PR: https://github.com/artivisi/balaka/pull/58 (merged 12 November 2026, +120/-2, 3 files)
- Koskela, "Spoofed 'Forwarded' header gets past reverse proxies and CDNs" (lkoskela.fi, 5 November 2026)
- dev.to, "Understanding Host Headers..." (17 November 2026)
- dev.to, "nginx as a Reverse Proxy: A Practical Guide for Java and Spring Boot Services" (2026)
Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.