Introduction

When Spring Boot runs behind reverse proxies or load balancers, request scheme/host/port seen by the app can differ from what clients used. Without forwarded-header handling, generated redirects and absolute URLs may use internal addresses or http instead of https. In Spring Boot 2.2, you must configure forwarded-header strategy correctly for your proxy setup.

The goal is to trust forwarded headers only from known infrastructure and ensure URL reconstruction is accurate.

Core Sections

1. Enable forwarded header support

In Spring Boot 2.2, configure behavior via properties.

server.use-forward-headers=true

Depending on deployment and container behavior, additional filter strategy may be needed.

2. Use ForwardedHeaderFilter when appropriate

1@Bean
2public FilterRegistrationBean<ForwardedHeaderFilter> forwardedHeaderFilter() {
3    FilterRegistrationBean<ForwardedHeaderFilter> bean = new FilterRegistrationBean<>();
4    bean.setFilter(new ForwardedHeaderFilter());
5    bean.setOrder(0);
6    return bean;
7}

This helps Spring MVC resolve scheme/host from X-Forwarded-* headers.

3. Validate proxy header injection

Ensure reverse proxy sends expected headers:

• X-Forwarded-For
• X-Forwarded-Proto
• X-Forwarded-Host
• X-Forwarded-Port

Test endpoint:

1@GetMapping("/debug/request")
2public Map<String, String> debug(HttpServletRequest req) {
3    return Map.of(
4        "scheme", req.getScheme(),
5        "host", req.getServerName(),
6        "port", String.valueOf(req.getServerPort())
7    );
8}

4. Security implications

Do not trust arbitrary forwarded headers from internet clients. Restrict trusted proxy chain and sanitize headers at edge.

5. Redirect and link verification

After config, verify OAuth callbacks, redirect URLs, and generated links under HTTPS front-door routing.

Common Pitfalls

• Enabling forwarded headers without confirming proxy actually sends correct values.
• Trusting spoofed X-Forwarded-* headers from untrusted clients.
• Forgetting to test redirects and callback URLs after deployment behind proxy.
• Applying duplicate forwarded-header handling in both proxy and app layers incorrectly.
• Debugging only app logs without inspecting upstream proxy config.

Summary

Behind reverse proxies, Spring Boot must be configured to interpret forwarded headers correctly or request metadata becomes inaccurate. Enable forwarded-header support, optionally register ForwardedHeaderFilter, and validate proxy behavior end-to-end. Keep trust boundaries explicit to avoid header spoofing risks. With proper setup, URL generation and redirects remain correct under load balancer frontends.

A practical way to keep this guidance valuable over time is to convert it into an executable runbook rather than treating it as static prose. The runbook should include exact prerequisites, supported tool versions, expected environment settings, and a concise verification sequence that can be run from a clean machine. For each step, include a brief expected output and one common failure signature so engineers can quickly determine whether they are on a known-good path or a known-bad path. This reduces guesswork during incidents and shortens time-to-resolution when teams rotate ownership frequently.

It also helps to maintain one minimal reproducible fixture in source control for the specific scenario covered by the article. The fixture can be a tiny script, focused test case, sample dataset, or minimal manifest depending on topic. The point is to have an artifact that demonstrates both successful behavior and a realistic failure condition in isolation. When dependency versions or infrastructure behavior change, teams can run the fixture quickly and identify whether the regression is caused by environment drift, configuration mismatch, or application logic changes. This dramatically improves debugging speed compared to investigating only full production workflows.

For long-term reliability, add one lightweight CI guardrail that targets the most failure-prone step in the flow. Good examples include schema checks, startup smoke tests, deterministic unit tests, API contract assertions, and compatibility probes. Keep guardrails fast and specific so they run on every change and produce actionable failures. If a class of issue appears repeatedly, promote the manual troubleshooting step into automation so regressions are caught before deployment. Over time, this shifts effort from reactive debugging to preventive quality control and keeps operational knowledge aligned with real-world delivery practices.