Nginx Security Headers Configuration

This guide is part of the Server & Platform Implementation Guides reference and covers the complete set of HTTP security headers in Nginx: the exact add_header directives, the inheritance trap that silently drops them, and the verification commands that prove the policy reached the wire. Nginx applies headers through a small number of directives with surprisingly sharp edges — the most common production incident is not a wrong value but a header that was correct in http {} and then vanished the moment a location block added one of its own.

Threat Model & Protocol Mechanics

HTTP security headers are server-issued instructions that the browser enforces on the client side. The server emits them once per response; the browser caches or applies them per its own enforcement model. Nginx’s job is narrow and mechanical: attach the right header lines to the right responses, including error responses, without dropping them as the request flows through http → server → location scope.

Three mechanics dominate every Nginx headers deployment, and all three cause silent failures rather than loud errors.

1. add_header inheritance is replace-not-merge. Nginx inherits add_header directives from an outer block into an inner block only if the inner block declares no add_header of its own. The moment a server or location block contains a single add_header, every inherited add_header from the parent is dropped for that block. This is documented Nginx behavior, not a bug, and it is the number-one cause of “the header is there on the homepage but missing on /api/”. A child block with its own add_header does not add to the parent set — it replaces it entirely. This is covered in depth in Nginx add_header inheritance in location blocks.

2. Headers are not emitted on error responses without always. By default add_header only attaches to a fixed set of success and redirect status codes (200, 201, 204, 206, 301, 302, 303, 304, 307, 308). A 403, 404, 500, or proxy 502 response ships with no security headers unless the directive ends in the always flag. An attacker who can force an error page onto an unhardened response gets a frame-able, sniffable page. Treat always as mandatory on every security header.

3. Scope is map, server, and location — and proxies add a fourth dimension. A map block computes a value once; server sets a per-vhost baseline; location overrides per path. When Nginx proxies to an upstream, the upstream’s own headers pass through unless stripped with proxy_hide_header, producing duplicate or conflicting header lines that browsers resolve unpredictably. The relationship between add_header and proxy_hide_header is detailed in Nginx add_header vs proxy_hide_header explained.

The replace-not-merge rule reaches one level deeper than most operators expect: an add_header placed inside an if block within a location forms its own nested scope, so it drops every add_header declared in the enclosing location, not only those inherited from server. Combined with the well-known fragility of if inside location, this makes conditional headers a frequent source of gaps — prefer a map that computes the value and a single unconditional add_header over branching with if. Directives also emit in declaration order, and Nginx never deduplicates: two add_header X-Frame-Options lines in the same scope both ship, and the browser sees two field lines.

Two spec details decide whether a correct-looking directive actually takes effect. HSTS is honored only when the response arrives over a genuinely secure transport; per RFC 6797 a browser ignores Strict-Transport-Security received over plain HTTP, so setting it on a port-80 server block accomplishes nothing — deliver it only over TLS, and let the port-80 vhost do nothing but redirect. max-age=0 is the documented HSTS kill switch: it instructs the browser to expire the pinned policy immediately, which is how you unwind a bad rollout. CSP behaves the opposite way to X-Frame-Options under duplication — when a response carries more than one Content-Security-Policy header, the browser enforces all of them simultaneously and a resource must satisfy every policy to load. A duplicate CSP from an unstripped upstream therefore makes the effective policy strictly more restrictive, silently blocking assets that the origin policy alone would allow. This is why proxy_hide_header Content-Security-Policy matters even when the two policies look identical.

Mapping headers to the attacks they neutralize:

Directive Syntax & Spec

Every security header in Nginx is set with the same directive:

add_header <field-name> "<field-value>" [always];

The always flag is the only optional token, and in a security context it is never actually optional. The table below maps each header’s directive behavior in Nginx specifically.

Common malformed-syntax gotchas: omitting the quotes around a value that contains spaces or semicolons truncates the header silently; placing always before the value is a config-parse error caught by nginx -t; and writing the directive in http {} then expecting it to survive a location that has its own add_header (it will not).

Platform-Specific Implementation

The robust pattern is a single server block that declares the full security baseline with always on every line, kept in an include file so it can be re-emitted inside any location that needs its own add_header. The block below is the complete baseline.

Nginx

