Referrer Policy

1. Introduction

This section is not normative.

Requests made from a document, and for navigations away from that document are associated with a Referer header. While the header can be suppressed for links with the noreferrer link type, authors might wish to control the Referer header more directly for a number of reasons:

1.1. Privacy

A social networking site has a profile page for each of its users, and users add hyperlinks from their profile page to their favorite bands. The social networking site might not wish to leak the user’s profile URL to the band web sites when other users follow those hyperlinks (because the profile URLs might reveal the identity of the owner of the profile).

Some social networking sites, however, might wish to inform the band web sites that the links originated from the social networking site but not reveal which specific user’s profile contained the links.

1.2. Security

A web application uses HTTPS and a URL-based session identifier. The web application might wish to link to HTTPS resources on other web sites without leaking the user’s session identifier in the URL.

Alternatively, a web application may use URLs which themselves grant some capability. Controlling the referrer can help prevent these capability URLs from leaking via referrer headers. [CAPABILITY-URLS]

1.3. Trackback

A blog hosted over HTTPS might wish to link to a blog hosted over HTTP and receive trackback links.

2. Key Concepts and Terminology

referrer policy

A referrer policy is a property of a settings object that defines the algorithm used to populate the Referer header when fetching subresources, prefetching, or performing navigations.

If no referrer policy is explicitly set for a settings object, then the value of the property is null. Otherwise, the value is whatever has been explicitly set, as explained in the §6.1 Set environment’s referrer policy to policy algorithm.

same-origin request

A Request request is a same-origin request if request’s origin and the origin of request’s url are the same.

cross-origin request

A Request is a cross-origin request if it is not same-origin.

3. Referrer Policy States

Every settings object has a referrer policy which governs the referrer information sent along with requests made for subresources, and for navigations. The policy will be null if no policy has been set, otherwise it will be one of the following five values: No Referrer, No Referrer When Downgrade, Origin Only, Origin When Cross-origin, and Unsafe URL. Each is explained below, and a detailed algorithm for evaluating their effect is given in the §5 Integration with Fetch and §6 Algorithms sections:

Note: The referrer policy for a settings object provides a default baseline policy for requests. This policy may be tightened for specific requests via mechanisms like the noreferrer link type.

3.1. No Referrer

The simplest policy is No Referrer, which specifies that no referrer information is to be sent along with requests made from a particular settings object to any origin. The header will be omitted entirely.

3.2. No Referrer When Downgrade

The No Referrer When Downgrade policy sends a full URL along with requests from TLS-protected settings object to a non-a priori insecure origin, and requests from settings objects which are not TLS-protected to any origin.

Requests from TLS-protected settings objects to a priori insecure origins, on the other hand, will contain no referrer information. A Referer HTTP header will not be sent.

This is a user agent’s default behavior, if no policy is otherwise specified.

3.3. Origin Only

The Origin Only policy specifies that only the ASCII serialization of the origin of the settings object from which a request is made is sent as referrer information when making both same-origin requests and cross-origin requests from a particular settings object.

Note: The serialization of an origin looks like https://example.com. To ensure that a valid URL is sent in the `Referer` header, user agents will append a U+002F SOLIDUS ("/") character to the origin (e.g. https://example.com/).

Note: The Origin Only policy causes the origin of HTTPS referrers to be sent over the network as part of unencrypted HTTP requests.

3.4. Origin When Cross-Origin

The Origin When Cross-Origin policy specifies that a full URL, stripped for use as a referrer, is sent as referrer information when making same-origin requests from a particular settings object, and only the ASCII serialization of the origin of the settings object from which a request is made is sent as referrer information when making cross-origin requests from a particular settings object.

Note: For the Origin When Cross-Origin policy, we also consider protocol upgrades, e.g. requests from http://example.com/ to https://example.com/ to be cross-origin requests.

Note: The Origin When Cross-Origin policy causes the origin of HTTPS referrers to be sent over the network as part of unencrypted HTTP requests.

3.5. Unsafe URL

The Unsafe URL policy specifies that a full URL, stripped for use as a referrer, is sent along with both cross-origin requests and same-origin requests made from a particular settings object.

Note: The policy’s name doesn’t lie; it is unsafe. This policy will leak origins and paths from TLS-protected resources to insecure origins. Carefully consider the impact of setting such a policy for potentially sensitive documents.

4. Referrer Policy Delivery

