Maud Nalpas on web.dev

Network Error Logging (NEL)

2022-01-31T00:00:00Z

Introduction #

Network Error Logging (NEL) is a mechanism for collecting client-side network errors from an origin.

It uses the NEL HTTP response header to tell the browser to collect network errors, then integrates with the Reporting API to report the errors to a server.

Overview of the legacy Reporting API #

The legacy `Report-To` Header #

To use the legacy Reporting API, you'll need to set a Report-To HTTP response header. Its value is an object which describes an endpoint group for the browser to report errors to:

Report-To:
{
    "max_age": 10886400,
    "endpoints": [{
    "url": "https://analytics.provider.com/browser-errors"
    }]
}

If your endpoint URL lives on a different origin than your site, the endpoint should support CORS preflight requests. (e.g. Access-Control-Allow-Origin: *; Access-Control-Allow-Methods: GET,PUT,POST,DELETE,OPTIONS; Access-Control-Allow-Headers: Content-Type, Authorization, Content-Length, X-Requested-With).

In the example, sending this response header with your main page configures the browser to report browser-generated warnings to the endpoint https://analytics.provider.com/browser-errors for max_age seconds. It's important to note that all subsequent HTTP requests made by the page (for images, scripts, etc.) are ignored. Configuration is setup during the response of the main page.

Explanation of header fields #

Each endpoint configuration contains a group name, max_age, and endpoints array. You can also choose whether to consider subdomains when reporting errors by using the include_subdomains field.

Field	Type	Description
`group`	string	Optional. If a `group` name is not specified, the endpoint is given a name of "default".
`max_age`	number	Required. A non-negative integer that defines the lifetime of the endpoint in seconds. A value of "0" will cause the endpoint group to be removed from the user agent’s reporting cache.
`endpoints`	Array<Object>	Required. An array of JSON objects that specify the actual URL of your report collector.
`include_subdomains`	boolean	Optional. A boolean that enables the endpoint group for all subdomains of the current origin's host. If omitted or anything other than "true", the subdomains are not reported to the endpoint.

The group name is a unique name used to associate a string with an endpoint. Use this name in other places that integrate with the Reporting API to refer to a specific endpoint group.

The max-age field is also required and specifies how long the browser should use the endpoint and report errors to it.

The endpoints field is an array to provide failover and load balancing features. See the section on Failover and load balancing. It's important to note that the browser will select only one endpoint, even if the group lists several collectors in endpoints. If you want to send a report to several servers at once, your backend will need to forward the reports.

How does the browser send reports? #

The browser periodically batches reports and sends them to the reporting endpoints that you configure.

To send reports, the browser issues a POST request with Content-Type: application/reports+json and a body containing the array of warnings/errors which were captured.

When does the browser send reports? #

Reports are delivered out-of-band from your app, meaning the browser controls when reports are sent to your server(s).

The browser attempts to deliver queued reports at the most opportune time. This may be as soon as they're ready (in order to provide timely feedback to the developer) but the browser can also delay delivery if it's busy processing higher priority work, or if the user is on a slow and/or congested network at the time. The browser may also prioritize sending reports about a particular origin first, if the user is a frequent visitor.

There's little to no performance concern (e.g. network contention with your app) when using the Reporting API. There's also no way to control when the browser sends queued reports.

Configuring multiple endpoints #

A single response can configure several endpoints at once by sending multiple Report-To headers:

Report-To: {
             "group": "default",
             "max_age": 10886400,
             "endpoints": [{
               "url": "https://example.com/browser-reports"
             }]
           }
Report-To: {
             "group": "network-errors-endpoint",
             "max_age": 10886400,
             "endpoints": [{
               "url": "https://example.com/network-errors"
             }]
           }

or by combining them into a single HTTP header:

Report-To: {
             "group": "network-errors-endpoint",
             "max_age": 10886400,
             "endpoints": [{
               "url": "https://example.com/network-errors"
             }]
           },
           {
             "max_age": 10886400,
             "endpoints": [{
               "url": "https://example.com/browser-errors"
             }]
           }

Once you've sent the Report-To header, the browser caches the endpoints according to their max_age values, and sends all of those nasty console warnings/errors to your URLs.

Failover and load balancing #

Most of the time you'll be configuring one URL collector per group. However, since reporting can generate a good deal of traffic, the spec includes failover and load-balancing features inspired by the DNS SRV record.

The browser will do its best to deliver a report to at most one endpoint in a group. Endpoints can be assigned a weight to distribute load, with each endpoint receiving a specified fraction of reporting traffic. Endpoints can also be assigned a priority to set up fallback collectors.

Fallback collectors are only tried when uploads to primary collectors fail.

Example: Create a fallback collector at https://backup.com/reports:

Report-To: {
             "group": "endpoint-1",
             "max_age": 10886400,
             "endpoints": [
               {"url": "https://example.com/reports", "priority": 1},
               {"url": "https://backup.com/reports", "priority": 2}
             ]
           }

Setting up Network Error Logging #

Setup #

To use NEL, set up the Report-To header with a collector that uses a named group:

Report-To: {
    ...
  }, {
    "group": "network-errors",
    "max_age": 2592000,
    "endpoints": [{
      "url": "https://analytics.provider.com/networkerrors"
    }]
  }

Next, send the NEL response header to start collecting errors. Since NEL is opt-in for an origin, you only need to send the header once. Both NEL and Report-To will apply to future requests to the same origin and will continue to collect errors according to the max_age value that was used to set up the collector.

The header value should be a JSON object that contains a max_age and report_to field. Use the latter to reference the group name of your network errors collector:

GET /index.html HTTP/1.1
NEL: {"report_to": "network-errors", "max_age": 2592000}

Subresources #

Example: If example.com loads foobar.com/cat.gif and that resource fails to load:

foobar.com's NEL collector is notified
example.com's NEL collector is not notified

The rule of thumb is that NEL reproduces server-side logs, just generated on the client.

Since example.com has no visibility into foobar.com's server logs, it also has no visibility into its NEL reports.

Debugging report configurations #

If you don't see reports showing up on your server, head over to chrome://net-export/. That page is useful for verifying things are configured correctly and reports are being sent out properly.

What about ReportingObserver? #

ReportingObserver is a related, but different reporting mechanism. It's based on JavaScript calls. It's not suited for network error logging, as network errors can't be intercepted via JavaScript.

Example server #

Below is an example Node server that uses Express. It shows how to configure reporting for network errors, and creates a dedicated handler to capture the result.

const express = require('express');

const app = express();
app.use(
  express.json({
    type: ['application/json', 'application/reports+json'],
  }),
);
app.use(express.urlencoded());

app.get('/', (request, response) => {
  // Note: report_to and not report-to for NEL.
  response.set('NEL', `{"report_to": "network-errors", "max_age": 2592000}`);

  // The Report-To header tells the browser where to send network errors.
  // The default group (first example below) captures interventions and
  // deprecation reports. Other groups, like the network-error group, are referenced by their "group" name.
  response.set(
    'Report-To',
    `{
    "max_age": 2592000,
    "endpoints": [{
      "url": "https://reporting-observer-api-demo.glitch.me/reports"
    }],
  }, {
    "group": "network-errors",
    "max_age": 2592000,
    "endpoints": [{
      "url": "https://reporting-observer-api-demo.glitch.me/network-reports"
    }]
  }`,
  );

  response.sendFile('./index.html');
});

