Cross-Origin Frame Controls: X-Frame-Options & frame-ancestors

This guide is part of the Web Security Headers Fundamentals reference. It covers the two response headers that govern who is allowed to embed your pages inside an <iframe>, <frame>, <object>, or <embed>: the legacy X-Frame-Options header and its modern, standards-track successor, the Content-Security-Policy frame-ancestors directive. Both exist to neutralize clickjacking. They overlap, they interact, and getting the precedence wrong silently weakens your defense.

Threat Model & Protocol Mechanics

Framing controls exist to stop clickjacking, also called UI redressing. The attack does not exploit a bug in your application — it exploits the fact that a browser will, by default, render any page inside a frame on any other site.

The mechanics are straightforward:

1. The attacker hosts evil.example and loads your authenticated page (https://bank.example/transfer) inside a transparent iframe.
2. CSS sets the iframe to opacity: 0 and stacks it above attacker-controlled bait UI with a high z-index.
3. The attacker positions a tempting decoy (“Claim your prize”) directly under your real “Confirm transfer” button.
4. The victim — already authenticated to bank.example via ambient cookies — clicks what they believe is the decoy. The click lands on your real button. The action executes with the victim’s credentials.

Because the victim’s session cookies travel with the framed request, no credential theft is required. The browser’s Same-Origin Policy blocks the attacker from reading your framed DOM, but it does not stop them from displaying it and capturing clicks through it. Framing headers close that gap by telling the browser to refuse to render your page as a nested browsing context at all.

The anatomy of the overlay is what makes the attack so effective: two pages are stacked pixel-for-pixel, and only the transparency and stacking order decide which one the victim sees versus which one receives the click.

Transparency is only the simplest technique in a broader family. Cursorjacking replaces the real pointer with a CSS-drawn fake offset by a fixed number of pixels, so the victim aims at one control while the actual click lands elsewhere. Drag-and-drop clickjacking frames your page invisibly and tricks the victim into dragging a token — a CSRF value, an OAuth code visible in a text field — out of the framed document and into an attacker-controlled drop target, exfiltrating data that Same-Origin Policy would otherwise protect. On touch devices the same class of attack is called tapjacking: the framed button receives the tap instead of the decoy. Every one of these variants depends on the browser agreeing to render your page as a nested browsing context, which is exactly what a framing header refuses.

The ancestor check is not limited to the immediate parent. When your page sits inside a chain — attacker frames a trusted intermediary which frames you — a conforming browser walks the entire ancestor chain and rejects the load if any ancestor fails the source list. This closes the “trusted middle frame” bypass, where an attacker embeds a partner you allow and then re-embeds that partner elsewhere. X-Frame-Options: SAMEORIGIN is weaker here: historically several engines compared only the top-level document’s origin rather than every ancestor, so a same-origin outer frame containing a cross-origin middle frame could slip through. frame-ancestors evaluates each hop and has no such gap.

Why frame-ancestors supersedes X-Frame-Options

X-Frame-Options was a Microsoft extension first shipped in IE8 (2009) and only later loosely standardized in RFC 7034, which is informational, not a normative standard. It has structural limits: it can express deny all or same origin only, and nothing in between that browsers actually honor. Its attempt at an allowlist (ALLOW-FROM) was never implemented in Chromium or Gecko.

frame-ancestors is part of the normative CSP Level 2/3 specification. It accepts a full source list — multiple origins, schemes, wildcards, and the 'self' and 'none' keywords — making it the only mechanism that can express “embeddable by these specific partners and no one else.” It is the directive every new deployment should lead with.

Browser precedence: which header wins

When a response carries both headers, the CSP specification mandates that frame-ancestors takes precedence and X-Frame-Options is ignored. All current Chromium, Gecko, and WebKit engines implement this. The practical consequence:

• A page with X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'self' is embeddable on its own origin — the CSP directive wins, the stricter XFO is discarded.
• This is not a bug; it is the defined contract. If you deploy both, make them agree, or accept that frame-ancestors is the effective policy.

Frame controls are evaluated by the browser per navigation, server-enforced — there is no cache analogous to HSTS’s max-age. The header must be present on the framed response every time. They are also only meaningful over a secure transport; pair framing controls with HTTPS enforcement so an attacker cannot strip the header on a plaintext hop.

Three delivery constraints are unique to frame-ancestors and catch teams that treat it like any other CSP directive:

• It cannot be delivered via a <meta> tag. The CSP spec explicitly ignores frame-ancestors, report-uri, and sandbox when the policy arrives through <meta http-equiv="Content-Security-Policy">. A framing policy embedded in HTML is silently discarded — it must travel as a real HTTP response header.
• default-src does not back-fill it. Unlike script-src or img-src, frame-ancestors has no fallback to default-src. If you set default-src 'none' expecting it to block framing, it does nothing; you must name frame-ancestors explicitly.
• Report-Only mode does not enforce. A Content-Security-Policy-Report-Only: frame-ancestors 'self' header logs a violation report but still renders the frame. Use report-only to discover which origins embed you before you commit to a blocking policy, but never rely on it as protection.

What framing headers do not cover

Framing controls stop your page from being loaded as a nested browsing context. They do not defend against attacks that never frame you. Double-clickjacking — a 2024 technique — opens your page in a new top-level window (a popup or window.open target) rather than an iframe, then exploits the timing gap between mousedown and mouseup while swapping windows underneath a double-click. Because there is no ancestor chain, frame-ancestors and X-Frame-Options are structurally irrelevant to it; mitigations there are application-side (disabling sensitive controls until a deliberate interaction, or requiring a gesture the timing trick cannot forge). Likewise, framing headers do not stop popups, noopener reverse-tabnabbing, or a user who is genuinely phished on a look-alike domain. Treat them as the specific countermeasure to embedding, not a general anti-UI-redressing shield.

Directive Syntax & Spec

X-Frame-Options carries a single token. Header values are matched case-insensitively, but whitespace and unknown tokens are unforgiving — a malformed value causes browsers to treat the header as absent and fall back to permissive framing.

X-Frame-Options: SAMEORIGIN

frame-ancestors is a CSP directive whose value is a source list:

Content-Security-Policy: frame-ancestors 'self' https://partner.example

The gap between the two mechanisms is easiest to read as a capability matrix. Every posture X-Frame-Options can express, frame-ancestors can also express — but not the reverse, which is why new deployments lead with the CSP directive and treat XFO as a fallback only.

Malformed-syntax gotchas:

• Wrapping origins in quotes (frame-ancestors "https://a.example") is invalid; only the keywords 'self', 'none' take quotes.
• A trailing or duplicated X-Frame-Options header (origin + CDN both setting it) is RFC-noncompliant and browsers may treat the page as having no policy.
• frame-ancestors does not accept the 'unsafe-inline'/'nonce-...' tokens — only host-source and scheme-source expressions plus 'self'/'none'.
• A path in a frame-ancestors source (https://a.example/embed) is ignored for ancestor matching; framing is decided at origin granularity.
• A bare host without a scheme (frame-ancestors a.example) matches that host over any scheme, including http:. To pin the ancestor to TLS, always write the scheme: frame-ancestors https://a.example.
• Scheme and port are part of the origin. frame-ancestors 'self' on a page served from https://app.example:8443 does not match an embed attempted from https://app.example (default port 443) — the ports differ. Name the exact origin when non-default ports are in play.
• frame-ancestors accepts data: and blob: scheme-sources for the rare case of framing generated documents, but listing them widens your surface; a data: ancestor is attacker-controllable and should almost never be allowed.
• Combining directives in one header is fine (frame-ancestors 'self'; img-src 'self'), but two separate Content-Security-Policy headers are enforced as an intersection: a frame load must satisfy every policy present. A second, stricter CSP header can therefore block a frame your first header allowed.

Platform-Specific Implementation

Lead with frame-ancestors. Add X-Frame-Options only as a fallback for pre-2015 user agents. Apply both on every response code so error pages cannot be framed.

Nginx

add_header Content-Security-Policy "frame-ancestors 'self' https://partner.example" always;
add_header X-Frame-Options "SAMEORIGIN" always;

• Security impact: always emits the headers on 4xx/5xx responses too — without it, Nginx drops add_header on error pages, leaving them frameable.
• Verification: curl -sI https://your-domain.com | grep -iE 'frame-ancestors|x-frame-options'

Apache (mod_headers)

Header always set Content-Security-Policy "frame-ancestors 'self' https://partner.example"
Header always set X-Frame-Options "SAMEORIGIN"

• Security impact: always applies the header across all HTTP status codes; the default onsuccess table skips errors. Requires mod_headers loaded.
• Verification: apachectl -M 2>/dev/null | grep headers_module && curl -sI https://your-domain.com | grep -i frame

IIS (web.config)

<configuration>
  <system.webServer>
    <httpProtocol>
      <customHeaders>
        <add name="Content-Security-Policy" value="frame-ancestors 'self' https://partner.example" />
        <add name="X-Frame-Options" value="SAMEORIGIN" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

• Security impact: customHeaders injects at the site/application level inside the IIS pipeline, before ASP.NET processing, covering static and dynamic responses uniformly.
• Verification: (Invoke-WebRequest -Uri https://your-domain.com).Headers['Content-Security-Policy']

Node/Express (Helmet)

const helmet = require('helmet');

app.use(
  helmet({
    contentSecurityPolicy: {
      directives: { frameAncestors: ["'self'", 'https://partner.example'] },
    },
    // helmet sets X-Frame-Options: SAMEORIGIN by default via frameguard
  })
);

• Security impact: Middleware runs before route handlers and emits both headers on every response Helmet touches. Mount it before your routers so error responses inherit it.
• Verification: curl -sI http://localhost:3000 | grep -iE 'frame-ancestors|x-frame-options'

Cloudflare (Transform Rules)

Rules → Transform Rules → Modify Response Header → Set static:
  Content-Security-Policy = frame-ancestors 'self' https://partner.example
  X-Frame-Options = SAMEORIGIN

• Security impact: Edge enforcement applies before traffic reaches the origin and covers cache hits the origin never sees. Use Set (not Add) to avoid stacking a second header on top of an origin-set one.
• Verification: curl -sI https://your-domain.com | grep -iE 'frame-ancestors|x-frame-options|cf-cache-status'

Verification & Diagnostic Workflows

Confirm the header is present, single-valued, and applied across status codes.

# Header presence on a normal response
curl -sI https://your-domain.com | grep -iE 'frame-ancestors|x-frame-options'

# Confirm coverage on a 404 (error pages must not be frameable)
curl -sI https://your-domain.com/this-path-404 | grep -iE 'frame-ancestors|x-frame-options'

# Detect duplicate X-Frame-Options (origin + CDN stacking)
curl -sI https://your-domain.com | grep -ci x-frame-options   # expect 1, not 2

Live embed test. Save the following as frame-test.html, serve it with python3 -m http.server 8080, and open http://localhost:8080/frame-test.html:

<iframe src="https://your-domain.com" style="width:100%;height:400px;"></iframe>

A protected page shows a blank frame and a DevTools Console error such as Refused to display 'https://your-domain.com/' in a frame because an ancestor violates the following Content Security Policy directive: "frame-ancestors 'self'". For an XFO-only page the message references X-Frame-Options to SAMEORIGIN.

CI/CD gate. Fail the pipeline if either header is missing:

hdrs=$(curl -sI https://your-domain.com)
echo "$hdrs" | grep -qi 'frame-ancestors' || echo "$hdrs" | grep -qi 'x-frame-options' \
  || { echo "FAIL: no framing control"; exit 1; }

Troubleshooting, Misconfigurations & Safe Rollback

• Symptom: a legitimate iframe (partner portal, support chat) stopped rendering after deploy. → The embedding origin is not in your source list. Add it: frame-ancestors 'self' https://that-partner.example. Detailed walkthrough in fixing X-Frame-Options blocking legitimate iframes.
• Symptom: ALLOW-FROM partner embed silently broke in Chrome/Firefox. → ALLOW-FROM was never supported there and provides no protection. Replace it entirely with frame-ancestors 'self' https://partner.example.
• Symptom: page frameable despite XFO set. → A frame-ancestors directive is also present and overriding it. Reconcile the two so they express the same policy; frame-ancestors is authoritative.
• Symptom: duplicate X-Frame-Options header. → Both origin and CDN are setting it. Pick one layer. On Cloudflare use Set, not Add; on the origin remove the directive if the edge owns it.
• Symptom: header missing on 404/500 only. → The always flag (Nginx/Apache) is missing. Add it.
• Symptom: frame-ancestors set in a <meta> tag has no effect. → frame-ancestors is ignored when CSP is delivered via <meta>. Move the policy to an HTTP response header emitted by the server or edge.
• Symptom: default-src 'none' is set but the page still frames. → frame-ancestors does not fall back to default-src. Add an explicit frame-ancestors 'none' (or 'self') directive.
• Symptom: report-only policy logs violations but never blocks embedding. → The policy is on Content-Security-Policy-Report-Only, which only reports. Promote it to the enforcing Content-Security-Policy header once the allowlist is confirmed.
• Symptom: same-origin embed on a non-standard port refused with frame-ancestors 'self'. → 'self' matches scheme + host + port exactly; the differing port fails. Replace with the explicit origin, e.g. frame-ancestors 'self' https://app.example:8443.
• Symptom: nested partner embed (you inside partner inside a third site) refused even though the partner is allowlisted. → The browser checks every ancestor. The outer third site is not in your source list. Add it, or accept that deep nesting through the partner is disallowed by design.
• Symptom: policy works in Chrome but the frame renders in an older Safari. → That engine predates frame-ancestors. This is exactly why the X-Frame-Options: SAMEORIGIN fallback stays in place alongside the CSP directive.
• Safe rollback: if framing controls break production embedding and you cannot immediately identify the missing origin, drop to the least-restrictive still-protective policy rather than removing the header. Replace frame-ancestors 'self' with an explicit allowlist of the broken origins, or temporarily fall back to X-Frame-Options: SAMEORIGIN alone:

Header unset Content-Security-Policy
Header always set X-Frame-Options "SAMEORIGIN"

Never roll back to no framing header — that reopens the clickjacking surface entirely.

Frequently Asked Questions

Do I still need X-Frame-Options if I use frame-ancestors? Only for legacy user agents (IE11, Safari before 10) that do not implement frame-ancestors. Modern browsers ignore X-Frame-Options whenever frame-ancestors is present, so keep XFO solely as a fallback and let CSP carry the real policy. See the side-by-side comparison.

Why does my page frame anyway when X-Frame-Options is DENY? A Content-Security-Policy: frame-ancestors directive on the same response overrides X-Frame-Options per the CSP spec. If frame-ancestors is more permissive than your XFO value, the permissive policy wins. Align both headers.

Does X-Frame-Options protect against an iframe reading my page’s data? No. Cross-origin DOM reads are blocked by the Same-Origin Policy regardless. Framing headers stop the page from being displayed and clicked through — the clickjacking vector — not data exfiltration.

Can I allowlist multiple partner domains with X-Frame-Options? No. X-Frame-Options supports only DENY and SAMEORIGIN; its ALLOW-FROM form is unsupported in Chromium and Gecko. Use frame-ancestors 'self' https://a.example https://b.example for any allowlist.

Where should these headers be set — origin or CDN? Either, but exactly one layer, to avoid duplicate headers. The edge (Cloudflare) covers cached responses the origin never serves; the origin guarantees coverage even if the CDN is bypassed. Pick one as authoritative.

Can I set frame-ancestors in a <meta> tag instead of an HTTP header? No. The CSP specification lists frame-ancestors among the directives that are ignored when the policy is delivered through <meta http-equiv>. A meta-tag framing policy is silently discarded. It must be an HTTP response header, which also means it can be applied to non-HTML responses and error pages that never carry a meta tag.

Does frame-ancestors fall back to default-src like other CSP directives? No. frame-ancestors has no fallback to default-src. Setting default-src 'none' does not restrict framing; you must declare frame-ancestors explicitly. This is a deliberate spec choice because framing is an ancestor-context decision, not a resource-fetch decision.

How does the browser handle deeply nested frames? It evaluates the complete ancestor chain against your source list, not just the immediate parent. If your page is framed by B, and B is framed by A, both A and B must satisfy frame-ancestors or the load is refused. This prevents an attacker from laundering an embed through an origin you trust.

Do framing headers stop double-clickjacking? No. Double-clickjacking opens your page in a new top-level window rather than an iframe, so there is no ancestor to check and framing headers do not apply. Defend against it in the application: disable or gate sensitive actions until an unambiguous, deliberate user interaction, rather than relying on response headers.

Should I use frame-ancestors in report-only mode first? Yes, as a discovery step. Content-Security-Policy-Report-Only: frame-ancestors 'self' collects violation reports showing which origins embed you without breaking anything. Once you have confirmed the legitimate embedders, move the directive to the enforcing Content-Security-Policy header. Report-only never blocks, so it is not protection on its own.

Related

• X-Frame-Options vs CSP frame-ancestors comparison

• Fixing X-Frame-Options blocking legitimate iframes

• Content Security Policy (CSP) Essentials

• HTTP Strict Transport Security (HSTS) Deep Dive

• Web Security Headers Fundamentals

• Allowing specific origins to frame you — a partner allowlist with frame-ancestors.