A settings object’s referrer policy is delivered in one of four ways:

• Via the referrer Content Security Policy directive (defined in §4.1 Delivery via CSP), delivered via the Content-Security-Policy HTTP header. [CSP2]
• Via the referrer Content Security Policy directive (defined in §4.1 Delivery via CSP), delivered via a <meta> element [CSP2]
• Via a meta element with a name of referrer.
• Via a referrer attribute on an a, area, img or iframe element.
• Implicitly, via inheritance.

4.1. Delivery via CSP

The referrer directive specifies the referrer policy that the user agent applies when determining what referrer information should be included with requests made, and with browsing contexts created from the context of the protected resource. The syntax for the name and value of the directive are described by the following ABNF grammar:

directive-name    = "referrer"
directive-value   = "no-referrer" / "no-referrer-when-downgrade" / "origin" / "origin-when-cross-origin" / "unsafe-url"

Note: The directive name does not share the HTTP header’s misspelling.

When enforcing the referrer directive, the user agent MUST execute §6.1 Set environment’s referrer policy to policy on the protected resource’s incumbent settings object, using the result of executing §6.4 Determine token’s Policy on the referrer directive’s value.

Content-Security-Policy: referrer no-referrer;

4.2. Delivery via meta

A referrer policy may be set when an HTML meta element with a name attribute that is an ASCII case-insensitive match for the string "Referrer" is inserted into a document, for example:

<meta name="referrer" content="origin">

The following values for the content attribute are valid, and map to the listed referrer policy values:

no-referrer

No Referrer

origin

Origin

no-referrer-when-downgrade

No Referrer When Downgrade

origin-when-cross-origin

Origin When Cross-Origin

unsafe-url

Unsafe URL

Add the following entry to the pragma directives for the meta element:

Referrer policy (name="Referrer")

1. If the Document’s head element is not an ancestor of the meta element, abort these steps.
2. If the meta element lacks a content attribute then abort these steps.
3. Let environment be the Document's incumbent settings object.
4. Let meta-value be the value of the element’s content attribute, after stripping leading and trailing whitespace.
5. If meta-value is the empty string, then abort these steps.
6. Let policy be the result of executing the §6.4 Determine token’s Policy algorithm on meta-value.
7. Execute the §6.1 Set environment’s referrer policy to policy algorithm on environment using policy, if policy is not null.

Note: Authors are encouraged to avoid the legacy keywords never, default, and always. The keywords no-referrer, no-referrer-when-downgrade, and unsafe-url respectively are preferred.

Note: Implementors are advised to also respect a referrer policy delivered via a meta element during speculative resource loads.

4.3. Delivery via a referrer attribute

A referrer policy may be set when a referrer attribute is added to an a, area, img or iframe element, for example:

<a href="http://example.com" referrer="origin">

The following values for the referrer attribute are valid, and map to the listed referrer policy values:

no-referrer

No Referrer

origin

Origin

unsafe-url

Unsafe URL

A policy delivered via a referrer attribute on an element takes precedence over the policy defined for the whole document via CSP or a meta element.

If an a or area element includes both a referrer attribute as well as a noreferrer link type, should the policy of the referrer attribute take precedence over the link type, as suggested by Martin Thomson, or should we take the more conservative approach as suggested by Brian Smith and honor the noreferrer link type?

4.4. Implicit Delivery

A settings object inherits the referrer policy of another object in several circumstances:

4.4.1. Nested Browsing Contexts

Whenever a user agent creates a nested browsing context containing an iframe srcdoc document or a resource whose origin’s scheme is a local scheme (for instance, a blob or data resource):

1. Let environment be the nested browsing context’s incumbent settings object.
2. Let policy be the parent browsing context’s incumbent settings object’s referrer policy.
3. Execute the §6.1 Set environment’s referrer policy to policy algorithm on environment using policy, if policy is not null.

4.4.2. Workers

Whenever a user agent runs a worker for a script with URL url and url’s scheme is a local scheme:

1. Let environment be the Worker’s incumbent settings object.
2. Let policy be No Referrer When Downgrade.
3. Execute the §6.1 Set environment’s referrer policy to policy algorithm on environment using policy.

5. Integration with Fetch

The Fetch specification calls out to the Determine request’s referrer algorithm as Step 2 of the Fetching algorithm, and uses the response to set the request’s referrer property. Fetch is responsible for serializing the URL provided, and setting the `Referer` header on request.

