Nginx guide · Strict-Transport-Security

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.

  • By
  • Updated
  • 5 min read
  • Tested on nginx 1.28, 1.30 and 1.31
$ curl -sI https://example.com/missing
status
HTTP/2 404
server
nginx
strict-transport-security
max-age=31536000; includeSubDomains

Present on error pages too

In short5 points
  • 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;
}
Shell
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 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:

Shell
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 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:

Shell
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:

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

Server hub

Every header on Nginx

Other web servers

Strict-Transport-Security on other servers

Questions

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.

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 security headers, including Strict-Transport-Security, in a few seconds. Free, no account.

Scan your site