Nginx guide · X-Frame-Options

How to set X-Frame-Options on Nginx

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.

  • By
  • Updated
  • 5 min read
  • Tested on nginx 1.28, 1.30 and 1.31
$ curl -sI https://example.com/missing
status
HTTP/2 404
server
nginx
x-frame-options
DENY

Present on error pages too

In short5 points
  • Add add_header X-Frame-Options "DENY" always; to the server block, with frame-ancestors 'none' in your Content-Security-Policy. Use SAMEORIGIN and 'self' if your own pages frame each other.
  • Keep always: without it, Nginx sends no X-Frame-Options header on 404 and 500 pages.
  • A location with its own add_header drops the server-level header. Share it through an include file, or use add_header_inherit merge; on nginx 1.29.3 or later.
  • If the upstream application sends X-Frame-Options too, the response carries two headers. SAMEORIGIN plus DENY blocks framing everywhere, even on your own site. Remove one with proxy_hide_header.
  • To let a partner embed one path, give that location its own CSP with frame-ancestors 'self' https://partner.example and no X-Frame-Options.

The short answer

Add both lines to the server block of your site:

Nginx
server {
    listen 443 ssl;
    http2 on;
    server_name example.com;
    ssl_certificate     /etc/ssl/example.com/fullchain.pem;
    ssl_certificate_key /etc/ssl/example.com/privkey.pem;

    add_header Content-Security-Policy "frame-ancestors 'none'" always;
    add_header X-Frame-Options "DENY" always;
}
Shell
sudo nginx -t && sudo systemctl reload nginx

always keeps both headers on error pages. 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 nginx 1.28, 1.30 and 1.31 and checked with curl, on a page, a 404 and a nested location.

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

List every server block, every add_header and every proxied application in the merged configuration:

Shell
sudo nginx -T | grep -nE "server_name|add_header|include|proxy_pass|fastcgi_pass|frame"

You are looking for three things:

  • Locations with their own add_header. They drop the server-level header (step 3).
  • An existing X-Frame-Options or frame-ancestors, in Nginx or in the application behind it. Two headers cause trouble (step 4).
  • Pages that are framed on purpose, such as widgets or previews. They need their own rule (step 5).

Step 1: choose DENY or SAMEORIGIN

Your site Nginx 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 5 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

Without always, Nginx only adds headers to 200, 201, 204, 206, 301, 302, 303, 304, 307 and 308 responses. Our test with add_header 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)

Error pages are often styled and can carry links or forms. Keep always on the line.

Step 3: keep it on every location

add_header directives are inherited from the parent block only if the current block has none. Here, files under /assets/ are served without X-Frame-Options:

Nginx
server {
    listen 443 ssl;
    server_name example.com;
    # ssl_certificate lines...

    add_header X-Frame-Options "DENY" always;

    location /assets/ {
        # This one line removes the server-level X-Frame-Options for /assets/.
        add_header Cache-Control "public, max-age=31536000, immutable" always;
    }
}

Our test returned only Cache-Control for /assets/app.css. The fix that works on every version is a snippet you include wherever a block sets its own headers:

Nginx
# /etc/nginx/snippets/security-headers.conf
add_header Content-Security-Policy "frame-ancestors 'none'" always;
add_header X-Frame-Options "DENY" always;
Nginx
server {
    listen 443 ssl;
    server_name example.com;
    # ssl_certificate lines...

    include /etc/nginx/snippets/security-headers.conf;

    location /assets/ {
        add_header Cache-Control "public, max-age=31536000, immutable" always;
        include /etc/nginx/snippets/security-headers.conf;
    }
}

On nginx 1.29.3 or later, which includes the 1.30 stable branch, add_header_inherit merge; makes nested blocks add their headers to the parent’s instead of replacing them:

Nginx
server {
    listen 443 ssl;
    server_name example.com;
    # ssl_certificate lines...

    add_header_inherit merge;
    add_header X-Frame-Options "DENY" always;

    location /assets/ {
        # Sent together with the server-level X-Frame-Options.
        add_header Cache-Control "public, max-age=31536000, immutable" always;
    }
}

