- Add
add_header X-Frame-Options "DENY" always;to theserverblock, withframe-ancestors 'none'in your Content-Security-Policy. UseSAMEORIGINand'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
locationwith its ownadd_headerdrops the server-level header. Share it through anincludefile, or useadd_header_inherit merge;on nginx 1.29.3 or later. - If the upstream application sends X-Frame-Options too, the response carries two headers.
SAMEORIGINplusDENYblocks framing everywhere, even on your own site. Remove one withproxy_hide_header. - To let a partner embed one path, give that
locationits own CSP withframe-ancestors 'self' https://partner.exampleand no X-Frame-Options.
The short answer
Add both lines to the server block of your site:
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;
}sudo nginx -t && sudo systemctl reload nginxalways 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:
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/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:
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:
# /etc/nginx/snippets/security-headers.conf
add_header Content-Security-Policy "frame-ancestors 'none'" always;
add_header X-Frame-Options "DENY" always;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:
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/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-Frame-Options: DENYBrowsers 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:
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:
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:
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:
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
Apache
Guide ↗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.
Caddy
Guide ↗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.
Traefik
Guide ↗Set X-Frame-Options on Traefik with frameDeny or customFrameOptionsValue, pair it with CSP frame-ancestors and let a partner embed one path. Tested configs.
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
- X-Frame-Options headerMDN Web Docs
- CSP: frame-ancestorsMDN Web Docs
