Nginx guide · All security headers

Nginx security headers: one tested configuration for all six

All six security headers on Nginx in one tested snippet: CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy and nosniff, error pages included.

  • By
  • Updated
  • 7 min read
  • Tested on nginx 1.28, 1.30 and 1.31
$ curl -sI https://example.com/missing
status
HTTP/2 404
server
nginx
content-security-policy
default-src 'self'; …
strict-transport-security
max-age=31536000; …
x-frame-options
DENY
referrer-policy
strict-origin-when-cross-origin
permissions-policy
camera=(), microphone=(), …
x-content-type-options
nosniff

All 6 present on error pages too

In short5 points
  • Put the six add_header lines, each with always, in one snippet and include it in every server block that listens on 443. Keep the port 80 block for the redirect only.
  • Any location with its own add_header drops the whole snippet. Include the snippet there too, or use add_header_inherit merge; on nginx 1.29.3 or later.
  • For pages that need a different value, such as an embeddable widget, use map blocks on $request_uri instead of location-level headers. An empty value removes the header.
  • Behind a reverse proxy, hide the application's six headers with proxy_hide_header so each one is sent once.
  • With all six passing, WebSec0 gives the headers grade 100 out of 100. Add server_tokens off; to avoid the 5-point penalty for the version in the Server header.

The short answer

Create one snippet with the six headers:

Nginx
# /etc/nginx/snippets/security-headers.conf
add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; upgrade-insecure-requests" always;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Frame-Options "DENY" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()" always;
add_header X-Content-Type-Options "nosniff" always;

Include it in the HTTPS server block, and keep port 80 for the redirect:

Nginx
server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name example.com;
    ssl_certificate     /etc/ssl/example.com/fullchain.pem;
    ssl_certificate_key /etc/ssl/example.com/privkey.pem;

    include /etc/nginx/snippets/security-headers.conf;
}
Shell
sudo nginx -t && sudo systemctl reload nginx

Every configuration on this page was run on nginx 1.28, 1.30 and 1.31 and checked with curl, on a page, a 404, a static file, a proxied application and paths with their own values.

Two of these lines need a rollout before they go live in this form. The CSP blocks every script, style and connection that is not on your own origin: start it in report-only mode, as the Content-Security-Policy guide for Nginx explains. The HSTS value is a final one: start with a short max-age, as the HSTS guide for Nginx explains.

What each line does

Header Value in the snippet WebSec0 points Details
Content-Security-Policy Only your own origin, no plugins, no framing 25 CSP on Nginx
Strict-Transport-Security HTTPS only for one year, subdomains included 20 HSTS on Nginx
X-Frame-Options No framing, for browsers without frame-ancestors 15 X-Frame-Options on Nginx
Referrer-Policy Full URL on your origin, origin only elsewhere 15 Referrer-Policy on Nginx
Permissions-Policy Camera, microphone, location, devices and sensors off 15 Permissions-Policy on Nginx
X-Content-Type-Options No MIME sniffing 10 X-Content-Type-Options on Nginx

always on every line keeps the headers on 404 and 500 pages. Without it, Nginx only adds headers to 200, 201, 204, 206, 301, 302, 303, 304, 307 and 308 responses.

Before you start

List every server block, add_header, include and proxied application in the merged configuration:

Shell
sudo nginx -T | grep -nE "listen|server_name|add_header|include|proxy_pass|fastcgi_pass|types"

Then check three things the snippet can break:

  • Scripts and styles your CSP does not allow. Run the policy in report-only mode first.
  • Subdomains without HTTPS. includeSubDomains makes browsers refuse them.
  • JavaScript served with the wrong type. nosniff blocks it. The default mime.types has no .mjs entry, for example; the X-Content-Type-Options guide for Nginx shows how to add it.

Also remove the features your site uses from the Permissions-Policy line, such as camera for a video call page, or give those pages their own value (step 4).

Step 1: include it in every HTTPS server block

Each host answers on its own, so each HTTPS server block needs the snippet, including blocks that only redirect, such as example.com to www.example.com:

Nginx
server {
    listen 443 ssl;
    server_name example.com;
    # ssl_certificate lines...

    include /etc/nginx/snippets/security-headers.conf;
    return 301 https://www.example.com$request_uri;
}

server {
    listen 443 ssl;
    server_name www.example.com;
    # ssl_certificate lines...

    include /etc/nginx/snippets/security-headers.conf;
}

Leave the snippet out of the port 80 block. Browsers ignore HSTS over plain HTTP, and that block should only redirect. In our test, the port 80 redirect carried no security header, and every HTTPS response carried all six.

