Apache guide · X-Frame-Options

How to set X-Frame-Options on Apache

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.

  • By
  • Updated
  • 6 min read
  • Tested on Apache httpd 2.4.58, 2.4.62 and 2.4.69
$ curl -sI https://example.com/missing
status
HTTP/2 404
server
Apache
x-frame-options
DENY

Present on error pages too

In short5 points
  • Add Header always set X-Frame-Options "DENY" to the VirtualHost, with frame-ancestors 'none' in your Content-Security-Policy. Use SAMEORIGIN and 'self' if your own pages frame each other.
  • Keep always: with Header set, Apache sends no X-Frame-Options header on 404 pages and redirects.
  • Behind mod_proxy_http, an application that sends X-Frame-Options too produces two headers, and DENY plus SAMEORIGIN blocks framing everywhere. Put Header unset X-Frame-Options before the always line.
  • Do not use Header append: it joins the values into one line, DENY, SAMEORIGIN, which browsers and WebSec0 read as a conflict.
  • To let a partner embed one path, give that <Location> its own frame-ancestors and Header always unset X-Frame-Options. Without always, the header stays.

The short answer

Add both lines to the VirtualHost of your site:

Apache
<VirtualHost *:443>
    ServerName example.com
    DocumentRoot "/var/www/example"
    SSLEngine on
    SSLCertificateFile    /etc/ssl/example.com/fullchain.pem
    SSLCertificateKeyFile /etc/ssl/example.com/privkey.pem

    Header always set Content-Security-Policy "frame-ancestors 'none'"
    Header always set X-Frame-Options "DENY"
</VirtualHost>
Shell
sudo apachectl configtest && sudo apachectl graceful

always keeps both headers on error pages and redirects. 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 Apache httpd 2.4.58, 2.4.62 and 2.4.69 and checked with curl, on a page, a 404, a redirect and a proxied application.

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

The Header directive comes from mod_headers. Check that it is loaded, then find your virtual hosts and every existing framing rule:

Shell
apachectl -M | grep headers
apachectl -S
grep -rniE "X-Frame-Options|frame-ancestors|ProxyPass" /etc/apache2/ /etc/httpd/ 2>/dev/null

If headers_module is missing, enable it with sudo a2enmod headers on Debian and Ubuntu, or uncomment its LoadModule line in httpd.conf.

You are looking for three things:

  • An existing X-Frame-Options, in another file, in .htaccess or in the application behind Apache. Two headers cause trouble (step 4).
  • Header set or Header append lines for this header. Both cause surprises (steps 2 and 5).
  • Pages that are framed on purpose, such as widgets or previews. They need their own rule (step 6).

Step 1: choose DENY or SAMEORIGIN

Your site Apache 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 6 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: keep it on error pages and redirects

Apache keeps two tables of response headers. Header set writes to the one used for successful responses; Header always set writes to the one that is also sent on errors and redirects. Our test with Header set X-Frame-Options "DENY":

HTTP
HTTP/1.1 200 OK
X-Frame-Options: DENY

HTTP/1.1 404 Not Found
(no X-Frame-Options header)

HTTP/1.1 301 Moved Permanently
(no X-Frame-Options header)

With Header always set, all three responses carried the header. Error pages are often styled and can carry links or forms. Use always.

Step 3: where to put it

A Header line in the VirtualHost covers the whole site. Apache merges <Directory>, <Files> and <Location> sections on top of it, so a section that sets another header keeps X-Frame-Options:

Apache
<VirtualHost *:443>
    # ...
    Header always set X-Frame-Options "DENY"

    <Location "/assets/">
        # X-Frame-Options is still sent for /assets/.
        Header always set Cache-Control "public, max-age=31536000, immutable"
    </Location>
</VirtualHost>

Our test returned both headers for /assets/app.js. This is the opposite of Nginx, where one add_header in a location drops every inherited header.

To cover every site at once, put the lines in the server configuration, outside any VirtualHost. The security headers hub for Apache shows one file with all six security headers, loaded that way.

Step 4: one header behind a reverse proxy

Many frameworks and security middlewares send X-Frame-Options by default. With mod_proxy_http, the application’s header lands in the default table and Header always set adds yours in the other one. Our test, with an application sending SAMEORIGIN:

HTTP
HTTP/1.1 200 OK
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 Apache, remove the application’s header from the default table, then set yours in the always table:

Apache
<VirtualHost *:443>
    # ...
    ProxyPass "/" "http://127.0.0.1:8080/"
    Header unset X-Frame-Options
    Header always set X-Frame-Options "DENY"
</VirtualHost>

