Nginx guide · Referrer-Policy

How to set Referrer-Policy on Nginx

Set Referrer-Policy on Nginx with add_header and always, keep it on every location, use a stricter policy on sensitive paths and avoid duplicate headers. Tested configs.

  • By
  • Updated
  • 4 min read
  • Tested on nginx 1.28, 1.30 and 1.31
$ curl -sI https://example.com/missing
status
HTTP/2 404
server
nginx
referrer-policy
strict-origin-when-cross-origin

Present on error pages too

In short4 points
  • Add add_header Referrer-Policy "strict-origin-when-cross-origin" always; to the server block. Without always, 404 and 500 pages are sent without it.
  • 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.
  • Browsers apply the last Referrer-Policy they receive, and Nginx's own header comes after the upstream's. Keep a single header with proxy_hide_header Referrer-Policy;.
  • For a stricter policy on sensitive paths, give the location its own no-referrer header. Under add_header_inherit merge;, add add_header_inherit off; there, or the server's weaker header comes last and wins.

The short answer

Add the header 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 Referrer-Policy "strict-origin-when-cross-origin" always;
}
Shell
sudo nginx -t && sudo systemctl reload nginx

always keeps the header on error pages. 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.

strict-origin-when-cross-origin keeps full URLs on your own origin and sends only the origin to other sites. The Referrer-Policy overview compares the eight values and explains when to choose a stricter one.

Before you start

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

Shell
sudo nginx -T | grep -niE "server_name|add_header|include|proxy_pass|fastcgi_pass|referrer"

Then check your HTML templates for a <meta name="referrer"> tag. It overrides the header in the browser:

Shell
curl -s https://example.com/ | grep -i 'name="referrer"'

You are looking for:

  • Locations with their own add_header. They drop the server-level header (step 3).
  • An existing Referrer-Policy in Nginx or in the application. Two headers cause trouble (step 4).
  • Paths whose URLs carry secrets, such as password reset or invitation links. They deserve a stricter policy (step 5).

Step 1: choose the value

Your site Nginx line
Most sites add_header Referrer-Policy "strict-origin-when-cross-origin" always;
Never reveal where users come from add_header Referrer-Policy "no-referrer" always;
Keep full URLs on your origin, nothing elsewhere add_header Referrer-Policy "same-origin" always;

Do not use unsafe-url or no-referrer-when-downgrade: both send full URLs to other sites, and WebSec0 grades them as a warning. Do not wrap the value in a second pair of quotes, as in '"no-referrer"': browsers receive "no-referrer", treat it as invalid and fall back to their default.

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 Referrer-Policy "strict-origin-when-cross-origin";:

HTTP
HTTP/1.1 200 OK
Referrer-Policy: strict-origin-when-cross-origin

HTTP/1.1 404 Not Found
(no Referrer-Policy header)

A 404 page that links to your home page or loads analytics then falls back to the browser default. 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 Referrer-Policy:

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

    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

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

This matters for CSS files: the fonts and images a stylesheet loads use the stylesheet’s own policy. 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 Referrer-Policy "strict-origin-when-cross-origin" 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 Referrer-Policy "strict-origin-when-cross-origin" always;

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

nginx 1.28 rejects it with unknown directive "add_header_inherit". The X-Frame-Options guide for Nginx and the HSTS guide for Nginx use the same snippet for their headers.

Step 4: one header behind a reverse proxy

Many frameworks send a Referrer-Policy of their own. When Nginx proxies such an application and adds its own line, the response carries both, the upstream’s first. Our test, with an application sending no-referrer-when-downgrade:

HTTP
HTTP/1.1 200 OK
Referrer-Policy: no-referrer-when-downgrade
Referrer-Policy: strict-origin-when-cross-origin

Browsers apply the last value they recognise, so users get Nginx’s policy here, and WebSec0 grades the same value. The trouble comes when the application’s policy is the stricter one: Nginx’s header silently replaces it.

Pick one owner. If it is Nginx, hide the upstream’s header:

Nginx
location / {
    proxy_pass http://app;
    proxy_hide_header Referrer-Policy;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
}

Use fastcgi_hide_header for PHP-FPM and uwsgi_hide_header for uWSGI.

Step 5: a stricter policy on sensitive paths

Pages whose URLs carry a token, such as /reset/?token=…, should send no referrer at all. Give that location its own header:

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

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

    location /reset/ {
        add_header Referrer-Policy "no-referrer" always;
        # Repeat your other security headers here.
    }
}

What our test returned:

URL Referrer-Policy
/ strict-origin-when-cross-origin
/reset/ no-referrer
/reset/does-not-exist (404) no-referrer

Because the location sets its own add_header, it inherits nothing from the server block, so repeat your other security headers in it.

With add_header_inherit merge; at server level, this goes wrong. Nginx puts the location’s header first and the server’s after it:

HTTP
HTTP/1.1 200 OK
Referrer-Policy: no-referrer
Referrer-Policy: strict-origin-when-cross-origin

Browsers apply the last one, so the reset page still sends its origin to other sites instead of nothing. WebSec0 sees the same policy and still passes the page, so the scan does not reveal the mistake. Add add_header_inherit off; as the first line of that location:

Nginx
location /reset/ {
    add_header_inherit off;
    add_header Referrer-Policy "no-referrer" always;
}

Our test then returned a single Referrer-Policy: no-referrer.

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 -i "^referrer-policy"
curl -sI https://example.com/does-not-exist | grep -i "^referrer-policy"
curl -sI https://example.com/assets/app.css | grep -i "^referrer-policy"

Each should print the policy you chose. Count the headers to catch duplicates. The result should be 1:

Shell
curl -sI https://example.com/ | grep -ci '^referrer-policy:'

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 Referrer-Policy headers The upstream application sends one too proxy_hide_header Referrer-Policy; or remove the Nginx line.
A stricter location policy has no effect add_header_inherit merge; puts the server’s header last Add add_header_inherit off; in that location.
WebSec0 shows a warning The last value is unsafe-url or no-referrer-when-downgrade Use strict-origin-when-cross-origin and keep one header.
WebSec0 fails a header that is present No recognised value: a typo or extra quotes Fix the value; browsers ignore it too.
Browser sends more than the header says A <meta name="referrer"> in the page overrides it Remove the tag or make it match.
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

Referrer-Policy on other servers

Questions

Frequently asked questions

Where do I put Referrer-Policy 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.

What is the Nginx line for Referrer-Policy?

add_header Referrer-Policy "strict-origin-when-cross-origin" always;. Check the configuration with nginx -t and reload with systemctl reload nginx.

Why is Referrer-Policy 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.

My response has two Referrer-Policy headers. Which one applies?

Browsers apply the last value they recognise. Behind a proxy, that is usually Nginx's, because headers from the upstream come first. WebSec0 grades the same last value. Keep a single header anyway: remove one with proxy_hide_header Referrer-Policy;.

How do I use a different Referrer-Policy for one URL?

Give that location its own add_header Referrer-Policy "no-referrer" always;. It no longer inherits the server-level headers, so repeat the others there. With add_header_inherit merge;, also add add_header_inherit off; in that location.

Should I set Referrer-Policy 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 policy 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 Referrer-Policy, in a few seconds. Free, no account.

Scan your site