Step 2: include it in every location with its own headers

add_header directives are inherited from the parent block only if the current block has none. A location that sets Cache-Control for static files loses all six security headers:

Nginx
location /assets/ {
    add_header Cache-Control "public, max-age=31536000, immutable" always;
    include /etc/nginx/snippets/security-headers.conf;
}

With the include, our test returned Cache-Control and the six headers for /assets/app.js. Without it, only Cache-Control.

On nginx 1.29.3 or later, which includes the 1.30 stable branch, add_header_inherit merge; in the server block makes nested blocks add to the parent’s headers instead of replacing them, so the include in each location is no longer needed. nginx 1.28 rejects it with unknown directive "add_header_inherit". Do not combine merge with location-level overrides of a security header: the response then carries the location’s value first and the server’s after it. Browsers apply the last Referrer-Policy and Permissions-Policy, enforce both CSPs, and treat two different X-Frame-Options as DENY, so the override does not work. Use step 4 instead.

Step 3: hide the application’s headers behind a proxy

When Nginx proxies an application that sends its own security headers, the response carries both versions, the application’s first. For some headers the first wins, for others the last, and two CSPs are both enforced. Hide the application’s headers with a second snippet:

Nginx
# /etc/nginx/snippets/proxy-hide-security-headers.conf
proxy_hide_header Content-Security-Policy;
proxy_hide_header Strict-Transport-Security;
proxy_hide_header X-Frame-Options;
proxy_hide_header Referrer-Policy;
proxy_hide_header Permissions-Policy;
proxy_hide_header X-Content-Type-Options;
Nginx
server {
    listen 443 ssl;
    server_name example.com;
    # ssl_certificate lines...

    include /etc/nginx/snippets/security-headers.conf;

    location / {
        proxy_pass http://app;
        include /etc/nginx/snippets/proxy-hide-security-headers.conf;
    }
}

In our test, the application sent weak values for all six headers, such as Referrer-Policy: unsafe-url and X-Frame-Options: SAMEORIGIN. The response carried each header once, with the snippet’s value. Use fastcgi_hide_header for PHP-FPM and uwsgi_hide_header for uWSGI. If the application must own one header, such as a CSP with per-request nonces, remove that line from both snippets instead.

Step 4: different values for some paths

Some pages need a different value: an embeddable widget, a password reset page, a video call. Overriding headers in their location brings back the inheritance problem. Instead, define the values with map blocks in the http context, and use the variables in the snippet:

Nginx
# /etc/nginx/conf.d/security-headers-maps.conf (http context)
map $request_uri $csp_header {
    default    "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; upgrade-insecure-requests";
    ~^/embed/  "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'self' https://partner.example; upgrade-insecure-requests";
}

map $request_uri $xfo_header {
    default    "DENY";
    ~^/embed/  "";
}

map $request_uri $referrer_header {
    default    "strict-origin-when-cross-origin";
    ~^/reset/  "no-referrer";
}

map $request_uri $permissions_header {
    default    "camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()";
    ~^/meet/   "camera=(self), microphone=(self), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()";
}
Nginx
# /etc/nginx/snippets/security-headers.conf
add_header Content-Security-Policy $csp_header always;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Frame-Options $xfo_header always;
add_header Referrer-Policy $referrer_header always;
add_header Permissions-Policy $permissions_header always;
add_header X-Content-Type-Options "nosniff" always;

What our test returned:

Path What changes
/ The default values
/embed/ frame-ancestors 'self' https://partner.example, and no X-Frame-Options: Nginx does not send a header whose value is empty
/reset/ Referrer-Policy: no-referrer
/meet/ camera=(self), microphone=(self)

