Traefik guide · X-Frame-Options

How to set X-Frame-Options on Traefik

Set X-Frame-Options on Traefik with frameDeny or customFrameOptionsValue, pair it with CSP frame-ancestors and let a partner embed one path. 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
x-frame-options
DENY

Present on error pages too

In short4 points
  • Add frameDeny: true and contentSecurityPolicy: "frame-ancestors 'none'" to a headers middleware, and list it on the router of your site.
  • For SAMEORIGIN, use customFrameOptionsValue: "SAMEORIGIN" with frame-ancestors 'self'. It wins over frameDeny when 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-ancestors and X-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:

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

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

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

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

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

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

Shell
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

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

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 X-Frame-Options, in a few seconds. Free, no account.

Scan your site