- Add
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;to theserverblock that listens on 443, and redirect port 80 to HTTPS withreturn 301. - Keep
always: without it, Nginx sends no HSTS header on 404 and 500 pages. - A
locationwith its ownadd_headerdrops the server-level HSTS header. Share it through anincludefile, or useadd_header_inherit merge;on nginx 1.29.3 or later. - Every HTTPS host needs the header, including a server block that only redirects
example.comtowww.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:
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;
}sudo nginx -t && sudo systemctl reload nginxThe 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:
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:
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/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:
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:
# /etc/nginx/snippets/security-headers.conf
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;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:
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:
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:
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/2 200
strict-transport-security: max-age=300
strict-transport-security: max-age=31536000; includeSubDomainsBrowsers 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:
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:
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:
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:
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
Apache
Guide ↗Enable HSTS on Apache: send Strict-Transport-Security from the HTTPS virtual host only, with always, on every redirect and error page, without duplicates. Tested configs.
Caddy
Guide ↗Enable HSTS on Caddy: add Strict-Transport-Security to the site block, keep it off plain HTTP, cover redirects and avoid a second header behind reverse_proxy. Tested.
Traefik
Guide ↗Enable HSTS on Traefik with the headers middleware: stsSeconds and stsIncludeSubdomains, the HTTPS redirect, middleware order, TLS offloading and a working rollback.
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
- Module ngx_http_map_modulenginx.org
- Module ngx_http_v2_module: http2nginx.org
- Strict-Transport-Security headerMDN Web Docs