The 404 pages under /embed/ and /reset/ got the same values as the pages. Map on $request_uri, the URL the browser asked for, rather than $uri: with an error_page directive, $uri becomes the error page’s path. In our test, a 404 under /reset/ got no-referrer with $request_uri and the default policy with $uri. The default nginx.conf of the official Docker image includes /etc/nginx/conf.d/*.conf in the http block; put the maps in any file included there.

Step 5: hide the Nginx version

By default, Nginx sends its version in the Server header, such as Server: nginx/1.30.5 (the Server header guide covers every server). WebSec0 removes 5 points from the headers grade when the Server header contains a version. Turn it off in the http block:

Nginx
http {
    server_tokens off;
    # ...
}

Our test then returned Server: nginx on every response, error pages and redirects included.

Verify it

Check that each header appears exactly once on a page, an error page and a static file. Use your own URLs:

Shell
for url in https://example.com/ https://example.com/does-not-exist https://example.com/assets/app.js; do
  echo "$url"
  for h in content-security-policy strict-transport-security x-frame-options referrer-policy permissions-policy x-content-type-options; do
    printf '  %-26s %s\n' "$h" "$(curl -sI "$url" | grep -ci "^$h:")"
  done
done

Every count should be 1. A 0 points to a location with its own add_header; a 2 to an application that sends the header too. Then open your pages with the browser console for CSP, Permissions-Policy or MIME errors, and scan the site with WebSec0.

How WebSec0 grades this configuration

The six headers make up the 100 points of the WebSec0 headers grade. With the snippet above, each one passes:

Header Points Passes when
Content-Security-Policy 25 No 'unsafe-inline' in script-src, or in default-src without script-src
Strict-Transport-Security 20 max-age of at least one year with includeSubDomains
X-Frame-Options 15 DENY or SAMEORIGIN, or frame-ancestors in the CSP
Referrer-Policy 15 The applied value is not unsafe-url or no-referrer-when-downgrade
Permissions-Policy 15 It parses and disables at least one sensitive feature with ()
X-Content-Type-Options 10 The first value is nosniff

A headers grade of A+ starts at 95. The score can also change with other headers: −5 for a version in the Server header (step 5), penalties for cookies without secure attributes (−5 per cookie without Secure, −10 at most; −3 per cookie without SameSite; −3 per session cookie without HttpOnly), and −10 for Access-Control-Allow-Origin: *. Cross-origin isolation headers add bonus points: +5 for Cross-Origin-Opener-Policy: same-origin, +3 for Cross-Origin-Embedder-Policy and +2 for Cross-Origin-Resource-Policy.

The HSTS line also counts for the TLS grade: a configuration that would earn an A+ is held at A unless HSTS has a max-age of at least one year and includeSubDomains. If the TLS grade is capped at C instead, the server still offers TLS 1.0 or 1.1: disable TLS 1.0 and 1.1 on Nginx.

Troubleshooting

Symptom Likely cause Fix
Headers missing on 404 or 500 pages A line without always Add always to every line.
Headers missing on static files That location has its own add_header Include the snippet there, or use add_header_inherit merge; (1.29.3+).
Headers missing on one host That HTTPS server block does not include the snippet Include it in every HTTPS block, redirects too.
A header appears twice The proxied application sends it too Include proxy-hide-security-headers.conf in the proxy location.
A path override has no effect Location-level add_header under merge, or a map on $uri Use map $request_uri and the variables in the snippet.
Scripts or styles stop loading The CSP or nosniff Check the browser console; start the CSP in report-only mode and fix MIME types.
unknown directive "add_header_inherit" nginx older than 1.29.3 Upgrade, or use the include approach.
WebSec0 still shows the Nginx version server_tokens off; missing or set in another context Put it in the http block and reload.

One guide per header

Every Nginx guide

Other web servers

Security headers on other servers

Questions

Frequently asked questions

Which security headers should Nginx send?

The six that WebSec0 grades: Content-Security-Policy, Strict-Transport-Security, X-Frame-Options, Referrer-Policy, Permissions-Policy and X-Content-Type-Options. Send them on every HTTPS response, error pages and static files included.

Where do I put security headers in Nginx?

In a snippet file such as /etc/nginx/snippets/security-headers.conf, included in every HTTPS server block and in every location that sets its own add_header. A header set in the http block is lost in any server or location that adds one of its own.

Why do my security headers disappear on some URLs?

Nginx inherits add_header from the parent block only when the current block has none. One add_header Cache-Control … in a location removes all six security headers there. Include the snippet in that location, or use add_header_inherit merge; on nginx 1.29.3 or later.

How do I use different security headers for one path?

Define the value with a map on $request_uri in the http block and use the variable in the snippet. A path can then get its own CSP, Referrer-Policy or Permissions-Policy, and an empty value removes a header, without location-level add_header.

How do I check all security headers at once?

Run curl -sI on a page, a 404 and a static file, and count each header: every one should appear once. Then scan the site with WebSec0, which grades all six and reports the value it received.

How do I get an A+ for headers on WebSec0 with Nginx?

Make all six headers pass, which is worth 100 points, and avoid the penalties: server_tokens off; removes the version from the Server header, and cookies need Secure, HttpOnly and SameSite. A+ starts at 95.

References

Sources

About the author

Portrait of Joshua Martinelle

Security engineer at Tenable

Security engineer at Tenable and web security researcher. He has disclosed more than 60 CVEs since 2020 and builds WebSec0.

Verify the change

Deployed it? Check it.

WebSec0 grades your TLS setup and all six security headers in a few seconds. Free, no account.

Scan your site