Have you ever embedded a third party asset on your website (like a map, a widget, or an external image) only to find it broken, displaying a blank space, or returning a 403 Forbidden error?
While developers often immediately check for Cross Origin Resource Sharing (CORS) errors or broken links, the culprit is frequently something much simpler but often overlooked: The HTTP Referrer Policy.
In the modern web ecosystem, balancing user privacy with seamless integrations is a delicate act. If your privacy settings are too loose, you leak user data. If they are too strict, external services will block your requests. In this article, we will dive into what the HTTP Referrer header is, how the Referrer Policy controls it, and how to configure it correctly so your web applications function without compromising security.
What is the HTTP "Referer" Header?
When a user clicks a link or when a browser automatically fetches a resource (like loading a script, an image, or an API endpoint), the browser sends an HTTP request to the target server. Historically, this request included an HTTP header called Referer (famously misspelled with a single 'r' in the original HTTP specification, a typo that has remained ever since). This header tells the receiving server the absolute URL of the web page that initiated the request.
Why is it useful?
- Analytics: It allows websites to see where their traffic is coming from (for example, Google Analytics tracking a visitor from a social media site).
- Access Control and Security: APIs and content delivery networks (CDNs) use it to verify that requests are coming from authorized domains, preventing bandwidth theft or hotlinking.
- Logging: Helps developers trace errors and track user flow.
The Privacy Problem
While useful, sending the full URL to external servers poses a significant privacy risk. Imagine a user is on a password reset page: example.com/reset_password?token=12345ABC. If that page loads an external image or a tracking script, the receiving server gets that exact sensitive URL (complete with the reset token) in the Referer header. To stop the leakage of sensitive data across domains, web standards introduced the Referrer Policy.
Enter the Referrer Policy
The Referrer-Policy is an HTTP header (or an HTML <meta> tag) that allows site administrators to explicitly instruct the browser on how much information to include in the Referer header when navigating away from the current page or fetching external resources.
The Most Common Policy Values
Here are the most frequently used values and what they do:
| Policy Value | What it does | Best for |
|---|---|---|
| no-referrer | The browser completely omits the Referer header. The destination server has no idea where the request came from. | Absolute privacy, but will break services that require origin verification. |
| no-referrer-when-downgrade | Sends the full URL when staying on HTTPS. Sends nothing when downgrading from HTTPS to HTTP. | Historical default. Rarely recommended today as the web has moved to HTTPS everywhere. |
| origin | Sends only the domain (e.g., example.com) instead of the full URL path (/path/page.html). | Good privacy, prevents leaking URL parameters. |
| strict-origin-when-cross-origin | (Modern Default) Sends the full URL within the same domain. Sends only the domain to other HTTPS domains. Sends nothing to HTTP. | The golden standard. Balances deep internal analytics with external privacy. |
When Strict Privacy Breaks the Web: A Real World Example
Many modern CMS platforms, security plugins, and hosting environments have started aggressively defaulting to Referrer-Policy: no-referrer to maximize privacy scores on security testing tools. However, using the no-referrer value essentially makes your website anonymous to the outside world. If you rely on external APIs, payment gateways, or CDNs that use referer checking to prevent abuse, your site will suddenly break.
A Practical Example: OpenStreetMap
Recently, this exact scenario played out on a large scale. OpenStreetMap (OSM) tile servers, which provide the map graphics used by countless websites worldwide, updated their usage policies to strictly require a valid Referer header. They did this to block automated scraping and bandwidth abuse from anonymous sources. Suddenly, website owners using strict privacy policies found their interactive maps replaced by grey boxes and "Referer is required" error messages. The browser was stripping the header, and OSM was rejecting the anonymous request.
In the Phoca Maps component, this situation was resolved directly at the software level. Because extension developers cannot control global server settings or third party hosting restrictions, the update explicitly injects a referrerPolicy parameter into the JavaScript map initialization. This overrides the site global block specifically for the map tiles, ensuring they load flawlessly without forcing the entire website to lower its global privacy standards.
How to Configure Your Referrer Policy
If you are experiencing external asset blocks, or if you simply want to audit your site security, you can set your policy at several levels.
Recommendation: For most modern websites, you should aim to use strict-origin-when-cross-origin.
1. Global Web Server Configuration (Recommended)
You can set the policy globally via your web server configuration to ensure it applies to all outbound requests.
Apache (.htaccess):
<IfModule mod_headers.c>
Header set Referrer-Policy "strict-origin-when-cross-origin"
</IfModule>Nginx:
add_header Referrer-Policy "strict-origin-when-cross-origin" always;2. CMS Level (for example Joomla)
Modern Content Management Systems like Joomla have native HTTP header management. In Joomla, you can navigate to System > Plugins > System - HTTP Headers, find the Referrer Policy dropdown, and set it to strict-origin-when-cross-origin.
3. HTML Document Level
If you do not have server access, you can define the policy for a specific page by placing a meta tag in the <head> of your HTML document:
<meta name="referrer" content="strict-origin-when-cross-origin">4. Element and Request Level (For Developers)
If your global site policy is strict (like no-referrer), but you need to load a specific external script, image, or API request, you can apply the policy to individual HTML elements or JavaScript fetch requests:
HTML Elements:
<img src="https://external_site.com/image.jpg" referrerpolicy="strict-origin-when-cross-origin" alt="External Image">JavaScript Fetch API:
fetch('https://api.external_site.com/data', {
referrerPolicy: 'strict-origin-when-cross-origin'
});Conclusion
The HTTP Referrer Policy is an unsung hero of web security, quietly managing the flow of information between your website and the rest of the internet. While turning off all referrers might seem like the ultimate privacy move, the modern web is a highly interconnected ecosystem. External providers need basic origin data to provide secure and stable services. By understanding and utilizing policies like strict-origin-when-cross-origin, developers and site administrators can protect sensitive user data without breaking the tools that make their websites great.