- Add
X-Frame-Options "DENY"and a Content-Security-Policy withframe-ancestors 'none'to aheaderblock in the site. UseSAMEORIGINand'self'if your own pages frame each other. - Caddy sends the header on its own 404 pages and on redirects without any extra flag.
- Behind
reverse_proxy, an application that sends X-Frame-Options too produces two headers, andDENYplusSAMEORIGINblocks framing everywhere. Addheader_down -X-Frame-Optionsinside the proxy block. - To let a partner embed one path, use two named matchers: the default headers on
not path /embed/*, and a CSP with the partner's origin onpath /embed/*. - Avoid
header /embed/* -X-Frame-Optionsfor this: Caddy defers deletions, and its own 404 pages under that path keep the header.
The short answer
Add both headers to the site block in your Caddyfile:
example.com {
header {
Content-Security-Policy "frame-ancestors 'none'"
X-Frame-Options "DENY"
}
root * /var/www/example
file_server
}caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddyIf you already send a Content-Security-Policy, add frame-ancestors 'none'
to that policy instead of the first line. Every snippet below was run on
Caddy 2.9, 2.10 and 2.11 and checked with curl, on a page, a 404, a
redirect, a proxied application 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'. The
X-Frame-Options overview explains the two values
and why frame-ancestors overrides the older header in current browsers.
Before you start
Find every site block, header directive and proxy in your Caddyfile:
grep -nE "^[^ \t#].*\{|header|X-Frame-Options|frame-ancestors|reverse_proxy|php_fastcgi|import" /etc/caddy/CaddyfileYou are looking for three things:
- Every site that serves pages. Caddy adds no X-Frame-Options on its own.
- Proxied applications that may send X-Frame-Options themselves. Two headers cause trouble (step 3).
- Pages that are framed on purpose, such as widgets or previews. They need their own rule (step 4).
Step 1: choose DENY or SAMEORIGIN
| Your site | Caddyfile lines |
|---|---|
| Never frames its own pages | X-Frame-Options "DENY" and frame-ancestors 'none' |
| Frames its own pages, such as admin previews | X-Frame-Options "SAMEORIGIN" and frame-ancestors 'self' |
| Is embedded by another site on some pages | One of the above, plus step 4 for those pages |
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
A plain header block acts on every response of the site. In our test:
| Response | X-Frame-Options |
|---|---|
A page from file_server |
Present |
A 404 from file_server |
Present |
A 301 from a redir in the site |
Present |
A file under /assets/ with its own header /assets/* Cache-Control … line |
Present |
| Caddy’s automatic HTTP to HTTPS redirect | Absent |
Unlike Nginx and Apache, there is no always flag to remember, and a line
that sets another header for one path keeps X-Frame-Options. The automatic
redirect has no page to protect.
To send the same headers from several sites, put them in a snippet that each site imports. The security headers hub for Caddy shows one snippet with all six security headers.
Step 3: one header behind reverse_proxy
Many frameworks and security middlewares send X-Frame-Options by default. A
header block runs before the proxy, and Caddy keeps the application’s
header next to its own. Our test, with an application sending SAMEORIGIN:
HTTP/2 200
x-frame-options: DENY
x-frame-options: SAMEORIGINBrowsers combine the two values, see a conflict and block the page in every frame, so same-site previews break. WebSec0 reads both values like a browser and grades the conflict as a warning, worth 7 of 15 points.
Pick one owner. If it is Caddy, drop the application’s header as the response comes back from the proxy:
example.com {
header {
Content-Security-Policy "frame-ancestors 'none'"
X-Frame-Options "DENY"
}
reverse_proxy 127.0.0.1:8080 {
header_down -X-Frame-Options
header_down -Content-Security-Policy
}
}Our test then returned DENY once on the application’s pages and 404s, and on
Caddy’s 502 when the application was down. The second header_down line
removes the application’s own CSP; keep it only if Caddy owns the whole
policy. Do not use the > prefix instead: it replaces the application’s
value, but Caddy’s own 502 then has no header at all.
If the application sends a CSP with frame-ancestors, you can also let it
own framing and drop the Caddy lines: browsers apply frame-ancestors either
way.
Step 4: let a partner embed one path
To let partner.example frame the pages under /embed/ and keep everything
else at DENY, split the site with two named matchers:
example.com {
@embed path /embed/*
@not_embed not path /embed/*
header @not_embed {
Content-Security-Policy "frame-ancestors 'none'"
X-Frame-Options "DENY"
}
header @embed Content-Security-Policy "frame-ancestors 'self' https://partner.example"
root * /var/www/example
file_server
}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 obvious alternative leaves a gap. With the default headers on the whole
site and header /embed/* -X-Frame-Options in a route block, /embed/ lost
the header, but the 404 under it still sent X-Frame-Options: DENY. Caddy
defers a line that deletes a field until the response is written, and its own
error pages skip deferred lines. That 404 is harmless, since browsers ignore
X-Frame-Options when the CSP has frame-ancestors, but the matchers avoid it.
If your full CSP is defined in the site, copy the whole policy into the
@embed line 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 a static file. 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/assets/app.css | grep -iE "^x-frame-options|^content-security-policy"Each should print x-frame-options: DENY and a policy with
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 | Caddy adds none by default | Add the header block to every site, or import a snippet. |
Two X-Frame-Options headers |
The proxied application sends one too | Add header_down -X-Frame-Options inside reverse_proxy. |
| Header missing on 502 pages | > in front of the field |
Drop the > and use header_down. |
| Your own iframes stopped loading | DENY, or SAMEORIGIN and DENY both sent |
Use SAMEORIGIN and 'self', and send one header. |
| A partner’s embed is blank | X-Frame-Options or frame-ancestors 'none' on that path |
Use the two matchers from step 4. |
| A 404 under the embed path keeps X-Frame-Options | A deferred -X-Frame-Options line |
Harmless with frame-ancestors; use matchers to remove it. |
| WebSec0 shows a warning | Two different values, often one from the application | Keep one header with one value (step 3). |
| WebSec0 fails a header that is present | An invalid value, such as ALLOW-FROM |
Replace it with DENY or SAMEORIGIN, or add frame-ancestors to your CSP. |
| Changes do not show up | Reload skipped, or a CDN cached old headers | caddy validate and reload, then purge the CDN. |
Server hub
Every header on Caddy
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.
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.
Traefik
Guide ↗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.
Questions
Frequently asked questions
Where do I put X-Frame-Options in a Caddyfile?
In a header block inside each site block, or in a snippet that every site imports. Caddy applies it to every response of the site, including its own 404 pages and redirects.
What is the Caddyfile line for X-Frame-Options?
header X-Frame-Options "DENY", or SAMEORIGIN instead of DENY if your own pages frame each other. Reload with caddy validate and systemctl reload caddy.
Why does my response have two X-Frame-Options headers behind reverse_proxy?
Caddy sets its header before the proxy and keeps the application's. Add header_down -X-Frame-Options inside the reverse_proxy block to drop the application's copy.
How do I allow framing for one URL on Caddy?
Define @embed path /embed/* and @not_embed not path /embed/*. Send X-Frame-Options and frame-ancestors 'none' on @not_embed only, and a CSP with frame-ancestors 'self' https://partner.example on @embed.
Why does a 404 under my embed path still send X-Frame-Options?
A header line that deletes a field, such as -X-Frame-Options, is deferred until the response is written, and Caddy's own error pages skip deferred lines. Use matchers so the header is never set on that path.
Does Caddy send X-Frame-Options by default?
No. Caddy sends no security headers of its own. Add the line to every site that serves pages.
References
Sources
- X-Frame-Options headerMDN Web Docs
- CSP: frame-ancestorsMDN Web Docs