server {
    listen 443 ssl;
    http2 on;
    server_name your-domain.com;

    # HSTS — enforces HTTPS for one year incl. subdomains; `always` emits it on error responses too.
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # CSP — restricts where scripts/styles/frames load from; `always` keeps the policy on 4xx/5xx pages.
    add_header Content-Security-Policy "default-src 'self'; script-src 'self'; object-src 'none'; frame-ancestors 'none'; base-uri 'self'" always;

    # X-Frame-Options — legacy clickjacking guard for browsers without frame-ancestors; `always` covers error pages that could be framed.
    add_header X-Frame-Options "SAMEORIGIN" always;

    # X-Content-Type-Options — disables MIME sniffing; `always` ensures even an error body is not reinterpreted.
    add_header X-Content-Type-Options "nosniff" always;

    # Referrer-Policy — trims the Referer header on cross-origin requests; `always` keeps it consistent on every response.
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Permissions-Policy — disables unused browser features to shrink attack surface; `always` applies it uniformly.
    add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=()" always;
}

Security impact: This block neutralizes the full first tier of client-side risk — downgrade, injection, framing, sniffing, referrer leakage, and feature abuse — on every response code. Start the Content-Security-Policy header as Content-Security-Policy-Report-Only in staging, collect violations, then rename the directive to enforce. Begin HSTS with a short max-age (such as 300) and raise it only once you have confirmed every subdomain serves HTTPS; add preload only after the long max-age is live and stable.

Apache

For the Apache equivalent of this block — Header always set with mod_headers — see Apache .htaccess & VirtualHost Hardening. The semantics differ: Apache Header set merges across scopes rather than replacing them, so the inheritance trap described above is specific to Nginx.

Cloudflare

When Nginx sits behind an edge network, push the baseline at the edge instead of (or in addition to) the origin to guarantee it reaches even cached responses; see Cloudflare Page Rules & Headers. If both layers set the same header, strip the origin’s at the edge to avoid duplicates.

When Nginx proxies, the upstream application often sets its own security headers. Left alone, Nginx forwards them and appends its own, so the client receives two conflicting X-Frame-Options lines and the browser picks one unpredictably. The safe pattern is to strip the upstream copy with proxy_hide_header, then re-assert a single hardened value with add_header ... always.

One-line verification (any platform):

curl -sI https://your-domain.com | grep -iE 'strict-transport|content-security|x-frame|x-content-type|referrer-policy|permissions-policy'

Verification & Diagnostic Workflows

Validation has two halves: prove the config is syntactically valid before reload, then prove the headers reached the wire on both success and error responses. The figure below sequences the whole gate — never advance to a reload until nginx -t is clean, and never call a deploy verified until the missing-path check confirms the headers survive an error.

1. Validate config before reload. Never reload without nginx -t:

sudo nginx -t

Expected output:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Then reload with sudo nginx -s reload (or systemctl reload nginx).

2. Inspect headers on a success response:

curl -sI https://your-domain.com

Expected (abbreviated):

HTTP/2 200
strict-transport-security: max-age=31536000; includeSubDomains
content-security-policy: default-src 'self'; script-src 'self'; object-src 'none'; frame-ancestors 'none'; base-uri 'self'
x-frame-options: SAMEORIGIN
x-content-type-options: nosniff
referrer-policy: strict-origin-when-cross-origin
permissions-policy: camera=(), microphone=(), geolocation=(), payment=()

3. Inspect headers on an error response — this is the test the always flag exists for:

curl -sI https://your-domain.com/this-path-does-not-exist

A correctly hardened server returns HTTP/2 404 with the same six headers present. If they are missing here but present in step 2, an always flag is missing somewhere.

4. Audit the full compiled config to find every header directive and catch accidental overrides:

sudo nginx -T | grep -E 'add_header|proxy_hide_header'

5. CI/CD gate. Fail the pipeline if a critical header is absent:

#!/usr/bin/env bash
set -euo pipefail
required=(strict-transport-security content-security-policy x-content-type-options)
hdrs=$(curl -fsSI "https://staging.your-domain.com" | tr 'A-Z' 'a-z')
for h in "${required[@]}"; do
  echo "$hdrs" | grep -q "^$h:" || { echo "MISSING: $h"; exit 1; }
done
echo "all required headers present"

In browser DevTools, open the Network tab, disable cache, reload, and confirm the headers appear on the document response and on a 304 Not Modified for a static asset served from the same origin.

Troubleshooting, Misconfigurations & Safe Rollback

