# 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.

Author: Joshua Martinelle, Security engineer at Tenable (https://www.websec0.com/guides/authors/joshua-martinelle/)
Canonical: https://www.websec0.com/guides/security-headers/nginx/
Updated: 2026-10-17
Tested on: nginx 1.28, 1.30 and 1.31

## In short

- 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;
}
```

```sh
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](/guides/content-security-policy/nginx/)
explains. The HSTS value is a final one: start with a short `max-age`, as the
[HSTS guide for Nginx](/guides/strict-transport-security/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](/guides/content-security-policy/nginx/) |
| Strict-Transport-Security | HTTPS only for one year, subdomains included | 20 | [HSTS on Nginx](/guides/strict-transport-security/nginx/) |
| X-Frame-Options | No framing, for browsers without `frame-ancestors` | 15 | [X-Frame-Options on Nginx](/guides/x-frame-options/nginx/) |
| Referrer-Policy | Full URL on your origin, origin only elsewhere | 15 | [Referrer-Policy on Nginx](/guides/referrer-policy/nginx/) |
| Permissions-Policy | Camera, microphone, location, devices and sensors off | 15 | [Permissions-Policy on Nginx](/guides/permissions-policy/nginx/) |
| X-Content-Type-Options | No MIME sniffing | 10 | [X-Content-Type-Options on Nginx](/guides/x-content-type-options/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:

```sh
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](/guides/x-content-type-options/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](/guides/server/) 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:

```sh
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](/guides/set-cookie/) (−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: *`](/guides/access-control-allow-origin/). [Cross-origin isolation headers](/guides/cross-origin-isolation/) 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](/guides/tls-versions/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. |

## 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.

## Sources

- [Module ngx_http_headers_module: add_header and add_header_inherit](https://nginx.org/en/docs/http/ngx_http_headers_module.html), nginx.org
- [Module ngx_http_map_module](https://nginx.org/en/docs/http/ngx_http_map_module.html), nginx.org
- [Module ngx_http_proxy_module: proxy_hide_header](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header), nginx.org
- [Module ngx_http_core_module: server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens), nginx.org
- [HTTP Security Response Headers Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html), OWASP
