- Add
add_header Referrer-Policy "strict-origin-when-cross-origin" always;to theserverblock. Withoutalways, 404 and 500 pages are sent without it. - 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. - 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
locationits ownno-referrerheader. Underadd_header_inherit merge;, addadd_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:
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;
}sudo nginx -t && sudo systemctl reload nginxalways 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:
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:
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/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:
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:
# /etc/nginx/snippets/security-headers.conf
add_header Referrer-Policy "strict-origin-when-cross-origin" 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 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/1.1 200 OK
Referrer-Policy: no-referrer-when-downgrade
Referrer-Policy: strict-origin-when-cross-originBrowsers 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:
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:
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/1.1 200 OK
Referrer-Policy: no-referrer
Referrer-Policy: strict-origin-when-cross-originBrowsers 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:
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:
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:
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
Apache
Guide ↗Set Referrer-Policy on Apache with Header always set, keep it on errors and redirects, use no-referrer on sensitive paths and stop a proxied app's value winning. Tested.
Caddy
Guide ↗Set Referrer-Policy on Caddy with the header directive, use no-referrer on sensitive paths with route, and stop a proxied app's weaker value from winning. Tested configs.
Traefik
Guide ↗Set Referrer-Policy on Traefik with the referrerPolicy option of the headers middleware, in labels or a file, and use no-referrer on sensitive paths. Tested configs.
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
- Referrer-Policy headerMDN Web Docs