function echoReports(request, response) {
  // Record report in server logs or otherwise process results.
  for (const report of request.body) {
    console.log(report.body);
  }
  response.send(request.body);
}

app.post('/network-reports', (request, response) => {
  console.log(`${request.body.length} Network error reports:`);
  echoReports(request, response);
});

const listener = app.listen(process.env.PORT, () => {
  console.log(`Your app is listening on port ${listener.address().port}`);
});

Security headers quick reference

2021-05-18T00:00:00Z

This article lists the most important security headers you can use to protect your website. Use it to understand web-based security features, learn how to implement them on your website, and as a reference for when you need a reminder.

Security headers recommended for websites that handle sensitive user data:: Content Security Policy (CSP); Trusted Types
Security headers recommended for all websites:: X-Content-Type-Options; X-Frame-Options; Cross-Origin Resource Policy (CORP); Cross-Origin Opener Policy (COOP); HTTP Strict Transport Security (HSTS)
Security headers for websites with advanced capabilities:: Cross-Origin Resource Sharing (CORS); Cross-Origin Embedder Policy (COEP)

Known threats on the web

Before diving into security headers, learn about known threats on the web and why you'd want to use these security headers.

Protect your site from injection vulnerabilities #

Injection vulnerabilities arise when untrusted data processed by your application can affect its behavior and, commonly, lead to the execution of attacker-controlled scripts. The most common vulnerability caused by injection bugs is cross-site scripting (XSS) in its various forms, including reflected XSS, stored XSS, DOM-based XSS, and other variants.

An XSS vulnerability can typically give an attacker complete access to user data processed by the application and any other information hosted in the same web origin.

Traditional defenses against injections include consistent use of autoescaping HTML template systems, avoiding the use of dangerous JavaScript APIs, and properly processing user data by hosting file uploads in a separate domain and sanitizing user-controlled HTML.

Use Content Security Policy (CSP) to control which scripts can be executed by your application to mitigate the risk of injections.
Use Trusted Types to enforce sanitization of data passed into dangerous JavaScript APIs.
Use X-Content-Type-Options to prevent the browser from misinterpreting the MIME types of your website's resources, which can lead to script execution.

Isolate your site from other websites #

The openness of the web allows websites to interact with each other in ways that can violate an application's security expectations. This includes unexpectedly making authenticated requests or embedding data from another application in the attacker's document, allowing the attacker to modify or read application data.

Common vulnerabilities that undermine web isolation include clickjacking, cross-site request forgery (CSRF), cross-site script inclusion (XSSI), and various cross-site leaks.

Use X-Frame-Options to prevent your documents from being embedded by a malicious website.
Use Cross-Origin Resource Policy (CORP) to prevent your website's resources from being included by a cross-origin website.
Use Cross-Origin Opener Policy (COOP) to protect your website's windows from interactions by malicious websites.
Use Cross-Origin Resource Sharing (CORS) to control access to your website's resources from cross-origin documents.

Post-Spectre Web Development is a great read if you are interested in these headers.

Build a powerful website securely #

Spectre puts any data loaded into the same browsing context group potentially readable despite same-origin policy. Browsers restrict features that may possibly exploit the vulnerability behind a special environment called "cross-origin isolation". With cross-origin isolation, you can use powerful features such as SharedArrayBuffer.

Use Cross-Origin Embedder Policy (COEP) along with COOP to enable cross-origin isolation.

Encrypt traffic to your site #

Encryption issues appear when an application does not fully encrypt data in transit, allowing eavesdropping attackers to learn about the user's interactions with the application.

Insufficient encryption can arise in the following cases: not using HTTPS, mixed content, setting cookies without the Secure attribute (or __Secure prefix), or lax CORS validation logic.

Use HTTP Strict Transport Security (HSTS) to consisitently serve your contents through HTTPS.

Content Security Policy (CSP) #

Cross-Site Scripting (XSS) is an attack where a vulnerability on a website allows a malicious script to be injected and executed.

Content-Security-Policy provides an added layer to mitigate XSS attacks by restricting which scripts can be executed by the page.

It's recommended that you enable strict CSP using one of the following approaches:

If you render your HTML pages on the server, use a nonce-based strict CSP.
If your HTML has to be served statically or cached, for example if it's a single-page application, use a hash-based strict CSP.

Example usage: A nonce-based CSP

Content-Security-Policy:
  script-src 'nonce-{RANDOM1}' 'strict-dynamic' https: 'unsafe-inline';
  object-src 'none';
  base-uri 'none';

How to use CSP

Recommended usages #

1. Use a nonce-based strict CSP #

If you render your HTML pages on the server, use a nonce-based strict CSP.

Generate a new script nonce value for every request on the server side and set the following header:

server configuration file

Content-Security-Policy:
  script-src 'nonce-{RANDOM1}' 'strict-dynamic' https: 'unsafe-inline';
  object-src 'none';
  base-uri 'none';

In HTML, in order to load the scripts, set the nonce attribute of all <script> tags to the same {RANDOM1} string.

index.html

<script nonce="{RANDOM1}" src="https://example.com/script1.js"></script>
<script nonce="{RANDOM1}">
  // Inline scripts can be used with the `nonce` attribute.
</script>

Google Photos is a good nonce-based strict CSP example. Use DevTools to see how it's used.

2. Use a hash-based strict CSP #

If your HTML has to be served statically or cached, for example if you're building a single-page application, use a hash-based strict CSP.

server configuration file

Content-Security-Policy:
  script-src 'sha256-{HASH1}' 'sha256-{HASH2}' 'strict-dynamic' https: 'unsafe-inline';
  object-src 'none';
  base-uri 'none';

In HTML, you'll need to inline your scripts in order to apply a hash-based policy, because most browsers don't support hashing external scripts.

index.html

<script>
...// your script1, inlined
</script>
<script>
...// your script2, inlined
</script>

To load external scripts, read "Load sourced scripts dynamically" under Option B: Hash-based CSP Response Header section.

CSP Evaluator is a good tool to evaluate your CSP, but at the same time a good nonce-based strict CSP example. Use DevTools to see how it's used.

Supported browsers #

Browser support

Chrome, Not supported
Firefox, Not supported
Edge, Not supported
Safari, Not supported

Other things to note about CSP #

frame-ancestors directive protects your site from clickjacking—a risk that arises if you allow untrusted sites to embed yours. If you prefer simpler solution, you can use X-Frame-Options to block being loaded, but frame-ancestors gives you an advanced configuration to only allow specific origins as embedders.
You may have used a CSP to ensure that all of your site's resources are loaded over HTTPS. This has become less relevant: nowadays, most browsers block mixed-content.
You can also set a CSP in report-only mode.
If you can't set a CSP as a header server-side, you can also set it as a meta tag. Note that you can't use report-only mode for meta tags (though this may change).

Learn more #

Trusted Types #

DOM-based XSS is an attack where a malicious data is passed into a sink that supports dynamic code execution such as eval() or .innerHTML.

