Caddy guide · X-Frame-Options

How to set X-Frame-Options on Caddy

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.

  • By
  • Updated
  • 5 min read
  • Tested on Caddy 2.9, 2.10 and 2.11
$ curl -sI https://example.com/missing
status
HTTP/2 404
server
Caddy
x-frame-options
DENY

Present on error pages too

In short5 points
  • Add X-Frame-Options "DENY" and a Content-Security-Policy with frame-ancestors 'none' to a header block in the site. Use SAMEORIGIN and '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, and DENY plus SAMEORIGIN blocks framing everywhere. Add header_down -X-Frame-Options inside 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 on path /embed/*.
  • Avoid header /embed/* -X-Frame-Options for 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:

Caddyfile
example.com {
	header {
		Content-Security-Policy "frame-ancestors 'none'"
		X-Frame-Options "DENY"
	}
	root * /var/www/example
	file_server
}
Shell
caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddy

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

Shell
grep -nE "^[^ \t#].*\{|header|X-Frame-Options|frame-ancestors|reverse_proxy|php_fastcgi|import" /etc/caddy/Caddyfile

You 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
HTTP/2 200
x-frame-options: DENY
x-frame-options: SAMEORIGIN

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

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

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

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

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

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

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