nginx add_header Appends. It Doesn't Override — And That Can Remove Protection.

A recent incident in the author's nginx-based system revealed an important lesson regarding the add_header directive. The developer had implemented a baseline of security headers across every generated nginx vhost to provide a fallback for applications that send no headers of their own. However, when production encountered two X-Frame-Options values - DENY from the application and SAMEORIGIN from the baseline - browsers treated it as if the header was absent, effectively removing the protection.

Initially, the author intended to prevent applications from overriding the security headers. However, they discovered that the add_header directive does not override existing headers but instead appends them. This behavior can inadvertently remove critical protections if not handled carefully. Additionally, add_header cannot query upstream headers, meaning it has no way to check if the upstream had already sent the header. Lastly, add_header replaces the entire set of headers instead of merging them.

The author learned that to resolve this issue, they needed to map upstream headers using the $upstream_http_* variables and add_header statements, allowing the baseline headers to be inherited only when the upstream had not set the corresponding header. This change ensured that applications maintaining their own security headers would not have their protections weakened by the baseline.

The fix involved creating maps for the X-Content-Type-Options, X-Frame-Options, and Referrer-Policy headers, allowing the system to utilize the upstream values when available and fall back to the baseline when necessary.