# How to enable HSTS (Strict-Transport-Security) on Nginx

> Enable HSTS on Nginx: send Strict-Transport-Security from the HTTPS server only, with always, on every location and redirect, without duplicates. Tested configs.

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

## In short

- Add `add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;` to the `server` block that listens on 443, and redirect port 80 to HTTPS with `return 301`.
- Keep `always`: without it, Nginx sends no HSTS header on 404 and 500 pages.
- A `location` with its own `add_header` drops the server-level HSTS header. Share it through an `include` file, or use `add_header_inherit merge;` on nginx 1.29.3 or later.
- Every HTTPS host needs the header, including a server block that only redirects `example.com` to `www.example.com`.
- When the upstream application also sends HSTS, its header comes first and wins. Remove it with `proxy_hide_header Strict-Transport-Security;`.

## The short answer

Redirect port 80 to HTTPS, and add the header to the `server` block that
listens on 443:

```nginx
server {
    listen 80;
    server_name example.com www.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;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
}
```

```sh
sudo nginx -t && sudo systemctl reload nginx
```

The `always` parameter keeps the header on error pages. The port 80 block has
no header on purpose: browsers ignore HSTS over plain HTTP. Every snippet below
was run on nginx 1.28, 1.30 and 1.31 and checked with `curl`, on a page, a 404
and a redirect.

`max-age=31536000` (one year) with `includeSubDomains` is what WebSec0 grades as
a pass, but it is a final value, not a starting point. Read
[how to roll out HSTS without locking users out](/guides/strict-transport-security/)
before you ship it, and check that every subdomain works over HTTPS.

## Before you start

List every `server` block and every existing `add_header` in the merged
configuration:

```sh
sudo nginx -T | grep -nE "listen|server_name|add_header|include|return 30"
```

You are looking for three things:

- **Every host on 443.** Each one needs the header, including blocks that only
  redirect.
- **Locations with their own `add_header`.** They will drop the server-level
  header (step 3).
- **An existing HSTS header,** from Nginx or from the application behind it.
  Two headers cause trouble (step 5).

## Step 1: start with a short max-age

A long `max-age` stays in visitors' browsers even if you remove the line. Start
at five minutes:

```nginx
add_header Strict-Transport-Security "max-age=300; includeSubDomains" always;
```

Reload, browse your sites and subdomains, and watch your error rates. Then raise
the value in steps, waiting a full `max-age` each time: `604800` (one week),
`2592000` (30 days), then `31536000` (one year) or `63072000` (two years).

If a subdomain cannot serve HTTPS yet, leave `includeSubDomains` out until it
can. WebSec0 grades a header without it as a warning, but a subdomain that
stops loading is worse.

## Step 2: keep it on error pages

Without `always`, Nginx only adds headers to 200, 201, 204, 206, 301, 302, 303,
304, 307 and 308 responses. Our test, with the line above minus `always`:

```http
HTTP/2 200
strict-transport-security: max-age=31536000; includeSubDomains

HTTP/2 404
(no strict-transport-security header)
```

A visitor's first HTTPS response can be a 404 from an old link. Keep `always`
on the line.

## Step 3: keep it on every location

`add_header` directives are inherited from the parent block **only if the
current block has none**. Here, files under `/assets/` are served without HSTS:

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

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    location /assets/ {
        # This one line removes the server-level HSTS header for /assets/.
        add_header Cache-Control "public, max-age=31536000, immutable" always;
    }
}
```

The fix that works on every version is a snippet you include wherever a block
sets its own headers:

```nginx
# /etc/nginx/snippets/security-headers.conf
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
```

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

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

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

On **nginx 1.29.3 or later**, which includes the 1.30 stable branch,
`add_header_inherit merge;` makes nested blocks add their headers to the
parent's instead of replacing them:

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

    add_header_inherit merge;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    location /assets/ {
        # Sent together with the server-level HSTS header.
        add_header Cache-Control "public, max-age=31536000, immutable" always;
    }
}
```

nginx 1.28 rejects it with `unknown directive "add_header_inherit"`. The same
trap applies to every security header; the
[Content-Security-Policy guide for Nginx](/guides/content-security-policy/nginx/)
uses the same snippet approach.

## Step 4: cover every host and redirect

`includeSubDomains` only protects visitors whose browser has already seen the
parent domain. A visitor who goes straight to `www.example.com` or
`api.example.com` learns the policy from that host, so each HTTPS `server`
block needs the header.

That includes blocks that only redirect. A `return 301` keeps the headers added
at the same level, and redirects are in the list Nginx covers even without
`always`:

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

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

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    return 301 https://www.example.com$request_uri;
}

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

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
}
```

The port 80 block redirects to HTTPS on the **same host** first, then the HTTPS
block moves visitors to `www`. Skipping that step, with
`http://example.com` going straight to `https://www.example.com`, means
browsers never receive HSTS for `example.com`. The HSTS preload list requires
this order.

If one `server` block listens on both 80 and 443, build the value from the
scheme. Nginx does not send a header whose value is empty:

```nginx
map $scheme $hsts_header {
    https   "max-age=31536000; includeSubDomains";
    default "";
}

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

    add_header Strict-Transport-Security $hsts_header always;
}
```

The `map` block goes in the `http` context, outside any `server`.

