2. X-Frame-Options Header

The X-Frame-Options HTTP header field indicates a policy that specifies whether the browser should render the transmitted resource within a <frame> or an <iframe>. Servers can declare this policy in the header of their HTTP responses to prevent clickjacking attacks, which ensures that their content is not embedded into other sites.

2.1 Syntax

The header field name is:

X-Frame-Options

There are three different values for the header field. These are mutually exclusive; that is, the header field MUST be set to exactly one of the three values.

DENY

A browser receiving content with this header field MUST NOT display this content in any frame.

SAMEORIGIN

A browser receiving content with this header field MUST NOT display this content in any frame from a page of different origin than the content itself. If a browser or plugin cannot reliably determine whether or not the origin of the content and the frame are the same, this MUST be treated as "DENY".

Please note that current implementations vary on the interpretation of this criteria. In some, it is only required that the top-level browsing context's origin matches the origin of the content using the X-Frame-Options directive; in others, this criteria must be satisfied for all ancestor browsing contexts. For more details on the nesting of frames and variations in the behavior of this header field in different browsers, see Section 2.3.2.2. In addition, refer to Section 4, paragraph 2 for the resulting potential security issues that may result from this.

ALLOW-FROM (followed by a serialized-origin [RFC6454])

A browser receiving content with this header field MUST NOT display this content in a frame from any page with a top-level browsing context of different origin than the specified origin. While this header value may have limited support, it is being deprecated in modern browsers.

Note that the X-Frame-Options header field MUST be sent as an HTTP header field and browsers specifically ignore instances found within the <meta http-equiv> tag.

2.2 Augmented Backus-Naur Form (ABNF)

The RFC 5234 ABNF [RFC5234] of the X-Frame-Options header field value is the following:

id-name                = "X-Frame-Options"
X-Frame-Options        = "DENY"
                        / "SAMEORIGIN"
                        / ( "ALLOW-FROM" RWS serialized-origin )

RWS                    = 1*( SP / HTAB )
                        ; required whitespace

serialized-origin      = scheme "://" host [ ":" port ]
                        ; <scheme>, <host>, <port> as per RFC 6454

where "serialized-origin" is as defined in RFC 6454 [RFC6454], Section 6.2. The production "serialized-origin" implies that the serialized origin string may not include any whitespace.

2.2.1 Examples of X-Frame-Options

X-Frame-Options: DENY
X-Frame-Options: SAMEORIGIN
X-Frame-Options: ALLOW-FROM https://example.com/

2.3 Design Issues

2.3.1 Enable HTML Content from Other Domains

There are a number of main direct vectors that enable HTML content from other domains, for example:

<frame> elements
<iframe> elements
<object> elements
<applet> elements
<embed> elements

Besides these, other elements may be leveraged to take action in the parent frames that may contribute to a clickjacking-like attack, including the <script> tag, the <form> tag, and the <button> tag, among others. The X-Frame-Options header field provides a mechanism by which site operators may indicate that their pages should not be embedded in frames from other domains, and thereby defend against clickjacking attacks.

2.3.2 Browser Behavior and Processing

2.3.2.1 Violation of X-Frame-Options

When a browser detects an X-Frame-Options header that prevents the page from being rendered in a frame, the browser MUST immediately cease rendering the document.

The page must be treated as though the user had canceled the request to load the document. This is similar to the manner in which the user agent processes the "204 No Content" response, though the latter does not result in an error condition.

If the browser has already started to download images or other included resource requests in the page, the browser SHOULD attempt to stop the download of those resources as soon as possible.

2.3.2.2 Variation in Current Browser Behavior

Browsers differ in their interpretation of the frame and browsing context check that is required when the SAMEORIGIN header field is used. The intended behavior is that the user agent MUST only render the page in a frame if that frame is in the same origin as the page being framed.

However, browser implementations differ. Some implementations walk the entire ancestor tree of browsing contexts and require that each ancestor be in the same origin. Others only verify that the top-level browsing context (the window) is from the same origin.

This means that, for pages that are "framed" through multiple intermediate pages (i.e., a frame within a frame within a frame), the set of pages that will be successfully rendered may be more restrictive (in implementations that check the entire ancestor chain) or less restrictive (in implementations that only check the top-level frame) than the specification intends.

Site operators should be aware of this potential difference in behavior and test rendering within their expected browser base to ensure compliance with their anti-clickjacking policies.

2.3.2.3 Usage Design Pattern and Example Scenario for the ALLOW-FROM Parameter

Due to weak support and varying implementations across different browsers, the ALLOW-FROM option has been deprecated. Site operators SHOULD consider using Content Security Policy's frame-ancestors directive [CSP2] instead, which provides better control over frame embedding policies and has better browser support.

2.3.2.4 No Caching of the X-Frame-Options Header

Browsers MUST process the X-Frame-Options header field value for each HTTP response, regardless of cache directives present in that HTTP response or previously cached responses. The header field is evaluated at navigation time and MUST NOT be cached. This ensures that the most current policy is enforced.