Trusted Types provide the tools to write, security review, and maintain applications free of DOM XSS. They can be enabled via CSP and make JavaScript code secure by default by limiting dangerous web APIs to only accept a special object—a Trusted Type.

To create these objects you can define security policies in which you can ensure that security rules (such as escaping or sanitization) are consistently applied before the data is written to the DOM. These policies are then the only places in code that could potentially introduce DOM XSS.

Example usages

Content-Security-Policy: require-trusted-types-for 'script'

// Feature detection
if (window.trustedTypes && trustedTypes.createPolicy) {
  // Name and create a policy
  const policy = trustedTypes.createPolicy('escapePolicy', {
    createHTML: str => {
      return str.replace(/\</g, '&lt;').replace(/>/g, '&gt;');
    }
  });
}

// Assignment of raw strings is blocked by Trusted Types.
el.innerHTML = 'some string'; // This throws an exception.

// Assignment of Trusted Types is accepted safely.
const escaped = policy.createHTML('<img src=x onerror=alert(1)>');
el.innerHTML = escaped;  // '&lt;img src=x onerror=alert(1)&gt;'

How to use Trusted Types

Recommended usages #

Enforce Trusted Types for dangerous DOM sinks

CSP and Trusted Types header:
```
Content-Security-Policy: require-trusted-types-for 'script'
```
Currently 'script' is the only acceptable value for require-trusted-types-for directive.

Of course, you can combine Trusted Types with other CSP directives:

Merging a nonce-based CSP from above with Trusted Types:
```
Content-Security-Policy:
  script-src 'nonce-{RANDOM1}' 'strict-dynamic' https: 'unsafe-inline';
  object-src 'none';
  base-uri 'none';
  require-trusted-types-for 'script';
```
You may limit allowed Trusted Types policy names by setting an additional trusted-types directive (for example, trusted-types myPolicy). However, this is not a requirement.

Define a policy

Policy:

// Feature detection
if (window.trustedTypes && trustedTypes.createPolicy) {
  // Name and create a policy
  const policy = trustedTypes.createPolicy('escapePolicy', {
    createHTML: str => {
      return str.replace(/\</g, '&lt;').replace(/>/g, '&gt;');
    }
  });
}

Apply the policy

Use the policy when writing data to the DOM:

// Assignment of raw strings are blocked by Trusted Types.
el.innerHTML = 'some string'; // This throws an exception.

// Assignment of Trusted Types is accepted safely.
const escaped = policy.createHTML('<img src=x onerror=alert(1)>');
el.innerHTML = escaped;  // '&lt;img src=x onerror=alert(1)&gt;'

With require-trusted-types-for 'script', using a trusted type is a requirement. Using any dangerous DOM API with a string will result in an error.

Supported browsers #

Browser support

Chrome, Not supported
Firefox, Not supported
Edge, Not supported
Safari, Not supported

Learn more #

Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types
CSP: require-trusted-types-for - HTTP | MDN
CSP: trusted-types - HTTP | MDN
Trusted Types demo—open DevTools Inspector and see what is happening

X-Content-Type-Options #

When a malicious HTML document is served from your domain (for example, if an image uploaded to a photo service contains valid HTML markup), some browsers will treat it as an active document and allow it to execute scripts in the context of the application, leading to a cross-site scripting bug.

X-Content-Type-Options: nosniff prevents it by instructing the browser that the MIME type set in the Content-Type header for a given response is correct. This header is recommended for all of your resources.

Example usage

X-Content-Type-Options: nosniff

How to use X-Content-Type-Options

Recommended usages #

X-Content-Type-Options: nosniff is recommended for all resources served from your server along with the correct Content-Type header.

Example headers sent with a document HTML

X-Content-Type-Options: nosniff
Content-Type: text/html; charset=utf-8

Supported browsers #

Browser support

Chrome 64, Supported 64
Firefox 50, Supported 50
Edge 12, Supported 12
Safari 11, Supported 11

Source

Learn more #

X-Content-Type-Options - HTTP MDN

X-Frame-Options #

If a malicious website can embed your site as an iframe, this may allow attackers to invoke unintended actions by the user with clickjacking. Also, in some cases Spectre-type attacks give malicious websites a chance to learn about the contents of an embedded document.

X-Frame-Options indicates whether or not a browser should be allowed to render a page in a <frame>, <iframe>, <embed>, or <object>. All documents are recommended to send this header to indicate whether they allow being embedded by other documents.

Example usage

X-Frame-Options: DENY

How to use X-Frame-Options

Recommended usages #

All documents that are not designed to be embedded should use X-Frame-Options header.

You can try how the following configurations affect loading an iframe on this demo. Change the X-Frame-Options dropdown menu and click the Reload the iframe button.

Protects your website from being embedded by any other websites #

Deny being embedded by any other documents.

X-Frame-Options: DENY

Protects your website from being embedded by any cross-origin websites #

Allow being embedded only by same-origin documents.

X-Frame-Options: SAMEORIGIN

Supported browsers #

Browser support

Chrome 4, Supported 4
Firefox 4, Supported 4
Edge 12, Supported 12
Safari 4, Supported 4

Source

Learn more #

X-Frame-Options - HTTP

Cross-Origin Resource Policy (CORP) #

An attacker can embed resources from another origin, for example from your site, to learn information about them by exploiting web-based cross-site leaks.

Cross-Origin-Resource-Policy mitigates this risk by indicating the set of websites it can be loaded by. The header takes one of three values: same-origin, same-site, and cross-origin. All resources are recommended to send this header to indicate whether they allow being loaded by other websites.

Example usage

Cross-Origin-Resource-Policy: same-origin

How to use CORP

Recommended usages #

It is recommended that all resources are served with one of the following three headers.

You can try how the following configurations affect loading resources under a Cross-Origin-Embedder-Policy: require-corp environment on this demo. Change the Cross-Origin-Resource-Policy dropdown menu and click the Reload the iframe or Reload the image button to see the effect.

Allow resources to be loaded `cross-origin` #

It's recommended that CDN-like services apply cross-origin to resources (since they are usually loaded by cross-origin pages), unless they are already served through CORS which has a similar effect.

Cross-Origin-Resource-Policy: cross-origin

Limit resources to be loaded from the `same-origin` #

same-origin should be applied to resources that are intended to be loaded only by same-origin pages. You should apply this to resources that include sensitive information about the user, or responses of an API that is intended to be called only from the same origin.

Keep in mind that resources with this header can still be loaded directly, for example by navigating to the URL in a new browser window. Cross-Origin Resource Policy only protects the resource from being embedded by other websites.

Cross-Origin-Resource-Policy: same-origin

Limit resources to be loaded from the `same-site` #

same-site is recommended to be applied to resources that are similar to above but are intended to be loaded by other subdomains of your site.

Cross-Origin-Resource-Policy: same-site

Supported browsers #

Browser support

Chrome 73, Supported 73
Firefox 74, Supported 74
Edge 79, Supported 79
Safari 12, Supported 12

Source

Learn more #

Cross-Origin Opener Policy (COOP) #

An attacker's website can open another site in a popup window to learn information about it by exploiting web-based cross-site leaks. In some cases, this may also allow the exploitation of side-channel attacks based on Spectre.

