# 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.

Author: Joshua Martinelle, Security engineer at Tenable (https://www.websec0.com/guides/authors/joshua-martinelle/)
Canonical: https://www.websec0.com/guides/x-frame-options/nginx/
Updated: 2026-10-12
Tested on: nginx 1.28, 1.30 and 1.31

## In short

- 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;
}
```

```sh
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](/guides/x-frame-options/) 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:

```sh
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](/guides/strict-transport-security/nginx/) and the
[Content-Security-Policy guide for Nginx](/guides/content-security-policy/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:

```sh
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`:

```sh
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. |

## 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.

## Sources

- [Module ngx_http_headers_module: add_header and add_header_inherit](https://nginx.org/en/docs/http/ngx_http_headers_module.html), nginx.org
- [Module ngx_http_proxy_module: proxy_hide_header](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header), nginx.org
- [Module ngx_http_fastcgi_module: fastcgi_hide_header](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_hide_header), nginx.org
- [HTML Standard: the X-Frame-Options header](https://html.spec.whatwg.org/#the-x-frame-options-header), WHATWG
- [X-Frame-Options header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options), MDN Web Docs
- [CSP: frame-ancestors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-ancestors), MDN Web Docs