nginx 1.28 rejects it with unknown directive "add_header_inherit". The same trap applies to every security header: the HSTS guide for Nginx and the Content-Security-Policy guide for Nginx use the same snippet.

Step 4: one header behind a reverse proxy

Many frameworks and security middlewares send X-Frame-Options by default. When Nginx proxies such an application and adds its own line, the response carries both. Our test, with an application sending SAMEORIGIN:

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

Browsers combine the two values, see a conflict and block the page in every frame. In our test in Chrome 152, this response could not be framed even by a page on its own origin, 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 Nginx, hide the upstream’s header:

Nginx
location / {
    proxy_pass http://app;
    proxy_hide_header X-Frame-Options;
    add_header X-Frame-Options "DENY" always;
}

Use fastcgi_hide_header for PHP-FPM and uwsgi_hide_header for uWSGI. If the application sends a CSP with frame-ancestors, let it own framing and drop the Nginx line instead: browsers apply frame-ancestors either way.

Step 5: let a partner embed one path

To let partner.example frame the pages under /embed/ and keep everything else at DENY, give that location its own CSP:

Nginx
server {
    listen 443 ssl;
    server_name example.com;
    # ssl_certificate lines...

    include /etc/nginx/snippets/security-headers.conf;

    location /embed/ {
        add_header Content-Security-Policy "frame-ancestors 'self' https://partner.example" always;
        # Repeat your other security headers here, without X-Frame-Options.
    }
}

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

Because the location sets its own add_header, it inherits nothing from the server block. That is what removes X-Frame-Options here, but it also removes your other security headers, so repeat them in the location.

With add_header_inherit merge; at server level, the location would inherit everything: our test returned X-Frame-Options: DENY and both CSP headers, and the partner’s frame stays blocked. Add add_header_inherit off; as the first line of that location to cancel inheritance there.

If your full CSP is defined at server level, copy the whole policy into the location 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 one URL in every location that sets its own headers. 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
Header missing on 404 or 500 pages add_header without always Add always to the line.
Header missing on some URLs That location has its own add_header Include the snippet there, or use add_header_inherit merge; (1.29.3+).
Two X-Frame-Options headers The upstream application sends one too proxy_hide_header X-Frame-Options; or remove the Nginx line.
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 Give the path its own frame-ancestors list (step 5).
WebSec0 shows a warning Two different values, often one from the application Keep one header with one value (step 4).
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.
unknown directive "add_header_inherit" nginx older than 1.29.3 Upgrade, or use the include approach.
Changes do not show up Reload skipped, or a CDN cached old headers nginx -t && systemctl reload nginx, then purge the CDN.

Server hub

Every header on Nginx

Other web servers

X-Frame-Options on other servers

Questions

Frequently asked questions

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

In the server block of each site, or in a snippet included there. A header in the http block reaches every site, but any server or location that sets its own add_header stops inheriting it, which is easy to miss.

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

add_header X-Frame-Options "DENY" always;, or SAMEORIGIN instead of DENY if your own pages frame each other. Reload with nginx -t && systemctl reload nginx.

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

Without the always parameter, Nginx only adds headers to 200, 201, 204, 206, 301, 302, 303, 304, 307 and 308 responses. Add always at the end of the add_header line.

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

The application behind Nginx sends one and Nginx adds another. Proxied headers come first. Add proxy_hide_header X-Frame-Options; (or fastcgi_hide_header for PHP-FPM) in the same block, or remove the Nginx line and let the application own it.

How do I allow framing for one URL on Nginx?

Give that location its own add_header Content-Security-Policy "frame-ancestors 'self' https://partner.example" always;. Because the location sets its own header, it no longer inherits X-Frame-Options from the server block. Repeat any other security headers there.

Should I set X-Frame-Options in Nginx or in my application?

Either, but only one. Nginx covers error pages and static files the application never sees. If the application must vary the value per page, let it own the header and do not add it in Nginx.

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