## Step 5: one header only, behind a reverse proxy

Many frameworks send HSTS on their own. When Nginx proxies such an application
and adds its own line, the response carries two headers, and the upstream's
comes first. Our test, with an application sending `max-age=300`:

```http
HTTP/2 200
strict-transport-security: max-age=300
strict-transport-security: max-age=31536000; includeSubDomains
```

Browsers apply only the first header, so these visitors get five minutes of
protection. WebSec0 also reads the first header and grades it as a warning.
Pick one owner. If it is Nginx, hide the upstream's header:

```nginx
location / {
    proxy_pass http://app;
    proxy_hide_header Strict-Transport-Security;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
}
```

Use `fastcgi_hide_header` for PHP-FPM and `uwsgi_hide_header` for uWSGI.

When Nginx itself sits behind a load balancer or CDN that terminates TLS, it
only sees plain HTTP. Either send HSTS from the component that terminates TLS,
or add the line in Nginx without the `$scheme` condition: browsers still
receive it over HTTPS. Make sure only one of the two sends it.

## Verify it

Check a page, an error page and the redirects. Use your own host names:

```sh
curl -sI https://example.com/ | grep -i strict-transport-security
curl -sI https://example.com/does-not-exist | grep -i strict-transport-security
curl -sI http://example.com/ | grep -iE "^location|strict-transport-security"
```

The first two should print the header. The third should print a `location:`
pointing to `https://example.com/` and no HSTS header.

Count the headers to catch duplicates. The result should be `1`:

```sh
curl -sI https://example.com/ | grep -ci '^strict-transport-security:'
```

Repeat for each host and for one URL in every `location` that sets its own
headers, then scan the site with WebSec0. The headers report shows the value it
received and whether it passes.

## Roll back

If a subdomain breaks after you enabled `includeSubDomains`, set the value to
`max-age=0`, reload, and keep HTTPS running:

```nginx
add_header Strict-Transport-Security "max-age=0" always;
```

Browsers forget the policy the next time they receive this header. Deleting
the line instead leaves the old policy in place until it expires.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Header missing on 404 or 500 pages | `add_header` without `always` | Add `always` to the line. |
| Header missing on some URLs | That `location` has its own `add_header` | Include the snippet there, or use `add_header_inherit merge;` (1.29.3+). |
| Header missing on `www` or another subdomain | Only the main `server` block sends it | Add it to every HTTPS `server` block, including redirects. |
| Two `Strict-Transport-Security` headers | The upstream application sends one too | `proxy_hide_header Strict-Transport-Security;` or remove the Nginx line. |
| Header on `http://` responses | The line is in the port 80 block | Move it to the 443 block, or use the `$scheme` map. Harmless, but browsers ignore it. |
| WebSec0 shows a warning | `max-age` below `31536000` or no `includeSubDomains` | Finish the rollout: one year with `includeSubDomains`. |
| `unknown directive "add_header_inherit"` | nginx older than 1.29.3 | Upgrade, or use the `include` approach. |
| Changes do not show up | Reload skipped, or a CDN cached old headers | `nginx -t && systemctl reload nginx`, then purge the CDN. |

## Frequently asked questions

### Where do I put the HSTS header in Nginx?

In the `server` block that listens on port 443 with `ssl`, or in a snippet included there. Do not put it in the port 80 block: browsers ignore HSTS received over plain HTTP, and that block should only redirect.

### Why is HSTS missing on my 404 pages?

Without the `always` parameter, Nginx only adds headers to 200, 201, 204, 206, 301, 302, 303, 304, 307 and 308 responses. Add `always` at the end of the `add_header` line.

### Why does Nginx drop the HSTS header on some URLs?

A `location` that sets any `add_header` of its own, such as `Cache-Control`, stops inheriting the headers of the `server` block. Include your security headers snippet in that location, or set `add_header_inherit merge;` on nginx 1.29.3 or later.

### Can I use one server block for HTTP and HTTPS?

Yes. Build the value with a `map` on `$scheme` that is empty for `http`. Nginx skips `add_header` when the value is empty, so only HTTPS responses carry the header.

### My response has two Strict-Transport-Security headers. Which one counts?

Browsers apply only the first one, and WebSec0 grades the first one too. It is usually the upstream application's, because proxied headers come before the ones Nginx adds. Hide it with `proxy_hide_header Strict-Transport-Security;`, or remove the Nginx line and let the application own it.

### How do I turn HSTS off on Nginx?

Change the value to `max-age=0`, reload, and keep serving HTTPS. Browsers drop the policy the next time they receive the header. Removing the `add_header` line does not clear the policy browsers already stored.

### Does HSTS work with HTTP/2 and HTTP/3 on Nginx?

Yes. `add_header` works the same way on every protocol. Header names are sent in lower case over HTTP/2 and HTTP/3, so search for them case-insensitively.

## 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_v2_module: http2](https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2), nginx.org
- [RFC 9113: HTTP/2, section 8.2 (field names in lowercase)](https://www.rfc-editor.org/rfc/rfc9113.html#section-8.2), IETF
- [RFC 6797: HTTP Strict Transport Security (HSTS)](https://www.rfc-editor.org/rfc/rfc6797.html), IETF
- [Strict-Transport-Security header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security), MDN Web Docs
