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 the empty string. Otherwise, the value is whatever has been explicitly set, as explained in the §8.2 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 the empty string 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 §6 Integration with Fetch and §8 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-Policy HTTP header (defined in §4.1 Delivery via Referrer-Policy header).
• Via a meta element with a name of referrer.
• Via a referrerpolicy content attribute on an a, area, img, iframe, or link element.
• Implicitly, via inheritance.

4.1. Delivery via Referrer-Policy header

The Referrer-Policy HTTP header 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 header are described by the following ABNF grammar:

"Referrer-Policy:" 1#policy-token

policy-token   = "no-referrer" / "no-referrer-when-downgrade" / "origin" / "origin-when-cross-origin" / "unsafe-url"

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

§6 Integration with Fetch and §7 Integration with HTML describe how the Referrer-Policy header is processed.

Referrer-Policy: 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 §8.5 Determine token’s Policy algorithm on meta-value.
7. Execute the §8.2 Set environment’s referrer policy to policy algorithm on environment using policy.

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 referrerpolicy content attribute

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

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

The following values for the referrerpolicy 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

A policy delivered via a referrerpolicy content attribute on an element takes precedence over the policy defined for the whole document via Referrer-Policy header or a meta element unless the attribute value is invalid.

NOTE: If an a or area element includes both a referrerpolicy attribute as well as a noreferrer link type then the noreferrer link type will take precedence and the No Referrer policy takes effect.

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 §8.2 Set environment’s referrer policy to policy algorithm on environment using policy.

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 §8.2 Set environment’s referrer policy to policy algorithm on environment using policy.

5. Element interface extensions

5.1. HTMLAnchorElement

partial interface HTMLAnchorElement {
  attribute DOMString referrerPolicy;
};

5.1.1. Attributes

5.2. HTMLAreaElement

partial interface HTMLAreaElement {
  attribute DOMString referrerPolicy;
};

5.2.1. Attributes

5.3. HTMLImageElement

partial interface HTMLImageElement {
  attribute DOMString referrerPolicy;
};

5.3.1. Attributes

5.4. HTMLIFrameElement

partial interface HTMLIFrameElement {
  attribute DOMString referrerPolicy;
};

5.4.1. Attributes

5.5. HTMLLinkElement

partial interface HTMLLinkElement {
  attribute DOMString referrerPolicy;
};

5.5.1. Attributes

6. Integration with Fetch

The Fetch specification should have a referrer policy associated with responses.

The Fetch specification should call out to the §8.1 Set response’s referrer policy from a Referrer-Policy header algorithm immediately after Step 7 of the HTTP-network fetch algorithm. This algorithm sets the associated referrer policy on a response.

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

7. Integration with HTML

When a Document or WorkerGlobalScope is created with a response (response) that has a non-empty referrer policy, then execute §8.2 Set environment’s referrer policy to policy on response’s environment.

8. Algorithms

8.1. Set response’s referrer policy from a Referrer-Policy header

Let policy-tokens be the list of tokens in the Referrer-Policy header value.

1. Let policy be the empty string.
2. For each token in policy-tokens, execute §8.5 Determine token’s Policy on token and set policy to the result if it is not the empty string.
3. Set response’s associated referrer policy to policy.

8.2. 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 if the new value is not the empty string.

1. If policy is the empty string, abort these steps.
2. 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.
3. Set environment’s referrer policy to policy.

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

1. Let policy be the empty string.
2. If request is the result of following a redirect from an HTTP Redirection 3xx response, then let referrerSource be request’s referrer, and let policy be response’s associated referrer policy. If referrerSource is null, then return no referrer and abort these steps.
3. Otherwise, if request is not the result of following a redirect:
   1. Let environment be request’s client.
   2. If request was initiated by an element with a referrerpolicy content attribute, let policy be the attribute’s value. Otherwise, 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 the empty string.

   1. If request is the result of following an HTTP Redirection 3xx response:
      1. If the request that returned the Redirection 3xx response was TLS-protected and the origin of request’s URL is an a priori insecure origin, then return no referrer.
      2. Otherwise, return referrerURL.
   2. Otherwise:
      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 referrerURL.

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

8.5. Determine token’s Policy

Given a string token (for example, the value of a Referrer-Policy header), 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. If token is empty, return No Referrer.
7. Return the empty string.

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.

9. Privacy Considerations

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

10. Security Considerations

10.1. Information Leakage

The referrer policies origin and unsafe-url might leak the origin and the URL of a secure site respectively via insecure transport.

Those two policies are include in the spec nevertheless to lower the friction of sites adopting secure transport.

10.2. Downgrade to less strict policies

The spec does not forbid downgrading to less strict policies, e.g., from never to unsafe-url.

On the one hand, it is not clear which policy is more strict for all possible pairs of policies: While no-referrer-when-downgrade will not leak any information over insecure transport, and origin will, the latter reveals less information across cross-origin navigations.

On the other hand, allowing for setting less strict policies enables authors to define safe fallbacks as described in §11.1 Unknown Policy Values.

11. Authoring Considerations

11.1. Unknown Policy Values

As described in §8.5 Determine token’s Policy and §8.2 Set environment’s referrer policy to policy, unknown policy values will be ignored, and when multiple sources specify a referrer policy, the value of the latest one will be used. This makes it possible to deploy new policy values.

12. Acknowledgements

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