- Put the six
add_headerlines, each withalways, in one snippet and include it in everyserverblock that listens on 443. Keep the port 80 block for the redirect only. - Any
locationwith its ownadd_headerdrops the whole snippet. Include the snippet there too, or useadd_header_inherit merge;on nginx 1.29.3 or later. - For pages that need a different value, such as an embeddable widget, use
mapblocks on$request_uriinstead of location-level headers. An empty value removes the header. - Behind a reverse proxy, hide the application's six headers with
proxy_hide_headerso 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 theServerheader.
The short answer
Create one snippet with the six headers:
# /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:
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;
}sudo nginx -t && sudo systemctl reload nginxEvery 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:
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.
includeSubDomainsmakes browsers refuse them. - JavaScript served with the wrong type.
nosniffblocks it. The defaultmime.typeshas no.mjsentry, 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:
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:
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:
# /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;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:
# /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=()";
}# /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:
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:
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
doneEvery 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
Content-Security-Policy
Guide ↗Add a Content-Security-Policy header in Nginx, test it in report-only mode, keep it on every location and error page, and add nonces or hashes. Tested configs.
Strict-Transport-Security
Guide ↗Enable HSTS on Nginx: send Strict-Transport-Security from the HTTPS server only, with always, on every location and redirect, without duplicates. Tested configs.
X-Frame-Options
Guide ↗Set X-Frame-Options on Nginx with add_header and always, pair it with CSP frame-ancestors, keep it on every location and avoid duplicate headers. Tested configs.
Referrer-Policy
Guide ↗Set Referrer-Policy on Nginx with add_header and always, keep it on every location, use a stricter policy on sensitive paths and avoid duplicate headers. Tested configs.
Permissions-Policy
Guide ↗Set Permissions-Policy on Nginx with add_header and always, quote origins correctly, keep it on every location and enable a feature on one path only. Tested configs.
X-Content-Type-Options
Guide ↗Set X-Content-Type-Options: nosniff on Nginx with add_header and always, keep it on static files, and fix the MIME types it breaks, such as .mjs. Tested configs.
Other web servers
Security headers on other servers
Apache
Guide ↗All six security headers on Apache in one tested file: CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy and nosniff, error pages and proxies included.
Caddy
Guide ↗All six security headers on Caddy in one tested snippet: CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy and nosniff, proxies and error pages included.
Traefik
Guide ↗All six security headers on Traefik in one tested headers middleware: CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy and nosniff, labels or file.
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
- Module ngx_http_map_modulenginx.org
