Set nginx security headers correctly

The fix/etc/nginx/conf.d/security-headers.conf

add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Content-Security-Policy "frame-ancestors 'self'" always;
add_header Cross-Origin-Opener-Policy "same-origin" always;

HSTS has its own page — see Enable HSTS, because it is the one that is hard to undo.

The inheritance rule that breaks everything

This is the most important paragraph on the page, and it is the thing most nginx configs get wrong without knowing.

add_header directives are inherited from the enclosing block only if the current block defines no add_header directives of its own. They do not merge. A single add_header in a location replaces the entire inherited set.

So this config serves no security headers under /api/:

server {
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    location /api/ {
        add_header X-Custom-Thing "value" always;   # drops BOTH headers above
    }
}

nginx does not warn. nginx -t passes. The headers are simply gone for that one path — usually the path handling the most sensitive traffic.

There are two honest fixes:

Put the headers in an include and repeat it wherever you add anything:

# /etc/nginx/snippets/security-headers.conf  — then in each block:
include snippets/security-headers.conf;
add_header X-Custom-Thing "value" always;

Or use the headers-more module (more_set_headers), which does accumulate across levels. It is a third-party module, so it needs a package that bundles it (nginx-extras on Debian and Ubuntu) or a custom build.

The include approach needs no modules and is what most people should do. Just know that “I set it in the server block” is not an answer to “does this location send it”.

always is not optional

Without always, add_header applies only to a specific list of successful status codes (200, 201, 204, 301, 302, 303, 304, 307, 308).

That means your 404s and 500s ship no security headers. Error pages are frequently where reflected content and stack traces appear, so they’re precisely where you want nosniff and a frame policy. Add always to every security header, every time.

Do not set X-XSS-Protection

Nearly every nginx hardening guide still recommends this:

add_header X-XSS-Protection "1; mode=block";   # don't

It is deprecated, and the reason matters: the header enabled a browser-side XSS filter that researchers showed could be weaponised against the page it was meant to protect. By crafting a URL that made the filter misidentify a legitimate script as an attack, an attacker could selectively disable specific scripts on a target page — turning a defence into a tool for breaking your site’s own security controls. MDN is explicit that the feature “can create XSS vulnerabilities in otherwise safe websites”.

Browsers removed the filter. The header does nothing in anything current, and it is not a harmless leftover — it is a documented footgun. If your config has it, delete the line rather than leaving it for the scanner’s benefit. A real Content-Security-Policy is the replacement.

X-Frame-Options is superseded, not urgent

frame-ancestors in CSP is the standard, and it is strictly more capable: it takes a source list rather than one origin, and it applies to <frame>, <iframe>, <embed> and <object>.

Keeping X-Frame-Options: SAMEORIGIN alongside it is harmless and covers very old browsers. Just don’t set it instead of frame-ancestors, and don’t let the two disagree — where both are present, frame-ancestors wins in browsers that support it, which will confuse whoever debugs it later.

Verify it worked

Check what is actually sent — from the outside, not the config:

curl -sI https://your.site/ | grep -iE 'content-type-options|referrer-policy|content-security-policy|x-xss'

Then check the paths, because the inheritance trap is path-specific. This is the check that finds the bug:

for p in / /api/ /static/ /nonexistent-404; do
  n=$(curl -sI "https://your.site$p" | grep -ci 'x-content-type-options')
  printf '%-22s nosniff: %s\n' "$p" "$([ "$n" -gt 0 ] && echo yes || echo MISSING)"
done

Any MISSING on a real path is an inherited-header drop. The 404 line tests whether you remembered always.

Find every block that re-declares headers:

sudo nginx -T 2>/dev/null | grep -n 'add_header'

For an external report, securityheaders.com grades a site in one request.

Before you apply this

Low risk for the headers above — nosniff and Referrer-Policy break almost nothing.

frame-ancestors 'self' breaks intentional embedding. If a partner, a status page, a payment widget, or your own admin tool iframes your site, this stops it dead with a blank frame and a console error. Check before you set it:

sudo grep -rhi 'x-frame-options\|frame-ancestors' /etc/nginx/ 2>/dev/null
awk '$0 ~ /iframe/' /var/log/nginx/access.log | head   # rough, but a start

If you need embedding, name the origins: frame-ancestors 'self' https://partner.example.

A full CSP is a project, not a line. The frame-ancestors directive above is safe because it only governs framing. Adding default-src 'self' to an existing site will break inline scripts, analytics and third-party widgets immediately. Deploy a real CSP with Content-Security-Policy-Report-Only first, collect violations, and only then enforce.

Related

• Enable HSTS — the header that is hard to take back.
• Configure TLS — HSTS assumes this is right.