6. Algorithms

6.1. Set environment’s referrer policy to policy

If no referrer policy has been set for a settings object, then setting its value is straightforward. If a policy has previously been set, then we overwrite it with the new value.

1. If policy is not one of No Referrer, No Referrer When Downgrade, Origin Only, Origin when cross-origin, or Unsafe URL, then return without setting environment’s referrer policy.
2. Set environment’s referrer policy to policy.

6.2. Determine request’s Referrer

Given a Request request, we can determine the correct referrer information to send by examining the policy associated with its client, as detailed in the following steps, which return either no referrer or a URL:

Note: If Fetch is performing a navigation in response to a link of type noreferrer, then request’s referrer will be no referrer, and Fetch won’t call into this algorithm.

This algorithm needs to be modifed to take into account any local overrides via the referrer attribute on elements.

1. Let environment be request’s client.
2. Let policy be the value of environment’s referrer policy.
3. If request’s referrer is a URL, then let referrerSource be request’s referrer. Otherwise:
   1. If environment is a document environment:
      1. Let document be the Document object of the active document of the browsing context of environment’s responsible browsing context.
   2. Otherwise, environment is a worker environment:
      1. Let source be the API referrer source specified by the incumbent settings object.
      2. If source is a URL, let referrerSource be source, otherwise let document be source.
   3. If document is set, execute the following steps:
      1. If document’s origin is not a scheme/host/port tuple (because, for example, it has been sandboxed into a unique origin), return no referrer and abort these steps.
      2. While document corresponds to an iframe srcdoc Document, let document be that Document’s browsing context’s browsing context container’s Document.
      3. Let referrerSource be document’s URL.
4. Let referrerURL be the result of stripping referrerSource for use as a referrer.
5. Let referrerOrigin be the result of stripping referrerSource for use as a referrer, with the origin-only flag set to true.
6. Execute the statements corresponding to the value of policy:

   policy is No Referrer

   Return no referrer

   policy is Origin Only

   Return referrerOrigin

   policy is Unsafe URL

   Return referrerURL.

   policy is Origin When Cross-Origin

   1. If request is a cross-origin request, then return referrerOrigin.
   2. Otherwise, return referrerURL.

   policy is No Referrer When Downgrade

   policy is null

   1. If environment is TLS-protected and the origin of request’s URL is an a priori insecure origin, then return no referrer.
   2. Otherwise, return requestURL.

6.3. Strip url for use as a referrer

Certain portions of URLs MUST not be included when sending a URL as the value of a `Referer` header: a URLs fragment, username, and password components should be stripped from the URL before it’s sent out. This algorithm accepts a origin-only flag, which defaults to false. If set to true, the algorithm will additionally remove the URL’s path and query components, leaving only the scheme, host, and port.

1. If url is null, return no referrer.
2. If url’s scheme is a local scheme, then return no referrer.
3. Set url’s username to the empty string.
4. Set url’s password to null.
5. Set url’s fragment to null.
6. If the origin-only flag is true, then:
   1. Set url’s path to null.
   2. Set url’s query to null.
7. Return url.

6.4. Determine token’s Policy

Given a string token (for example, the value of a referrer directive), this algorithm will return the referrer policy it refers to:

1. If token is an ASCII case-insensitive match for the strings "never" or "no-referrer", return No Referrer.
2. If token is an ASCII case-insensitive match for the string "origin", return Origin.
3. If token is ASCII case-insensitive match for the string "default" or "no-referrer-when-downgrade", return No Referrer When Downgrade.
4. If token is ASCII case-insensitive match for the string "origin-when-cross-origin", return Origin When Cross-Origin.
5. If token is ASCII case-insensitive match for the strings "always" or "unsafe-url", return Unsafe URL.
6. Return No Referrer.

Note: Authors are encouraged to avoid the legacy keywords never, default, and always. The keywords no-referrer, no-referrer-when-downgrade, and unsafe-url respectively are preferred.

7. Privacy Considerations

7.1. User Controls

Nothing in this specification should be interpreted as preventing user agents from offering options to users which would change the information sent out via a `Referer` header. For instance, user agents MAY allow users to suppress the referrer header entirely, regardless of the active referrer policy on a page.

8. Acknowledgements

This specification is based in large part on Adam Barth and Jochen Eisinger’s Meta referrer document.