Our test then returned DENY once, on the application’s pages and on its 404s. Apache’s documentation notes that CGI scripts and mod_proxy_fcgi, which runs PHP-FPM, put their headers in the always table, where Header always set replaces them. If the application sends a CSP with frame-ancestors, you can also let it own framing and drop the Apache line: browsers apply frame-ancestors either way.

Step 5: do not append

Old tutorials use Header append X-Frame-Options SAMEORIGIN. append adds the value to an existing header, separated by a comma, instead of a second line. With Header always set X-Frame-Options "DENY" in the virtual host and Header always append X-Frame-Options "SAMEORIGIN" in a <Location>, our test returned:

HTTP
HTTP/1.1 200 OK
X-Frame-Options: DENY, SAMEORIGIN

Browsers split the value on commas, as the HTML Standard specifies, and treat it like two conflicting headers. WebSec0 does the same and grades it as a warning. Replace every append with always set.

Step 6: let a partner embed one path

To let partner.example frame the pages under /embed/ and keep everything else at DENY, give that path its own CSP and remove X-Frame-Options there:

Apache
<VirtualHost *:443>
    # ...
    Header always set Content-Security-Policy "frame-ancestors 'none'"
    Header always set X-Frame-Options "DENY"

    <Location "/embed/">
        Header always set Content-Security-Policy "frame-ancestors 'self' https://partner.example"
        Header always unset X-Frame-Options
    </Location>
</VirtualHost>

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

Write always in the unset line too. The virtual host’s header is in the always table, and a plain Header unset X-Frame-Options only clears the default one: in our test, /embed/ then still returned DENY. Unlike Nginx, the other headers of the virtual host stay in place under /embed/.

If your full CSP is defined in the virtual host, copy the whole policy into the <Location> and change only frame-ancestors. WebSec0 passes these pages too, since their CSP contains frame-ancestors.

On shared hosting: .htaccess

Without access to the virtual host, the same lines work in .htaccess, provided the directory allows it with AllowOverride FileInfo:

Apache
# .htaccess
<IfModule mod_headers.c>
    Header always set Content-Security-Policy "frame-ancestors 'none'"
    Header always set X-Frame-Options "DENY"
</IfModule>

In our test, .htaccess headers were sent on pages, 404s and static files, but not on a Redirect defined in the virtual host: Apache sends it before it reads .htaccess.

Verify it

Check a page, an error page and a redirect. 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, and the value should contain no comma:

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
Invalid command 'Header' mod_headers is not loaded a2enmod headers, or uncomment its LoadModule line.
Header missing on 404 pages or redirects Header set without always Write Header always set.
Two X-Frame-Options headers The proxied application sends one too Add Header unset X-Frame-Options before the always line.
X-Frame-Options: DENY, SAMEORIGIN A Header append line Replace it with Header always set.
Your own iframes stopped loading DENY, or two conflicting values Use SAMEORIGIN and 'self', and send one value.
A partner’s embed is blank X-Frame-Options still sent on that path Use Header always unset X-Frame-Options in its <Location>.
WebSec0 shows a warning Two different values, in two headers or one appended line Keep one header with one value (steps 4 and 5).
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 apachectl configtest && apachectl graceful, then purge the CDN.

Server hub

Every header on Apache

Other web servers

X-Frame-Options on other servers

Questions

Frequently asked questions

Where do I put X-Frame-Options in Apache?

In the VirtualHost of each site, or once in the server configuration to cover every site. Apache merges it into every <Location> and <Directory>, even one that sets other headers.

What is the Apache line for X-Frame-Options?

Header always set X-Frame-Options "DENY", or SAMEORIGIN instead of DENY if your own pages frame each other. It needs mod_headers. Reload with apachectl configtest && apachectl graceful.

Why is X-Frame-Options missing on my 404 pages or redirects?

Header set without always writes to the table Apache uses for successful responses only. Error pages and redirects that Apache generates use the always table. Write Header always set.

Why does my response have two X-Frame-Options headers?

The application behind mod_proxy_http sends one, and Header always set adds yours in another table. Add Header unset X-Frame-Options before the Header always set line, or remove the Apache line and let the application own it.

How do I allow framing for one URL on Apache?

In a <Location> for that path, set a Content-Security-Policy with frame-ancestors 'self' https://partner.example and add Header always unset X-Frame-Options. The other headers of the virtual host stay in place.

Can I set X-Frame-Options in .htaccess?

Yes, with the same Header always set line, when the directory allows it with AllowOverride FileInfo. Wrap it in <IfModule mod_headers.c> if the module might be missing.

References

Sources

  1. Apache Module mod_headersApache HTTP Server Project
  2. .htaccess filesApache HTTP Server Project

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