Traefik guide · Referrer-Policy

How to set Referrer-Policy on Traefik

Set Referrer-Policy on Traefik with the referrerPolicy option of the headers middleware, in labels or a file, and use no-referrer on sensitive paths. Tested configs.

  • 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
referrer-policy
strict-origin-when-cross-origin

Present on error pages too

In short3 points
  • Add referrerPolicy: "strict-origin-when-cross-origin" to a headers middleware and list it on the router of your site.
  • Traefik replaces the application's Referrer-Policy, on its pages and 404s, and adds the header to its own 502s. There is no duplicate to hide.
  • For no-referrer on sensitive paths, add a router for the path with a second middleware, listed before the default one. Listed after, the default value wins.

The short answer

Define a headers middleware with the policy and attach it to the router of your site. In a dynamic configuration file:

YAML
http:
  middlewares:
    referrer-policy:
      headers:
        referrerPolicy: "strict-origin-when-cross-origin"

  routers:
    site:
      rule: "Host(`example.com`)"
      entryPoints: [websecure]
      tls: {}
      service: backend
      middlewares: [referrer-policy]

With Docker labels:

YAML
services:
  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=referrer-policy"
      - "traefik.http.middlewares.referrer-policy.headers.referrerPolicy=strict-origin-when-cross-origin"

Every snippet below was run on Traefik 2.11, 3.6 and 3.7, in front of Nginx containers, and checked with curl on a page, a 404, an application that sends its own header and an application that was down.

strict-origin-when-cross-origin keeps full URLs on your own origin and sends only the origin to other sites. The Referrer-Policy overview compares the eight values and explains when to choose a stricter one.

Before you start

A middleware does nothing until a router lists it. Check which routers exist and which middlewares they use, in the Traefik dashboard or in your labels:

Shell
docker inspect --format '{{json .Config.Labels}}' <container> | tr ',' '\n' | grep traefik

Then check your HTML templates for a <meta name="referrer"> tag. It overrides the header in the browser, and Traefik does not touch the page body:

Shell
curl -s https://example.com/ | grep -i 'name="referrer"'

Step 1: choose the value

Your site Middleware option
Most sites referrerPolicy: "strict-origin-when-cross-origin"
Never reveal where users come from referrerPolicy: "no-referrer"
Keep full URLs on your origin, nothing elsewhere referrerPolicy: "same-origin"

Do not use unsafe-url or no-referrer-when-downgrade: both send full URLs to other sites, and WebSec0 grades them as a warning. Traefik sends the value as written, so a typo reaches the browser, which ignores it and falls back to its default.

Step 2: which responses get the header

The middleware acts on everything that goes through the router. In our test:

Response Referrer-Policy
A page from the application Present
A 404 from the application Present
A page where the application sends unsafe-url Present once, with the middleware’s value
A 502 from Traefik when the application did not answer Present
The entry point’s HTTP to HTTPS redirect Absent

Unlike Nginx, Apache and Caddy, there is no always flag to remember and no duplicate to hide behind a proxy: the middleware replaces the application’s value. If the application must vary the policy per page, leave the option out of the middleware on its router.

To send the same headers on every router, attach the middleware to the HTTPS entry point. The security headers hub for Traefik shows that option and its cost: per-path values on routers stop working.

Step 3: a stricter policy on sensitive paths

Pages whose URLs carry a token, such as /reset/?token=…, should send no referrer at all. Add a router for that path with a second middleware:

YAML
http:
  middlewares:
    referrer-none:
      headers:
        referrerPolicy: "no-referrer"

  routers:
    site-reset:
      rule: "Host(`example.com`) && PathPrefix(`/reset/`)"
      entryPoints: [websecure]
      tls: {}
      service: backend
      middlewares: [referrer-none, referrer-policy]

Traefik gives priority to the longer rule, so this router wins for /reset/ URLs. What our test returned:

URL Referrer-Policy
/ strict-origin-when-cross-origin
/reset/ no-referrer
/reset/does-not-exist (404) no-referrer

The order in middlewares matters: the first middleware in the list modifies the response last, so its value wins. With [referrer-policy, referrer-none], our test returned strict-origin-when-cross-origin on /reset/, and the reset page still sends its origin to other sites. WebSec0 passes the page either way, so the scan does not reveal the mistake. Keeping the default middleware in the list keeps your other security headers on the path.

Verify it

Check a page, an error page and a sensitive path. Use your own host name:

Shell
curl -sI https://example.com/ | grep -i "^referrer-policy"
curl -sI https://example.com/does-not-exist | grep -i "^referrer-policy"
curl -sI https://example.com/reset/ | grep -i "^referrer-policy"

Each should print the policy you chose for that path. Count the headers to catch duplicates. The result should be 1:

Shell
curl -sI https://example.com/ | grep -ci '^referrer-policy:'

Then scan the site with WebSec0. The headers report shows the value it received and whether it passes.

Troubleshooting

Symptom Likely cause Fix
No Referrer-Policy at all No router lists the middleware Add it to each HTTPS router’s middlewares, or to the entry point.
A stricter path policy has no effect The override is listed after the default middleware, or the default is on the entry point List the override first, and attach the default to routers.
The application’s own policy disappears The middleware on its router replaces it Remove referrerPolicy from that router’s middleware if the application owns it.
WebSec0 shows a warning The value is unsafe-url or no-referrer-when-downgrade Use strict-origin-when-cross-origin.
WebSec0 fails a header that is present No recognised value: a typo Fix the value; browsers ignore it too.
Browser sends more than the header says A <meta name="referrer"> in the page overrides it Remove the tag or make it match.
No header on a 404 for an unknown host Traefik answers before any router Expected: the response has no body to protect.

Server hub

Every header on Traefik

Other web servers

Referrer-Policy on other servers

Questions

Frequently asked questions

How do I set Referrer-Policy in Traefik?

Add referrerPolicy: "strict-origin-when-cross-origin" to a headers middleware, or the label traefik.http.middlewares.<name>.headers.referrerPolicy=strict-origin-when-cross-origin, and list the middleware on the router.

Does Traefik keep the application's Referrer-Policy?

No. When the middleware sets the header, Traefik replaces the application's value. In our test, an application sending unsafe-url came out with a single strict-origin-when-cross-origin.

How do I use a different Referrer-Policy for one URL on Traefik?

Add a router with a PathPrefix rule for that path and a middleware with referrerPolicy: "no-referrer". List it before the default middleware in the router's middlewares: the first one in the list writes the response headers last.

Does Traefik send Referrer-Policy by default?

No. Traefik adds security headers only through a headers middleware that a router or entry point lists.

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 Referrer-Policy, in a few seconds. Free, no account.

Scan your site