Traefik guide · Strict-Transport-Security

How to enable HSTS (Strict-Transport-Security) on Traefik

Enable HSTS on Traefik with the headers middleware: stsSeconds and stsIncludeSubdomains, the HTTPS redirect, middleware order, TLS offloading and a working rollback.

  • By
  • Updated
  • 4 min read
  • Tested on Traefik 2.11, 3.6 and 3.7
$ curl -sI https://example.com/missing
status
HTTP/2 404
strict-transport-security
max-age=31536000; includeSubDomains

Present on error pages too

In short5 points
  • Define a headers middleware with stsSeconds: 31536000 and stsIncludeSubdomains: true, attach it to each HTTPS router, and redirect the web entry point to websecure.
  • 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: 0 does not send max-age=0: Traefik 3 sends no header and Traefik 2.11 rejects the middleware. Roll back with customResponseHeaders.
  • 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:

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

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

YAML
http:
  middlewares:
    hsts:
      headers:
        stsSeconds: 300
        stsIncludeSubdomains: true

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

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

YAML
http:
  middlewares:
    hsts:
      headers:
        stsSeconds: 31536000
        stsIncludeSubdomains: true
        forceSTSHeader: true

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

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

YAML
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

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

  1. Headers middlewareTraefik Labs

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