Enterprise Java

Handle Forwarded Headers in Spring Boot

In production, a Spring Boot application rarely faces users directly. It usually sits behind a reverse proxy or load balancer (NGINX, an AWS ALB, an ingress controller) that terminates TLS and forwards plain HTTP to the app. From the application’s point of view, every request then appears to come from the proxy over http on an internal host, so generated links, redirects, and client IP addresses are all wrong. Forwarded headers are how the proxy tells the application what the original request looked like. This article explains what those headers are, the three strategies Spring Boot offers for handling them, and shows the difference in a small working example.

1. What are Forwarded Headers? Different Strategies in Spring Boot

1.1 What are forwarded headers?

Forwarded headers are HTTP headers a proxy adds to describe the original client request before it rewrote it. The widely used de facto set is the X-Forwarded-* family, and the standard equivalent is the single Forwarded header defined in RFC 7239.

HeaderWhat it carriesExample
X-Forwarded-ForThe original client IP address203.0.113.7
X-Forwarded-ProtoThe protocol the client usedhttps
X-Forwarded-HostThe host name the client requestedapi.example.com
X-Forwarded-PortThe port the client connected to443
ForwardedThe standard single-header form of all of the abovefor=203.0.113.7;proto=https;host=api.example.com

Without them, an app behind a TLS-terminating proxy sees http://internal-host:8080. It then builds http links in responses, redirects users from https to http, and logs the proxy’s address as the client.

1.2 Forwarding strategies in Spring Boot

Spring Boot controls this with one property, server.forward-headers-strategy, which accepts three values.

StrategyProperty valueWho processes the headersNotes
NonenoneNobodyThe headers are ignored. This is the default, although Boot switches to native on some cloud platforms.
NativenativeThe embedded server itself (for Tomcat, its RemoteIpValve)Only trusts headers from known proxy addresses; Tomcat is tuned with server.tomcat.remoteip.* properties
FrameworkframeworkSpring’s ForwardedHeaderFilter (servlet) or ForwardedHeaderTransformer (WebFlux)Works the same on any server and understands the Forwarded header, but does not check where the request came from

The practical difference is trust. With native on Tomcat, the forwarded headers are only honored when the request arrives from an internal proxy address (server.tomcat.remoteip.internal-proxies, which defaults to loopback and private ranges). With framework, any caller can send these headers and the filter will believe them, so the proxy must overwrite or strip client-supplied X-Forwarded-* headers before forwarding.

2. Code Example

2.1 Dependency

The example needs only the web starter. It assumes your project already uses spring-boot-starter-parent or the Spring Boot BOM.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

The starter brings in the embedded Tomcat and Spring MVC. Forwarded-header support is part of Spring Boot and Spring Framework themselves, so no extra library is required for any of the three strategies.

2.2 A controller that reports how the request looks

This endpoint returns what the application believes about the incoming request, so you can see exactly how each strategy changes it.

package com.example;

import jakarta.servlet.http.HttpServletRequest;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.support.ServletUriComponentsBuilder;

import java.util.LinkedHashMap;
import java.util.Map;

@SpringBootApplication
@RestController
public class ForwardedDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(ForwardedDemoApplication.class, args);
    }

    @GetMapping("/info")
    public Map<String, Object> info(HttpServletRequest request) {
        Map<String, Object> result = new LinkedHashMap<>();
        result.put("scheme", request.getScheme());
        result.put("host", request.getServerName());
        result.put("port", request.getServerPort());
        result.put("secure", request.isSecure());
        result.put("selfLink", ServletUriComponentsBuilder.fromCurrentRequestUri().build().toUriString());
        return result;
    }
}

HttpServletRequest exposes the scheme, host, port, and secure flag, which are exactly the values a proxy changes. ServletUriComponentsBuilder.fromCurrentRequestUri() builds the URL the app would put in a link or a redirect, so selfLink shows the practical effect: whether your generated links use http and the internal host, or https and the public host. The controller has no forwarded-header code at all, because the chosen strategy rewrites the request before it reaches this method.

2.3 Choose the strategy

Set the strategy in application.properties. Switch the value to none or native to compare behavior.

server.forward-headers-strategy=framework

With framework, Spring Boot registers a ForwardedHeaderFilter bean automatically, so no filter class or configuration is needed. With none the property can simply be left out, and with native Boot configures the embedded server’s own support instead.

2.4 Call it like a proxy would

Start the app, then call the endpoint twice: once directly, and once with the headers a TLS-terminating proxy would add.

curl -s http://localhost:8080/info

curl -s http://localhost:8080/info \
  -H "X-Forwarded-Proto: https" \
  -H "X-Forwarded-Host: api.example.com"

The first call has no forwarded headers, so it shows the baseline. The second adds the two headers that matter most for link generation, which simulates a request that reached a proxy over https at api.example.com and was forwarded to the app over plain HTTP.

2.5 Output

This is the expected response for the second call under each strategy. With none the headers are ignored, so the first call gives this same result.

# server.forward-headers-strategy=none
{"scheme":"http","host":"localhost","port":8080,"secure":false,"selfLink":"http://localhost:8080/info"}

# server.forward-headers-strategy=framework
{"scheme":"https","host":"api.example.com","port":443,"secure":true,"selfLink":"https://api.example.com/info"}

With none, the app still believes it is serving http://localhost:8080, so every link it generates would point at the internal address over plain HTTP. With framework, the filter rewrote the request from the headers: the scheme is https, the host is api.example.com, secure is true, and the port falls back to the default 443 because no X-Forwarded-Port was sent. As a result selfLink is the public URL, which is what a user behind the proxy should see. The native strategy reads the same X-Forwarded-* headers through the embedded server instead, and only honors them when the request comes from a trusted proxy address.

3. Conclusion

Forwarded headers let an application behind a proxy see the original scheme, host, port, and client address, and Spring Boot exposes one switch for them: server.forward-headers-strategy. Leave it at none only if nothing sits in front of the app. Use native when you want the embedded server’s trusted-proxy checks, and use framework when you want identical behavior on any server or need the standard Forwarded header. Whichever you pick, configure the proxy to overwrite client-supplied X-Forwarded-* headers, because an application that trusts them blindly can be fooled into building links for a host the attacker chose.

Yatin B.

An experienced full-stack engineer and solution architect with expertise in Core Java, Spring/Spring Boot, MVC, Security, AOP, Angular, React, cloud technologies (AWS and GCP), CI/CD (Jenkins), Docker, and Kubernetes. Skilled in designing scalable architectures and building agentic AI solutions, including AI agents, LLM integrations, agent orchestration, and enterprise AI systems.
Subscribe
Notify of
guest

This site uses Akismet to reduce spam. Learn how your comment data is processed.

0 Comments
Oldest
Newest Most Voted
Back to top button