• Headers present on / but missing inside a location. Symptom: curl -sI .../api/ shows none of the baseline headers. Cause: that location declares its own add_header, dropping all inherited ones. Fix: move the baseline into include /etc/nginx/security-headers.conf; and include it inside every location that has its own add_header. Detailed walkthrough: Nginx add_header inheritance in location blocks.
• Headers vanish on 403/404/500. Symptom: present on 200, absent on error pages. Fix: append always to every add_header. Without it, error responses ship no headers.
• Duplicate headers from an upstream. Symptom: curl -sI shows X-Frame-Options twice with conflicting values. Cause: the upstream sets the header and Nginx adds it again. Fix: proxy_hide_header X-Frame-Options; in the proxied location, then re-add the value you want with add_header ... always;. See Nginx add_header vs proxy_hide_header explained.
• proxy_hide_header stripped a header you needed. Symptom: an upstream’s legitimate Strict-Transport-Security disappeared. Fix: only hide informational headers (Server, X-Powered-By, X-AspNet-Version); never strip a security header unless you immediately re-add a hardened value.
• CSP broke inline scripts. Symptom: console reports Refused to execute inline script. Fix: stage the policy as Content-Security-Policy-Report-Only, then adopt nonces or hashes rather than 'unsafe-inline'.
• CSP suddenly blocks assets that used to load. Symptom: a stylesheet or image is refused even though the origin Content-Security-Policy allows it, and curl -sI shows two content-security-policy lines. Cause: an unstripped upstream sends its own CSP; the browser enforces both policies, so a resource must satisfy the intersection. Fix: proxy_hide_header Content-Security-Policy; in the proxied location, then set one authoritative policy with add_header ... always.
• HSTS never takes effect. Symptom: curl -sI http://your-domain.com shows the header but browsers still allow plain HTTP. Cause: the header is being served over HTTP, which RFC 6797 requires browsers to ignore. Fix: emit Strict-Transport-Security only from the listen 443 ssl block; leave the port-80 vhost as a bare return 301 https://$host$request_uri;.
• A subdomain went unreachable after enabling HSTS. Symptom: an internal host on a subdomain stopped loading in browsers that had visited the apex. Cause: includeSubDomains applies the HTTPS requirement to every subdomain, including ones not yet serving TLS. Fix: bring every subdomain onto HTTPS before adding includeSubDomains, or issue max-age=0 to expire the pinned policy while you remediate.
• nosniff broke a stylesheet or script. Symptom: a .css or .js file is refused with a MIME-type console error after adding X-Content-Type-Options: nosniff. Cause: the file is served with a wrong or generic Content-Type (often text/plain or application/octet-stream); with sniffing disabled the browser refuses to treat it as a stylesheet or module. Fix: correct the types {} mapping or default_type so the asset carries its accurate MIME type — the header is doing its job, the content type is the defect.
• Safe rollback. Keep each change in version control. To revert: restore the previous config (or comment the offending directive), run nginx -t, reload with nginx -s reload, and re-run the curl -sI checks above. Because Nginx reloads are graceful, no requests are dropped during rollback.

Frequently Asked Questions

Why do my security headers disappear in some paths but not others? A location (or server) block that contains any add_header of its own discards every add_header inherited from a parent block. Nginx replaces rather than merges. Redeclare the headers in that block, or pull them into an include file you reference everywhere.

Is the always flag really necessary if my site rarely returns errors? Yes. Without always, no security header is attached to 4xx or 5xx responses, and those are exactly the pages an attacker can often force. An unhardened 404 is frameable and sniffable. Treat always as mandatory.

Should I set both X-Frame-Options and CSP frame-ancestors? Set frame-ancestors as the authoritative control and keep X-Frame-Options: SAMEORIGIN as a fallback for older browsers that do not honor frame-ancestors. Where both are present, modern browsers obey frame-ancestors.

How do I confirm a reload actually applied the new headers? Run nginx -t, reload, then curl -sI https://your-domain.com and compare against the expected output. Add a curl against a deliberately missing path to confirm the headers survive on 404.

Why does nginx -T matter over just reading my config file? nginx -T dumps the fully resolved configuration including every include, so it reveals duplicate or shadowed add_header directives that are invisible when reading a single file.

What are the exact requirements before I add preload to HSTS? The public preload list requires max-age of at least 31536000 (one year), the includeSubDomains token, and the preload token, all served from the apex domain over HTTPS. Add preload only after that long max-age has been live and stable, because removal from the list is slow and browsers hard-fail HTTP for preloaded domains regardless of the header they currently send.

Does putting a security header in an if block work? It works but it is fragile. An add_header inside if creates a nested scope that drops the enclosing location’s own add_header directives, reintroducing the replace-not-merge gap. Compute the value in a map and emit a single unconditional add_header ... always instead of branching with if.

Related

• Server & Platform Implementation Guides — the parent reference for all server hardening.

• Nginx add_header vs proxy_hide_header explained — strip upstream headers, then re-add hardened values.

• Nginx add_header inheritance in location blocks — the replace-not-merge trap in detail.

• Content-Security-Policy essentials — the policy you stage with the CSP header above.

• HSTS deep dive — max-age, includeSubDomains, and preload.

• Apache .htaccess & VirtualHost Hardening — the Header always set equivalent.

• Nginx CSP nonces with njs & sub_filter — per-request nonce injection at the edge.

• headers_more vs add_header — error-response and removal behaviour compared.