Preventing Nginx from Modifying HTTP Headers during Reverse Proxy

Nginx does not modify request headers by default during reverse proxying, but it adds or strips specific response headers for security and compatibility. To prevent unwanted modifications to the HTTP response stream, administrators must configure proxy_set_header directives carefully and use proxy_hide_header to remove sensitive information from upstream responses before they reach the client.

Understanding Nginx Header Behavior

When acting as a reverse proxy, Nginx sits between the client and the backend server. It is crucial to distinguish between how Nginx handles incoming requests and outgoing responses. By design, Nginx preserves the original request headers sent by the client unless explicitly told otherwise. However, it often modifies response headers received from the backend.

The most common modification involves the Host header in requests. If you do not specify a proxy_set_header Host directive, Nginx defaults to passing the Host header from the original client request. This is usually desired behavior. However, if your backend service expects a different hostname, you must override this. Conversely, many administrators mistakenly believe that proxy_hide_header can remove request headers. This is incorrect; proxy_hide_header only affects headers returned by the upstream server in the response body.

Another area of confusion is the handling of connection-related headers like Connection, Keep-Alive, and Transfer-Encoding. Nginx typically removes these from the response before sending them to the client to manage its own connection pooling efficiently. While this is standard behavior, some strict applications may rely on these headers being present exactly as the backend sent them.

Clarifying Common Misconceptions

A frequent error is assuming that setting an empty string in a proxy_set_header directive will "disable" a header. For example, proxy_set_header X-Forwarded-For ""; does not remove the header; it sets it to an empty string, which might still be processed by the backend. To completely omit a header from the request, you should simply not include it in the configuration block, or ensure no other module adds it.

Additionally, using proxy_hide_header does not stop Nginx from adding its own headers. Headers like X-Powered-By or Server are added by Nginx itself based on global settings, not by the upstream. Hiding upstream headers will not remove Nginx's identity headers.

Configuring Request Headers Correctly

To maintain the integrity of request headers, you should explicitly define what gets passed to the backend. The most robust approach is to list every header you want to forward. This prevents accidental leakage of internal headers while ensuring necessary ones like Authorization or Content-Type are preserved.

Consider the following configuration snippet for a typical reverse proxy block:

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://backend_server:8080;
        
        # Preserve the original Host header
        proxy_set_header Host $host;
        
        # Pass real client IP
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        
        # Forward SSL info if applicable
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

In this setup, Nginx forwards the Host header exactly as received from the client. It also appends the client's IP to the X-Forwarded-For header chain. If your backend application rejects requests that contain unexpected headers, you can restrict the forwarding list strictly. For instance, if you do not want to pass cookies, simply omit any proxy_set_header Cookie directive.

If you are experiencing issues with specific downstream services, such as those described in our guide on Unable to Access Nextcloud Archive via Internet with Nginx Reverse Proxy, checking header fidelity is often the first diagnostic step. Incorrect header handling can cause authentication failures or routing errors.

Hiding Response Headers from Upstream

While Nginx does not alter request headers arbitrarily, it does control which response headers are visible to the end-user. Security best practices dictate hiding implementation details from the upstream server. Use proxy_hide_header to strip sensitive data such as internal server versions or custom tracking headers.

location / {
    proxy_pass http://backend_server:8080;
    
    # Hide specific headers from the upstream response
    proxy_hide_header X-Powered-By;
    proxy_hide_header Server;
    proxy_hide_header X-Internal-ID;
}

This directive tells Nginx to drop the specified headers from the response before forwarding it to the client. Note that proxy_hide_header is case-insensitive. You cannot use this directive to hide headers that Nginx itself generates, such as Date or Content-Length, as these are required for valid HTTP communication.

For more complex scenarios involving SSL termination or certificate validation, refer to our article on NGINX Reverse Proxy: Fixing HTTPS Connection with Invalid Backend Certificate. Proper header management is often intertwined with TLS configuration, especially when dealing with Strict-Transport-Security headers.

Preserving Specific Response Headers

There are cases where you need to ensure certain response headers are not stripped by default Nginx behaviors. For example, Nginx might remove Set-Cookie headers if not configured correctly, or it might interfere with caching directives like Cache-Control. To preserve these, you generally do not need special directives because Nginx passes them through by default. However, if you have used proxy_hide_header previously, ensure you are not accidentally hiding critical caching headers.

If you need to add new headers to the response, use add_header. This is distinct from modifying upstream headers. add_header inserts headers into the response after Nginx has processed the upstream reply.

location / {
    proxy_pass http://backend_server:8080;
    
    # Add a custom header to all responses
    add_header X-Custom-Header "value";
}

This allows you to inject metadata without altering the upstream payload. Be cautious when mixing proxy_hide_header and add_header, as the order of operations matters for debugging but the final output is a clean combination of hidden and added headers.

Troubleshooting Header Issues

If your backend service behaves unexpectedly after enabling a reverse proxy, start by inspecting the actual headers received by the backend. Use tools like curl -v or browser developer tools to see what the client receives, and check backend logs to see what the server actually parses. Discrepancies here usually point to either missing proxy_set_header directives or overly aggressive proxy_hide_header rules.

Remember that Nginx buffers responses by default. This can sometimes delay header visibility in logging systems. If you require real-time header inspection, consider disabling buffering with proxy_buffering off;, though this impacts performance. Always test changes in a staging environment to ensure that downstream dependencies, such as those found in Setting Up Nginx Reverse Proxy for Home Assistant OS on KVM, continue to function correctly.

Frequently Asked Questions

Does proxy_hide_header remove request headers?

No, proxy_hide_header only affects headers returned by the upstream server in the HTTP response. It has no effect on the headers sent from the client to Nginx. To control request headers, you must use proxy_set_header.

How do I completely remove a request header?

You cannot explicitly "delete" a header once it arrives. To prevent a header from reaching the backend, simply do not include a proxy_set_header directive for it in your Nginx configuration. Nginx will not forward headers that are not explicitly set to be passed.

Why is my Set-Cookie header missing?

Nginx rarely removes Set-Cookie headers unless you have explicitly used proxy_hide_header Set-Cookie. Check your configuration for any such directives. Also, ensure that proxy_ignore_headers is not set to ignore cache-control or expiry headers that might interact with cookie persistence.

Can Nginx add headers to the request?

Yes, you can add new headers to the request using proxy_set_header. For example, proxy_set_header X-Request-ID $request_id; will append a unique ID to every request forwarded to the backend, aiding in distributed tracing and logging.

What happens if I don't set proxy_set_header Host?

If you omit proxy_set_header Host, Nginx defaults to using the Host header from the original client request. This is usually the correct behavior for virtual hosting, but if your backend requires a specific internal hostname, you must explicitly set it.