- Add
frameDeny: trueandcontentSecurityPolicy: "frame-ancestors 'none'"to aheadersmiddleware, and list it on the router of your site. - For
SAMEORIGIN, usecustomFrameOptionsValue: "SAMEORIGIN"withframe-ancestors 'self'. It wins overframeDenywhen both are set. - Traefik replaces the application's X-Frame-Options, on its pages and 404s, and adds the header to its own 502s. There is no duplicate to hide.
- To let a partner embed one path, add a router for it with a middleware that sets the partner's
frame-ancestorsandX-Frame-Options: "", listed before the default middleware.
The short answer
Define a headers middleware with both options and attach it to the router
of your site. In a dynamic configuration file:
http:
middlewares:
frame-headers:
headers:
contentSecurityPolicy: "frame-ancestors 'none'"
frameDeny: true
routers:
site:
rule: "Host(`example.com`)"
entryPoints: [websecure]
tls: {}
service: backend
middlewares: [frame-headers]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=frame-headers"
- "traefik.http.middlewares.frame-headers.headers.contentSecurityPolicy=frame-ancestors 'none'"
- "traefik.http.middlewares.frame-headers.headers.frameDeny=true"frameDeny: true sends X-Frame-Options: DENY. If you already send a
Content-Security-Policy, add frame-ancestors 'none' to that policy instead.
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.
DENY blocks every frame, including your own. If your site frames its own
pages, use SAMEORIGIN and frame-ancestors 'self' (step 1). The
X-Frame-Options overview explains the two values
and why frame-ancestors overrides the older header in current browsers.
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 traefikYou are looking for two things:
- Every HTTPS router that serves pages. Each one needs the middleware, or attach it to the entry point.
- Pages that are framed on purpose, such as widgets or previews. They need their own router (step 3).
Step 1: choose DENY or SAMEORIGIN
| Your site | Middleware options |
|---|---|
| Never frames its own pages | frameDeny: true and frame-ancestors 'none' |
| Frames its own pages, such as admin previews | customFrameOptionsValue: "SAMEORIGIN" and frame-ancestors 'self' |
| Is embedded by another site on some pages | One of the above, plus step 3 for those pages |
http:
middlewares:
frame-headers:
headers:
contentSecurityPolicy: "frame-ancestors 'self'"
customFrameOptionsValue: "SAMEORIGIN"Our test returned X-Frame-Options: SAMEORIGIN on pages and 404s. When a
middleware sets both frameDeny: true and customFrameOptionsValue, the
custom value wins: our test returned SAMEORIGIN on all three versions.
Keep the two headers in agreement. Current browsers apply frame-ancestors
and ignore X-Frame-Options when both are present, so a mismatch means older
clients and current ones behave differently. Do not use ALLOW-FROM: browsers
ignore it and the page can be framed by anyone.
Step 2: which responses get the header
The middleware acts on everything that goes through the router. In our test:
| Response | X-Frame-Options |
|---|---|
| A page from the application | DENY |
| A 404 from the application | DENY |
A page where the application sends SAMEORIGIN |
DENY, once: Traefik replaced the application’s value |
| A 502 from Traefik when the application did not answer | DENY |
| 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 redirect has no page to protect.
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: let a partner embed one path
To let partner.example frame the pages under /embed/ and keep everything
else at DENY, add a router for that path with a middleware that changes the
CSP and removes X-Frame-Options:
http:
middlewares:
embed-frame:
headers:
contentSecurityPolicy: "frame-ancestors 'self' https://partner.example"
customResponseHeaders:
X-Frame-Options: ""
routers:
site-embed:
rule: "Host(`example.com`) && PathPrefix(`/embed/`)"
entryPoints: [websecure]
tls: {}
service: backend
middlewares: [embed-frame, frame-headers]Traefik gives priority to the longer rule, so this router wins for /embed/
URLs. What our test returned:
| URL | Headers |
|---|---|
/ |
X-Frame-Options: DENY and frame-ancestors 'none' |
/embed/ |
frame-ancestors 'self' https://partner.example only |
/embed/does-not-exist (404) |
frame-ancestors 'self' https://partner.example only |
The order in middlewares matters: the first middleware in the list modifies
the response last, so its values win. With [frame-headers, embed-frame], our
test returned X-Frame-Options: DENY and frame-ancestors 'none' on /embed/,
and the partner’s frame stays blocked. Keeping frame-headers in the list
keeps your other security headers on the path.
If your full CSP is defined in the default middleware, copy the whole policy
into embed-frame and change only frame-ancestors. WebSec0 passes these
pages too, since their CSP contains frame-ancestors.
Verify it
Check a page, an error page and the embed path. Use your own host name:
curl -sI https://example.com/ | grep -iE "^x-frame-options|^content-security-policy"
curl -sI https://example.com/does-not-exist | grep -iE "^x-frame-options|^content-security-policy"
curl -sI https://example.com/embed/ | grep -iE "^x-frame-options|^content-security-policy"The first two should print x-frame-options: DENY and a policy with
frame-ancestors 'none'; the third only the partner’s frame-ancestors.
Count the X-Frame-Options headers to catch duplicates. The result should be
1:
curl -sI https://example.com/ | grep -ci '^x-frame-options:'Then scan the site with WebSec0. The headers report shows the value it received and whether it passes.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| No X-Frame-Options at all | No router lists the middleware | Add it to each HTTPS router’s middlewares, or to the entry point. |
SAMEORIGIN sent where you expected DENY |
customFrameOptionsValue is set and wins over frameDeny |
Remove customFrameOptionsValue. |
| A partner’s embed is blank | The override middleware is listed after the default one, or the default is on the entry point | List the override first, and attach the default to routers. |
| X-Frame-Options still sent on the embed path | The override sets the CSP but does not remove the header | Add X-Frame-Options: "" under customResponseHeaders. |
| Your own iframes stopped loading | DENY on a site that frames its own pages |
Use customFrameOptionsValue: "SAMEORIGIN" and 'self'. |
| WebSec0 fails a header that is present | An invalid value, such as ALLOW-FROM in customFrameOptionsValue |
Use DENY or SAMEORIGIN, or add frame-ancestors to your CSP. |
| 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
X-Frame-Options on other servers
Apache
Guide ↗Set X-Frame-Options on Apache with Header always set, pair it with CSP frame-ancestors, keep it on errors and redirects and avoid duplicate headers. Tested configs.
Caddy
Guide ↗Set X-Frame-Options on Caddy with the header directive, pair it with CSP frame-ancestors, drop the application's copy behind reverse_proxy and allow one path. Tested.
Nginx
Guide ↗Set X-Frame-Options on Nginx with add_header and always, pair it with CSP frame-ancestors, keep it on every location and avoid duplicate headers. Tested configs.
Questions
Frequently asked questions
How do I set X-Frame-Options in Traefik?
Add frameDeny: true to a headers middleware, or the label traefik.http.middlewares.<name>.headers.frameDeny=true, and list the middleware on the router. Traefik then sends X-Frame-Options: DENY.
How do I send X-Frame-Options: SAMEORIGIN in Traefik?
Set customFrameOptionsValue: "SAMEORIGIN" in the headers middleware. In our test it replaced DENY even when frameDeny: true was also set, on Traefik 2.11, 3.6 and 3.7.
Does Traefik keep the application's X-Frame-Options?
No. When the middleware sets the header, Traefik replaces the application's value. In our test, an application sending SAMEORIGIN came out with a single DENY.
How do I allow framing for one URL on Traefik?
Add a router with PathPrefix(/embed/) and a middleware that sets contentSecurityPolicy with the partner's origin in frame-ancestors and removes X-Frame-Options with customResponseHeaders. List it before the default middleware.
How do I remove X-Frame-Options in Traefik?
Give it an empty value under customResponseHeaders: X-Frame-Options: "". Traefik then sends no X-Frame-Options header, including on error pages.
Does Traefik send X-Frame-Options 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
- X-Frame-Options headerMDN Web Docs
- CSP: frame-ancestorsMDN Web Docs
