- Add
referrerPolicy: "strict-origin-when-cross-origin"to aheadersmiddleware 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-referreron 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:
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:
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:
docker inspect --format '{{json .Config.Labels}}' <container> | tr ',' '\n' | grep traefikThen 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:
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:
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:
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:
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
Apache
Guide ↗Set Referrer-Policy on Apache with Header always set, keep it on errors and redirects, use no-referrer on sensitive paths and stop a proxied app's value winning. Tested.
Caddy
Guide ↗Set Referrer-Policy on Caddy with the header directive, use no-referrer on sensitive paths with route, and stop a proxied app's weaker value from winning. Tested configs.
Nginx
Guide ↗Set Referrer-Policy on Nginx with add_header and always, keep it on every location, use a stricter policy on sensitive paths and avoid duplicate headers. Tested configs.
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
- Traefik Proxy: Headers middlewareTraefik Labs
- Traefik Proxy: Routers (rules and priority)Traefik Labs
- Referrer-Policy headerMDN Web Docs
