- Define a
headersmiddleware withstsSeconds: 31536000andstsIncludeSubdomains: true, attach it to each HTTPS router, and redirect thewebentry point towebsecure. - Traefik only adds the header to requests that arrived over TLS. Behind a load balancer that terminates TLS, add
forceSTSHeader: true. - On a router that redirects to
www, list the HSTS middleware before the redirect. In the other order, the redirect is sent without the header. stsSeconds: 0does not sendmax-age=0: Traefik 3 sends no header and Traefik 2.11 rejects the middleware. Roll back withcustomResponseHeaders.- Traefik replaces the HSTS header your application sends, so the response carries one.
The short answer
Redirect the web entry point to HTTPS, define a headers middleware with
the HSTS options, and attach it to the router of your site. With Docker
Compose:
services:
traefik:
image: traefik:v3.7
command:
- "--providers.docker=true"
- "--providers.docker.exposedByDefault=false"
- "--entryPoints.web.address=:80"
- "--entryPoints.web.http.redirections.entryPoint.to=websecure"
- "--entryPoints.web.http.redirections.entryPoint.scheme=https"
- "--entryPoints.websecure.address=:443"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
app:
image: nginx:1.30
labels:
- "traefik.enable=true"
- "traefik.http.routers.app.rule=Host(`example.com`)"
- "traefik.http.routers.app.entrypoints=websecure"
- "traefik.http.routers.app.tls=true"
- "traefik.http.routers.app.middlewares=hsts"
- "traefik.http.middlewares.hsts.headers.stsSeconds=31536000"
- "traefik.http.middlewares.hsts.headers.stsIncludeSubdomains=true"With the file provider, in a dynamic configuration file:
http:
middlewares:
hsts:
headers:
stsSeconds: 31536000
stsIncludeSubdomains: true
routers:
site:
rule: "Host(`example.com`)"
entryPoints: [websecure]
tls: {}
service: backend
middlewares: [hsts]Traefik builds the header from these options:
max-age=31536000; includeSubDomains. Every snippet below was run on Traefik
2.11, 3.6 and 3.7, in front of an Nginx container, 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
Check which routers exist, which entry points they use and which middlewares they list, in the Traefik dashboard or in your labels and dynamic files. You are looking for:
- Every HTTPS router. Each one needs the middleware, including routers that only redirect.
- How TLS reaches Traefik. If a load balancer in front terminates TLS, Traefik sees plain HTTP (step 3).
- Redirect middlewares on the same routers (step 2).
Step 1: start with a short max-age
A long max-age stays in visitors’ browsers even if you remove the
middleware. Start at five minutes:
http:
middlewares:
hsts:
headers:
stsSeconds: 300
stsIncludeSubdomains: trueThen raise stsSeconds 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 stsIncludeSubdomains
out until it can.
Step 2: cover every host and redirect
What our test returned with the configuration above:
| Request | Response |
|---|---|
http://example.com/a |
301 to https://example.com/a, no HSTS |
https://example.com/ and a 404 from the application |
With HSTS |
| A host no router matches | Traefik’s own 404, no HSTS |
The entry point redirection goes to HTTPS on the same host, which is the order the HSTS preload list requires.
To move visitors from example.com to www.example.com, add a redirect
middleware to the example.com router, after the HSTS middleware:
http:
middlewares:
redirect-www:
redirectRegex:
regex: "^https://example\\.com/(.*)"
replacement: "https://www.example.com/${1}"
permanent: true
routers:
apex:
rule: "Host(`example.com`)"
entryPoints: [websecure]
tls: {}
service: backend
middlewares: [hsts, redirect-www]Middlewares run in the order listed. With [hsts, redirect-www], our test
returned the 301 with the HSTS header. With [redirect-www, hsts], the
redirect answered before the HSTS middleware ran, and the 301 had no header.
The www.example.com router needs the hsts middleware too.
Step 3: TLS terminated in front of Traefik
Traefik only adds the header when the request reached it over TLS. On an entry point that receives plain HTTP, our test returned no header, even with the middleware attached. That is the case when a cloud load balancer or CDN terminates TLS and forwards plain HTTP to Traefik.
Either send HSTS from the component that terminates TLS, or force it in Traefik:
http:
middlewares:
hsts:
headers:
stsSeconds: 31536000
stsIncludeSubdomains: true
forceSTSHeader: trueWith forceSTSHeader: true, our test returned the header on the plain HTTP
entry point. Make sure only one component sends it, and do not attach this
middleware to routers that browsers reach over plain HTTP.
Step 4: the application’s own header
Many frameworks send HSTS on their own. In our test, the application sent
max-age=300 and Traefik’s middleware replaced it: the response carried a
single header with Traefik’s value. Nothing to hide, unlike Nginx, Apache or
Caddy.
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, then scan the site with WebSec0. The headers report shows the value it received and whether it passes.
Roll back
To back out, browsers need to receive max-age=0. The obvious change does not
send it. With stsSeconds: 0, Traefik 3.6 and 3.7 sent no HSTS header at all,
and Traefik 2.11 logged headers configuration not valid and answered 404 on
the router. Set the header directly instead:
http:
middlewares:
hsts:
headers:
customResponseHeaders:
Strict-Transport-Security: "max-age=0"Our test returned max-age=0 on every version. Keep serving HTTPS: browsers
forget the policy the next time they receive this header. Removing the
middleware instead leaves the old policy in place until it expires.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| No HSTS header at all | No router lists the middleware | Add it to each HTTPS router’s middlewares. |
| No header behind a load balancer | The request reaches Traefik over plain HTTP | Add forceSTSHeader: true, or send HSTS from the load balancer. |
Redirect to www has no header |
The redirect middleware is listed before hsts |
List hsts first. |
Header missing on www or another host |
Only one router has the middleware | Attach it to every HTTPS router. |
stsSeconds: 0 sends nothing, or the router answers 404 on 2.11 |
Traefik treats 0 as “no HSTS” | Use customResponseHeaders with max-age=0. |
| No header on a 404 for an unknown host | Traefik answers before any router | Expected: the response has no body to protect. |
| WebSec0 shows a warning | stsSeconds below 31536000 or no stsIncludeSubdomains |
Finish the rollout: one year with includeSubDomains. |
Server hub
Every header on Traefik
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.
Nginx
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.
Questions
Frequently asked questions
How do I enable HSTS in Traefik?
Create a headers middleware with stsSeconds: 31536000 and stsIncludeSubdomains: true, in Docker labels or a dynamic file, and list it in the middlewares of each HTTPS router.
Why does Traefik not send my HSTS header?
Either no router lists the middleware, or the request reached Traefik over plain HTTP. Traefik only adds HSTS to TLS requests unless forceSTSHeader is true, which you need when a load balancer in front terminates TLS.
Is HSTS sent on Traefik's HTTP to HTTPS redirect?
No. The entry point redirection answered with a 301 to the same host over HTTPS and no HSTS header in our tests. Browsers ignore HSTS over plain HTTP anyway.
How do I turn HSTS off on Traefik?
Send max-age=0 with customResponseHeaders: Strict-Transport-Security: "max-age=0", and keep serving HTTPS. Setting stsSeconds: 0 does not work: no header is sent on Traefik 3, and Traefik 2.11 rejects the middleware.
My application sends HSTS too. Do I get two headers?
No. In our tests Traefik's middleware replaced the application's header, so the response carried only Traefik's value.
References
Sources
- Headers middlewareTraefik Labs
- RedirectRegex middlewareTraefik Labs
- EntryPoints: HTTP redirectionsTraefik Labs
- Strict-Transport-Security headerMDN Web Docs