The Cross-Origin-Opener-Policy header provides a way for a document to isolate itself from cross-origin windows opened through window.open() or a link with target="_blank" without rel="noopener". As a result, any cross-origin opener of the document will have no reference to it and will not be able to interact with it.

Example usage

Cross-Origin-Opener-Policy: same-origin-allow-popups

How to use COOP

Recommended usages #

You can try how the following configurations affect communication with a cross-origin popup window on this demo. Change the Cross-Origin-Opener-Policy dropdown menu for both the document and the popup window, click the Open a popup button then click Send a postMessage to see if the message is actually delivered.

Isolate a document from cross-origin windows #

Setting same-origin puts the document to be isolated from cross-origin document windows.

Cross-Origin-Opener-Policy: same-origin

Isolate a document from cross-origin windows but allow popups #

Setting same-origin-allow-popups allows a document to retain a reference to its popup windows unless they set COOP with same-origin or same-origin-allow-popups. This means same-origin-allow-popups can still protect the document from being referenced when opened as a popup window, but allow it to communicate with its own popups.

Cross-Origin-Opener-Policy: same-origin-allow-popups

Allow a document to be referenced by cross-origin windows #

unsafe-none is the default value but you can explicitly indicate that this document can be opened by a cross-origin window and retain mutual access.

Cross-Origin-Opener-Policy: unsafe-none

Report patterns incompatible with COOP #

You can receive reports when COOP prevents cross-window interactions with the Reporting API.

Cross-Origin-Opener-Policy: same-origin; report-to="coop"

COOP also supports a report-only mode so you can receive reports without actually blocking communication between cross-origin documents.

Cross-Origin-Opener-Policy-Report-Only: same-origin; report-to="coop"

Supported browsers #

Browser support

Chrome 83, Supported 83
Firefox 79, Supported 79
Edge 83, Supported 83
Safari 15.2, Supported 15.2

Source

Learn more #

Why you need "cross-origin isolated" for powerful features

Cross-Origin Resource Sharing (CORS) #

Unlike other items in this article, Cross-Origin Resource Sharing (CORS) is not a header, but a browser mechanism that requests and permits access to cross-origin resources.

By default, browsers enforce the same-origin policy to prevent a web page from accessing cross-origin resources. For example, when a cross-origin image is loaded, even though it's displayed on the web page visually, the JavaScript on the page doesn't have access to the image's data. The resource provider can relax restrictions and allow other websites to read the resource by opting-in with CORS.

Example usage

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Credentials: true

How to use CORS

Before looking into how to configure CORS, it's helpful to understand the distinction between request types. Depending on request details, a request will be classified as a simple request or a preflighted request.

Criteria for a simple request:

The method is GET, HEAD, or POST.
The custom headers only include Accept, Accept-Language, Content-Language, and Content-Type.
The Content-Type is application/x-www-form-urlencoded, multipart/form-data, or text/plain.

Everything else is classified as a preflighted request. For more details, check out Cross-Origin Resource Sharing (CORS) - HTTP | MDN.

Recommended usages #

Simple request #

When a request meets the simple request criteria, the browser sends a cross-origin request with an Origin header that indicates the requesting origin.

Example request header

Get / HTTP/1.1
Origin: https://example.com

Example response header

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Credentials: true

Access-Control-Allow-Origin: https://example.com indicates that the https://example.com can access the contents of the response. Resources meant to be readable by any site can set this header to *, in which case the browser will only require the request to be made without credentials.
Access-Control-Allow-Credentials: true indicates that requests which carry credentials (cookies) are allowed to load the resource. Otherwise, authenticated requests will be rejected even if the requesting origin is present in the Access-Control-Allow-Origin header.

You can try how the simple request affect loading resources under a Cross-Origin-Embedder-Policy: require-corp environment on this demo. Click the Cross-Origin Resource Sharing checkbox and click the Reload the image button to see the effect.

Preflighted requests #

A preflighted request is preceded with an OPTIONS request to check if the subsequent request is allowed to be sent.

Example request header

OPTIONS / HTTP/1.1
Origin: https://example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: X-PINGOTHER, Content-Type

Access-Control-Request-Method: POST allows the following request to be made with the POST method.
Access-Control-Request-Headers: X-PINGOTHER, Content-Type allows the requester to set the X-PINGOTHER and Content-Type HTTP headers in the subsequent request.

Example response headers

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: X-PINGOTHER, Content-Type
Access-Control-Max-Age: 86400

Access-Control-Allow-Methods: POST, GET, OPTIONS indicates that subsequent requests can be made with the POST, GET and OPTIONS methods.
Access-Control-Allow-Headers: X-PINGOTHER, Content-Type indicates subsequent requests can include the X-PINGOTHER and Content-Type headers.
Access-Control-Max-Age: 86400 indicates that the result of the preflighted request can be cached for 86400 seconds.

Supported browsers #

Browser support

Chrome 4, Supported 4
Firefox 3.5, Supported 3.5
Edge 12, Supported 12
Safari 4, Supported 4

Source

Learn more #

Cross-Origin Embedder Policy (COEP) #

To reduce the ability of Spectre-based attacks to steal cross-origin resources, features such as SharedArrayBuffer or performance.measureUserAgentSpecificMemory() are disabled by default.

Cross-Origin-Embedder-Policy: require-corp prevents documents and workers from loading cross-origin resources such as images, scripts, stylesheets, iframes and others unless these resources explicitly opt into being loaded via CORS or CORP headers. COEP can be combined withCross-Origin-Opener-Policy to opt a document into cross-origin isolation.

Use Cross-Origin-Embedder-Policy: require-corp when you want to enable cross-origin isolation for your document.

Example usage

Cross-Origin-Embedder-Policy: require-corp

How to use COEP

Example usages #

COEP takes a single value of require-corp. By sending this header, you can instruct the browser to block loading resources that do not opt-in via CORS or CORP.

You can try how the following configurations affect loading resources on this demo. Change the Cross-Origin-Embedder-Policy dropdown menu, the Cross-Origin-Resource-Policy dropdown menu, the Report Only checkbox etc to see how they affect loading resources. Also, open the reporting endpoint demo to see if the blocked resources are reported.

Enable cross-origin isolation #

Enable cross-origin isolation by sending Cross-Origin-Embedder-Policy: require-corp along with Cross-Origin-Opener-Policy: same-origin.

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

Report resources incompatible withn COEP #

You can receive reports of blocked resources caused by COEP with the Reporting API.

Cross-Origin-Embedder-Policy: require-corp; report-to="coep"

COEP also supports report-only mode so you can receive reports without actually blocking loading resources.

Cross-Origin-Embedder-Policy-Report-Only: require-corp; report-to="coep"

Supported browsers #

Browser support

Chrome 83, Supported 83
Firefox 79, Supported 79
Edge 83, Supported 83
Safari 15.2, Supported 15.2

Source

Learn more #

HTTP Strict Transport Security (HSTS) #

Communication over a plain HTTP connection is not encrypted, making the transferred data accessible to network-level eavesdroppers.

Strict-Transport-Security header informs the browser that it should never load the site using HTTP and use HTTPS instead. Once it's set, the browser will use HTTPS instead of HTTP to access the domain without a redirect for a duration defined in the header.

Example usage

Strict-Transport-Security: max-age=31536000

How to use HSTS

Recommended usages #

All websites that transition from HTTP to HTTPS should respond with a Strict-Transport-Security header when a request with HTTP is received.

Strict-Transport-Security: max-age=31536000

Supported browsers #

Browser support

Chrome 4, Supported 4
Firefox 4, Supported 4
Edge 12, Supported 12
Safari 7, Supported 7

Source

Learn more #

Strict-Transport-Security - HTTP

How to use HTTPS for local development

2021-01-25T00:00:00Z

In this post, statements about localhost are valid for 127.0.0.1 and [::1] as well, since they both describe the local computer address, also called "loopback address". Also, to keep things simple, the port number isn't specified. So when you see http://localhost, read it as http://localhost:{PORT} or http://127.0.0.1:{PORT}.

If your production website uses HTTPS, you want your local development site to behave like an HTTPS site (if your production website doesn't use HTTPS, make it a priority to switch to HTTPS). Most of the time, you can trust http://localhost to behave like an HTTPS site. But in some cases, you need to run your site locally with HTTPS. Let's take a look at how to do this.

⏩ Are you looking for quick instructions, or have you been here before? Skip to the Cheatsheet.

Running your site locally with HTTPS using mkcert (recommended) #

To use HTTPS with your local development site and access https://localhost or https://mysite.example (custom hostname), you need a TLS certificate. But browsers won't consider just any certificate valid: your certificate needs to be signed by an entity that is trusted by your browser, called a trusted certificate authority (CA).

What you need to do is to create a certificate and sign it with a CA that is trusted locally by your device and browser. mkcert is a tool that helps you do this in a few commands. Here's how it works:

If you open your locally running site in your browser using HTTPS, your browser will check the certificate of your local development server.
Upon seeing that the certificate has been signed by the mkcert-generated certificate authority, the browser checks whether it's registered as a trusted certificate authority.
mkcert is listed as a trusted authority, so your browser trusts the certificate and creates an HTTPS connection.

A diagram of how mkcert works.

mkcert (and similar tools) provide several benefits:

mkcert is specialized in creating certificates that are compliant with what browsers consider valid certificates. It stays updated to match requirements and best practices. This is why you won't have to run mkcert commands with complex configurations or arguments to generate the right certificates!
mkcert is a cross-platform tool. Anyone on your team can use it.

mkcert is the tool we recommend for creating a TLS certificate for local development. You can check out other options too.

Many operating systems may include libraries to produce certificates, such as openssl. Unlike mkcert and similar tools, such libraries may not consistently produce correct certificates, may require complex commands to be run, and are not necessarily cross-platform.

Caution #

Setup #

Install mkcert (only once).

Follow the instructions for installing mkcert on your operating system. For example, on macOS:
```
brew install mkcert
brew install nss # if you use Firefox
```
Add mkcert to your local root CAs.

In your terminal, run the following command:
```
mkcert -install
```
This generates a local certificate authority (CA). Your mkcert-generated local CA is only trusted locally, on your device.
Generate a certificate for your site, signed by mkcert.

In your terminal, navigate to your site's root directory or whichever directory you'd like the certificates to be located at.

Then, run:
```
mkcert localhost
```
If you're using a custom hostname like mysite.example, run:
```
mkcert mysite.example
```
The command above does two things:
- Generates a certificate for the hostname you've specified
- Lets mkcert (that you've added as a local CA in Step 2) sign this certificate.
Now, your certificate is ready and signed by a certificate authority your browser trusts locally. You're almost done, but your server doesn't know about your certificate yet!
Configure your server.

You now need to tell your server to use HTTPS (since development servers tend to use HTTP by default) and to use the TLS certificate you've just created.

How to do this exactly depends on your server. A few examples:

👩🏻‍💻 With node:

server.js (replace {PATH/TO/CERTIFICATE...} and {PORT}):
```
const https = require('https');
const fs = require('fs');
const options = {
  key: fs.readFileSync('{PATH/TO/CERTIFICATE-KEY-FILENAME}.pem'),
  cert: fs.readFileSync('{PATH/TO/CERTIFICATE-FILENAME}.pem'),
};
https
  .createServer(options, function (req, res) {
    // server code
  })
  .listen({PORT});
```
👩🏻‍💻 With http-server:

Start your server as follows (replace {PATH/TO/CERTIFICATE...}):
```
http-server -S -C {PATH/TO/CERTIFICATE-FILENAME}.pem -K {PATH/TO/CERTIFICATE-KEY-FILENAME}.pem
```
-S runs your server with HTTPS, while -C sets the certificate and -K sets the key.

👩🏻‍💻 With a React development server:

Edit your package.json as follows, and replace {PATH/TO/CERTIFICATE...}:
```
"scripts": {
"start": "HTTPS=true SSL_CRT_FILE={PATH/TO/CERTIFICATE-FILENAME}.pem SSL_KEY_FILE={PATH/TO/CERTIFICATE-KEY-FILENAME}.pem react-scripts start"
```
For example, if you've created a certificate for localhost that is located in your site's root directory as follows:
```
|-- my-react-app
    |-- package.json
    |-- localhost.pem
    |-- localhost-key.pem
    |--...
```
Then your start script should look like this:
```
"scripts": {
    "start": "HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem react-scripts start"
```
👩🏻‍💻 Other examples:
- Angular development server
- Python
✨ You're done! Open https://localhost or https://mysite.example in your browser: you're running your site locally with HTTPS. You won't see any browser warnings, because your browser trusts mkcert as a local certificate authority.

Using mkcert: cheatsheet #

mkcert in short

To run your local development site with HTTPS:

Set up mkcert.

If you haven't yet, install mkcert, for example on macOS:
```
brew install mkcert
```
Check install mkcert for Windows and Linux instructions.

Then, create a local certificate authority:
```
mkcert -install
```
Create a trusted certificate.
```
mkcert {YOUR HOSTNAME e.g. localhost or mysite.example}
```
This create a valid certificate (that will be signed by mkcert automatically).
Configure your development server to use HTTPS and the certificate you've created in Step 2.
✨ You're done! You can now access https://{YOUR HOSTNAME} in your browser, without warnings

Running your site locally with HTTPS: other options #

Self-signed certificate #

You may also decide to not use a local certificate authority like mkcert, and instead sign your certificate yourself.

Beware of a few pitfalls with this approach:

Browsers don't trust you as a certificate authority and they'll show warnings you'll need to bypass manually. In Chrome, you may use the flag #allow-insecure-localhost to bypass this warning automatically on localhost. It feels a bit hacky, because it is.
This is unsafe if you're working in an insecure network.
Self-signed certificates won't behave in exactly the same way as trusted certificates.
It's not necessarily easier or faster than using a local CA like mkcert.
If you're not using this technique in a browser context, you may need to disable certificate verification for your server. Omitting to re-enable it in production would be dangerous.

The warnings browsers show when a self-signed certificate is used.

Why don't browsers trust self-signed certificates?

If you open your locally running site in your browser using HTTPS, your browser will check the certificate of your local development server. When it sees that the certificate has been signed by yourself, it checks whether you're registered as a trusted certificate authority. Because you're not, your browser can't trust the certificate; it displays a warning telling you that your connection is not secure. You may proceed at your own risk—if you do, an HTTPS connection will be created.

Why browsers don't trust self-signed certificates.

Certificate signed by a regular certificate authority #

You may also find techniques based on having an actual certificate authority—not a local one—sign your certificate.

A few things to keep in mind if you're considering using these techniques:

You'll have more setup work to do than when using a local CA technique like mkcert.
You need to use a domain name that you control and that is valid. This means that you can't use actual certificate authorities for:
- localhost and other domain names that are reserved, such as example or test.
- Any domain name that you don't control.
- Top-level domains that are not valid. See the list of valid top-level domains.

Reverse proxy #

Another option to access a locally running site with HTTPS is to use a reverse proxy such as ngrok.

A few points to consider:

Anyone can access your local development site once you share with them a URL created with a reverse proxy. This can be very handy when demoing your project to clients! Or this can be a downside, if your project is sensitive.
You may need to consider pricing.
New security measures in browsers may affect the way these tools work.

Flag (not recommended) #

If you're using a custom hostname like mysite.example, you can use a flag in Chrome to forcefully consider mysite.example secure. Avoid doing this, because:

You would need to be 100% sure that mysite.example always resolves to a local address, otherwise you could leak production credentials.
You won't be able to debug across browsers with this trick 🙀.

With many thanks for contributions and feedback to all reviewers and contributors—especially Ryan Sleevi, Filippo Valsorda, Milica Mihajlija and Rowan Merewood. 🙌

Hero image background by @anandu on Unsplash, edited.

When to use HTTPS for local development

2021-01-25T00:00:00Z

Also see: How to use HTTPS for local development.

Summary #

When developing locally, use http://localhost by default. Service Workers, Web Authentication API, and more will work. However, in the following cases, you'll need HTTPS for local development:

Setting Secure cookies in a consistent way across browsers
Debugging mixed-content issues
Using HTTP/2 and later
Using third-party libraries or APIs that require HTTPS
Using a custom hostname

When to use HTTPS for local development.

✨ This is all you need to know. If you're interested in more details keep reading!

Why your development site should behave securely #

To avoid running into unexpected issues, you want your local development site to behave as much as possible like your production website. So, if your production website uses HTTPS, you want your local development site to behave like an HTTPS site.

Use `http://localhost` by default #

Browsers treat http://localhost in a special way: although it's HTTP, it mostly behaves like an HTTPS site.

On http://localhost, Service Workers, Sensor APIs, Authentication APIs, Payments, and other features that require certain security guarantees are supported and behave exactly like on an HTTPS site.

When to use HTTPS for local development #

You may encounter special cases where http://localhost doesn't behave like an HTTPS site—or you may simply want to use a custom site name that's not http://localhost.

You need to use HTTPS for local development in the following cases:

You need to set a cookie locally that is Secure, or SameSite:none, or has the __Host prefix. Secure cookies are set only on HTTPS, but not on http://localhost for all browsers. And because SameSite:none and __Host also require the cookie to be Secure, setting such cookies on your local development site requires HTTPS as well.

Gotchas
When it comes to setting Secure cookies locally, not all browsers behave in the same way! For example, Chrome and Safari don't set Secure cookies on localhost, but Firefox does. In Chrome, this is considered a bug.
You need to debug locally an issue that only occurs on an HTTPS website but not on an HTTP site, not even http://localhost, such as a mixed-content issue.
You need to locally test or reproduce a behaviour specific to HTTP/2 or newer. For example, if you need to test loading performance on HTTP/2 or newer. Insecure HTTP/2 or newer is not supported, not even on localhost.
You need to locally test third-party libraries or APIs that require HTTPS (for example OAuth).
You're not using localhost, but a custom host name for local development, for example mysite.example. Typically, this means you've overridden your local hosts file:

Editing a hosts file to add a custom hostname.

In this case, Chrome, Edge, Safari, and Firefox by default do not consider mysite.example to be secure, even though it's a local site. So it won't behave like an HTTPS site.
Other cases! This is not an exhaustive list, but if you encounter a case that's not listed here, you'll know: things will break on http://localhost, or it won't quite behave like your production site. 🙃

In all of these cases, you need to use HTTPS for local development.

How to use HTTPS for local development #

If you need to use HTTPS for local development, head over to How to use HTTPS for local development.

Tips if you're using a custom hostname #

If you're using a custom hostname, for example, editing your hosts file:

Don't use a bare hostname like mysite because if there's a top-level domain (TLD) that happens to have the same name (mysite), you'll run into issues. And it's not that unlikely: in 2020, there are over 1,500 TLDs, and the list is growing. coffee, museum, travel, and many large company names (maybe even the company you're working at!) are TLDs. See the full list here.
Only use domains that are yours, or that are reserved for this purpose. If you don't have a domain of your own, you can use either test or localhost (mysite.localhost). test doesn't have special treatment in browsers, but localhost does: Chrome and Edge support http://<name>.localhost out of the box, and it will behave securely when localhost does. Try it out: run any site on localhost and access http://<whatever name you like>.localhost:<your port> in Chrome or Edge. This may soon be possible in Firefox and Safari as well. The reason you can do this (have subdomains like mysite.localhost) is because localhost is not just a hostname: it's also a full TLD, like com.

Learn more #

With many thanks for contributions and feedback to all reviewers—especially Ryan Sleevi, Filippo Valsorda, Milica Mihajlija, Rowan Merewood and Jake Archibald. 🙌

Hero image by @moses_lee on Unsplash, edited.

Referer and Referrer-Policy best practices

2020-07-30T00:00:00Z

Summary #

Unexpected cross-origin information leakage hinders web users' privacy. A protective referrer policy can help.
Consider setting a referrer policy of strict-origin-when-cross-origin. It retains much of the referrer's usefulness, while mitigating the risk of leaking data cross-origins.
Don't use referrers for Cross-Site Request Forgery (CSRF) protection. Use CSRF tokens instead, and other headers as an extra layer of security.

Referer and Referrer-Policy 101 #

HTTP requests may include the optional Referer header, which indicates the origin or web page URL the request was made from. The Referrer-Policy header defines what data is made available in the Referer header.

In the example below, the Referer header includes the complete URL of the page on site-one from which the request was made.

The Referer header might be present in different types of requests:

Navigation requests, when a user clicks a link
Subresource requests, when a browser requests images, iframes, scripts, and other resources that a page needs.

For navigations and iframes, this data can also be accessed via JavaScript using document.referrer.

The Referer value can be insightful. For example, an analytics service might use the value to determine that 50% of the visitors on site-two.example came from social-network.example.

But when the full URL including the path and query string is sent in the Referer across origins, this can be privacy-hindering and pose security risks as well. Take a look at these URLs:

URLs #1 to #5 contain private information—sometimes even identifying or sensitive. Leaking these silently across origins can compromise web users' privacy.

URL #6 is a capability URL. You don't want it to fall in the hands of anyone other than the intended user. If this were to happen, a malicious actor could hijack this user's account.

In order to restrict what referrer data is made available for requests from your site, you can set a referrer policy.

What policies are available and how do they differ? #

You can select one of eight policies. Depending on the policy, the data available from the Referer header (and document.referrer) can be:

No data (no Referer header is present)
Only the origin
The full URL: origin, path, and query string

Some policies are designed to behave differently depending on the context: cross-origin or same-origin request, security (whether the request destination is as secure as the origin), or both. This is useful to limit the amount of information shared across origins or to less secure origins—while maintaining the richness of the referrer within your own site.

Here is an overview showing how referrer policies restrict the URL data available from the Referer header and document.referrer:

MDN provides a full list of policies and behavior examples.

Things to note:

All policies that take the scheme (HTTPS vs. HTTP) into account (strict-origin, no-referrer-when-downgrade and strict-origin-when-cross-origin) treat requests from an HTTP origin to another HTTP origin the same way as requests from an HTTPS origin to another HTTPS origin—even if HTTP is less secure. That's because for these policies, what matters is whether a security downgrade takes place, i.e. if the request can expose data from an encrypted origin to an unencrypted one. An HTTP → HTTP request is unencrypted all along, so there is no downgrade. HTTPS → HTTP requests, on the contrary, present a downgrade.
If a request is same-origin, this means that the scheme (HTTPS or HTTP) is the same; hence there is no security downgrade.

Default referrer policies in browsers #

As of October 2021

If no referrer policy is set, the browser's default policy will be used.

Browser	Default `Referrer-Policy` / Behavior
Chrome	The default is `strict-origin-when-cross-origin`.
Firefox	The default is `strict-origin-when-cross-origin`. Starting from version 93, for Strict Tracking Protection and Private Browsing users: the less restrictive referrer policies `no-referrer-when-downgrade`, `origin-when-cross-origin`, and `unsafe-url` are ignored for cross-site requests, meaning that the referrer is always trimmed for cross-site requests, regardless of the website's policy.
Edge	The default is `strict-origin-when-cross-origin`.
Safari	The default is similar to `strict-origin-when-cross-origin`, with some specificities. See Preventing Tracking Prevention Tracking for details.

Setting your referrer policy: best practices #

There are different ways to set referrer policies for your site:

As an HTTP header
Within your HTML
From JavaScript on a per-request basis

You can set different policies for different pages, requests or elements.

The HTTP header and the meta element are both page-level. The precedence order when determining an element's effective policy is:

Element-level policy
Page-level policy
Browser default

Example:

index.html:

<meta name="referrer" content="strict-origin-when-cross-origin" />
<img src="..." referrerpolicy="no-referrer-when-downgrade" />

The image will be requested with a no-referrer-when-downgrade policy, while all other subresource requests from this page will follow the strict-origin-when-cross-origin policy.

How to see the referrer policy? #

securityheaders.com is handy to determine the policy a specific site or page is using.

You can also use the developer tools of Chrome, Edge, or Firefox to see the referrer policy used for a specific request. At the time of this writing, Safari doesn't show the Referrer-Policy header but does show the Referer that was sent.

Chrome DevTools, Network panel with a request selected.

Which policy should you set for your website? #

Summary: Explicitly set a privacy-enhancing policy such as strict-origin-when-cross-origin (or stricter).

Why "explicitly"? #

If no referrer policy is set, the browser's default policy will be used—in fact, websites often defer to the browser's default. But this is not ideal, because:

Browser default policies are either no-referrer-when-downgrade, strict-origin-when-cross-origin, or stricter—depending on the browser and mode (private/incognito). So your website won't behave predictably across browsers.
Browsers are adopting stricter defaults such as strict-origin-when-cross-origin and mechanisms such as referrer trimming for cross-origin requests. Explicitly opting into a privacy-enhancing policy before browser defaults change gives you control and helps you run tests as you see fit.

Why `strict-origin-when-cross-origin` (or stricter)? #

You need a policy that is secure, privacy-enhancing, and useful—what "useful" means depends on what you want from the referrer:

Secure: if your website uses HTTPS (if not, make it a priority), you don't want your website's URLs to leak in non-HTTPS requests. Since anyone on the network can see these, this would expose your users to person-in-the-middle-attacks. The policies no-referrer-when-downgrade, strict-origin-when-cross-origin, no-referrer and strict-origin solve this problem.
Privacy-enhancing: for a cross-origin request, no-referrer-when-downgrade shares the full URL—this is not privacy-enhancing. strict-origin-when-cross-origin and strict-origin only share the origin, and no-referrer shares nothing at all. This leaves you with strict-origin-when-cross-origin, strict-origin, and no-referrer as privacy-enhancing options.
Useful: no-referrer and strict-origin never share the full URL, even for same-origin requests—so if you need this, strict-origin-when-cross-origin is a better option.

All of this means that strict-origin-when-cross-origin is generally a sensible choice.

Example: Setting a strict-origin-when-cross-origin policy:

index.html:

<meta name="referrer" content="strict-origin-when-cross-origin" />

Or server-side, for example in Express:

const helmet = require('helmet');
app.use(helmet.referrerPolicy({policy: 'strict-origin-when-cross-origin'}));

What if `strict-origin-when-cross-origin` (or stricter) doesn't accommodate all your use cases? #

In this case, take a progressive approach: set a protective policy like strict-origin-when-cross-origin for your website and if need be, a more permissive policy for specific requests or HTML elements.

Example: element-level policy #

index.html:

<head>
  <!-- document-level policy: strict-origin-when-cross-origin -->
  <meta name="referrer" content="strict-origin-when-cross-origin" />
  <head>
    <body>
      <!-- policy on this <a> element: no-referrer-when-downgrade -->
      <a src="…" href="…" referrerpolicy="no-referrer-when-downgrade"></a>
      <body></body>
    </body>
  </head>
</head>

Note that Safari/WebKit may cap document.referrer or the Referer header for cross-site requests. See details.

Example: request-level policy #

script.js:

fetch(url, {referrerPolicy: 'no-referrer-when-downgrade'});

What else should you consider? #

Your policy should depend on your website and use cases—this is up to you, your team, and your company. If some URLs contain identifying or sensitive data, set a protective policy.

Using the referrer from incoming requests: best practices #

What to do if your site's functionality uses the referrer URL of incoming requests? #

Protect users' data #

The Referer may contain private, personal, or identifying data—so make sure you treat it as such.

Keep in mind that the `Referer` you receive may change #

Using the referrer from incoming cross-origin requests has a few limitations:

If you have no control over the request emitter's implementation, you can't make assumptions about the Referer header (and document.referrer) you receive. The request emitter may decide anytime to switch to a no-referrer policy, or more generally to a stricter policy than what they used before—meaning you'll get less data via the Referer than you used to.
Browsers are increasingly using the Referrer-Policy strict-origin-when-cross-origin by default. This means that you may now receive only the origin (instead of full referrer URL) in incoming cross-origin requests, if the site that sends these has no policy set.
Browsers may change the way they manage Referer; for example, in the future, they may decide to always trim referrers to origins in cross-origin subresource requests, in order to protect user privacy.
The Referer header (and document.referrer) may contain more data than you need, for example a full URL when you only want to know if the request is cross-origin.

Alternatives to `Referer` #

You may need to consider alternatives if:

An essential functionality of your site uses the referrer URL of incoming cross-origin requests;
And/or if your site is not receiving anymore the part of the referrer URL it needs in a cross-origin request. This happens when the request emitter changed their policy or when they have no policy set and the browser default's policy changed (like in Chrome 85).

To define alternatives, analyze first what part of the referrer you're using.

If you only need the origin (https://site-one.example):

If you're using the referrer in a script that has top-level access to the page, window.location.origin is an alternative.
If available, headers like Origin and Sec-Fetch-Site give you the Origin or describe whether the request is cross-origin, which may be exactly what you need.

If you need other elements of the URL (path, query parameters…):

Request parameters may address your use case and this saves you the work of parsing the referrer.
If you're using the referrer in a script that has top-level access to the page, window.location.pathname may be an alternative. Extract only the path section of the URL and pass it on as an argument, so any potentially sensitive information in the URL parameters isn't passed on.

If you can't use these alternatives:

Check if your systems can be changed to expect the request emitter (site-one.example) to explicitly set the information you need in a configuration of some sort. Pro: more explicit, more privacy-preserving for site-one.example users, more future-proof. Con: potentially more work from your side or for your system's users.
Check whether the site that emits the requests may agree to set a per-element or per-request Referrer-Policy of no-referrer-when-downgrade. Con: potentially less privacy-preserving for site-one.example users, potentially not supported in all browsers.

Cross-Site Request Forgery (CSRF) protection #

Note that a request emitter can always decide not to send the referrer by setting a no-referrer policy (and a malicious actor could even spoof the referrer).

Use CSRF tokens as your primary protection. For extra protection, use SameSite—and instead of Referer, use headers such as Origin (available on POST and CORS requests) and Sec-Fetch-Site (if available).

Logging #

Make sure to protect users' personal or sensitive data that may be in the Referer.

If you're only using the origin, check if the Origin header could be an alternative. This may give you the information that you need for debugging purposes in a simpler way and without needing to parse the referrer.

Payments #

Payment providers may rely on the Referer header of incoming requests for security checks.

For example:

The user clicks a Buy button on online-shop.example/cart/checkout.
online-shop.example redirects to payment-provider.example to manage the transaction.
payment-provider.example checks the Referer of this request against a list of allowed Referer values set up by the merchants. If it doesn't match any entry in the list, payment-provider.example rejects the request. If it does match, the user can proceed to the transaction.

Best practices for payment flow security checks #

Summary: as a payment provider, you can use the Referer as a basic check against naive attacks—but you should absolutely have another, more reliable verification method in place.

The Referer header alone isn't a reliable basis for a check: the requesting site, whether they're a legitimate merchant or not, can set a no-referrer policy which will make the Referer information unavailable to the payment provider. However, as a payment provider, looking at the Referer may help you catch naive attackers who did not set a no-referrer policy. So you can decide to use the Referer as a first basic check. If you do so:

Do not expect the Referer to always be present; and if it's present, only check against the piece of data it will include at the minimum: the origin. When setting the list of allowed Referer values, make sure that no path is included, but only the origin. Example: the allowed Referer values for online-shop.example should be online-shop.example, not online-shop.example/cart/checkout. Why? Because by expecting either no Referer at all or a Referer value that is the origin of the requesting website, you prevent unexpected errors since you're not making assumptions about the Referrer-Policy your merchant has set or about the browser's behavior if the merchant has no policy set. Both the site and the browser could strip the Referer sent in the incoming request to only the origin or not send the Referer at all.
If the Referer is absent or if it's present and your basic Referer origin check was successful: you can move onto your other, more reliable verification method (see below).

What is a more reliable verification method?

One reliable verification method is to let the requester hash the request parameters together with a unique key. As a payment provider, you can then calculate the same hash on your side and only accept the request if it matches your calculation.

What happens to the Referer when an HTTP merchant site with no referrer policy redirects to an HTTPS payment provider?

No Referer will be visible in the request to the HTTPS payment provider, because most browsers use strict-origin-when-cross-origin or no-referrer-when-downgrade by default when a website has no policy set. Also note that Chrome's change to a new default policy won't change this behaviour.

Conclusion #

A protective referrer policy is a great way to give your users more privacy.

To learn more about different techniques to protect your users, check out web.dev's Safe and secure collection!

With many thanks for contributions and feedback to all reviewers - especially Kaustubha Govind, David Van Cleve, Mike West, Sam Dutton, Rowan Merewood, Jxck and Kayce Basques.

Maud Nalpas on web.dev

Network Error Logging (NEL)

Introduction #

Overview of the legacy Reporting API #

The legacy Report-To Header #

Explanation of header fields #

How does the browser send reports? #

When does the browser send reports? #

Configuring multiple endpoints #

Failover and load balancing #

Setting up Network Error Logging #

Setup #

Subresources #

Debugging report configurations #

What about ReportingObserver? #

Example server #

Further reading #

Security headers quick reference

Protect your site from injection vulnerabilities #

Isolate your site from other websites #

Build a powerful website securely #

Encrypt traffic to your site #

Content Security Policy (CSP) #

Recommended usages #

1. Use a nonce-based strict CSP #

2. Use a hash-based strict CSP #

Supported browsers #

Other things to note about CSP #

Learn more #

Trusted Types #

Recommended usages #

Supported browsers #

Learn more #

X-Content-Type-Options #

Recommended usages #

Supported browsers #

Learn more #

X-Frame-Options #

Recommended usages #

Protects your website from being embedded by any other websites #

Protects your website from being embedded by any cross-origin websites #

Supported browsers #

Learn more #

Cross-Origin Resource Policy (CORP) #

Recommended usages #

Allow resources to be loaded cross-origin #

Limit resources to be loaded from the same-origin #

Limit resources to be loaded from the same-site #

Supported browsers #

Learn more #

Cross-Origin Opener Policy (COOP) #

Recommended usages #

Isolate a document from cross-origin windows #

Isolate a document from cross-origin windows but allow popups #

Allow a document to be referenced by cross-origin windows #

Report patterns incompatible with COOP #

Supported browsers #

Learn more #

Cross-Origin Resource Sharing (CORS) #

Recommended usages #

Simple request #

Preflighted requests #

Supported browsers #

Learn more #

Cross-Origin Embedder Policy (COEP) #

Example usages #

Enable cross-origin isolation #

Report resources incompatible withn COEP #

Supported browsers #

Learn more #

HTTP Strict Transport Security (HSTS) #

Recommended usages #

Supported browsers #

Learn more #

Further reading #

How to use HTTPS for local development

Running your site locally with HTTPS using mkcert (recommended) #

Caution #

Setup #

Using mkcert: cheatsheet #

The legacy `Report-To` Header #

Allow resources to be loaded `cross-origin` #

Limit resources to be loaded from the `same-origin` #

Limit resources to be loaded from the `same-site` #

Use `http://localhost` by default #

Why `strict-origin-when-cross-origin` (or stricter)? #

What if `strict-origin-when-cross-origin` (or stricter) doesn't accommodate all your use cases? #

Keep in mind that the `Referer` you receive may change #

Alternatives to `Referer` #