A guide to enable cross-origin isolation

A guide to enable cross-origin isolation

Cross-origin isolation enables a web page to use powerful features such as SharedArrayBuffer. This article explains how to enable cross-origin isolation on your website.

Updated

This guide shows you how to enable cross-origin isolation. Cross-origin isolation is required if you want to use SharedArrayBuffer, performance.measureUserAgentSpecificMemory(), high resolution timer with better precision, or the JS Self-Profiling API.

If you intend to enable cross-origin isolation, evaluate the impact this will have on other cross-origin resources on your website, such as ad placements.

Determine where in your website SharedArrayBuffer is used

Starting in Chrome 92, functionalities that use SharedArrayBuffer will no longer work without cross-origin isolation. If you landed on this page due to a SharedArrayBuffer deprecation message, it's likely either your website or one of the resources embedded on it is using SharedArrayBuffer. To ensure nothing breaks on your website due to deprecation, start by identifying where it's used.

Objective:

  • Turn on cross-origin isolation to keep using SharedArrayBuffer.
  • If you rely on third-party code that uses SharedArrayBuffer, notify the third-party provider to take action.

If you are not sure where in your site a SharedArrayBuffer is used, there are two ways find out:

  • Using Chrome DevTools
  • (Advanced) Using Deprecation Reporting

If you already know where you are using SharedArrayBuffer, skip to Analyze the impact of cross-origin isolation.

Using Chrome DevTools #

Chrome DevTools allows developers to inspect websites.

  1. Open the Chrome DevTools on the page you suspect might be using SharedArrayBuffer.
  2. Select the Console panel.
  3. If the page is using SharedArrayBuffer, the following message will show up:
    [Deprecation] SharedArrayBuffer will require cross-origin isolation as of M92, around May 2021. See https://developer.chrome.com/blog/enabling-shared-array-buffer/ for more details. common-bundle.js:535
  4. The filename and the line number at the end of the message (for example, common-bundle.js:535) indicate where the SharedArrayBuffer is coming from. If it's a third-party library, contact the developer to fix the issue. If it's implemented as part of your website, follow the guide below to enable cross-origin isolation.
DevToools Console warning when SharedArrayBuffer is used without cross-origin isolation
DevToools Console warning when SharedArrayBuffer is used without cross-origin isolation.

(Advanced) Using Deprecation Reporting #

Some browsers have a reporting functionality of deprecating APIs to a specified endpoint.

  1. Set up a deprecation report server and get the reporting URL. You can achieve this by either using a public service or building one yourself.
  2. Using the URL, set the following HTTP header to pages that are potentially serving SharedArrayBuffer.
    Report-To: {"group":"default","max_age":86400,"endpoints":[{"url":"THE_DEPRECATION_ENDPOINT_URL"}]}
  3. Once the header starts to propagate, the endpoint you registered to should start collecting deprecation reports.

See an example implementation here: https://first-party-test.glitch.me.

Analyze the impact of cross-origin isolation #

Wouldn't it be great if you could assess the impact that enabling cross-origin isolation would have on your site without actually breaking anything? The Cross-Origin-Opener-Policy-Report-Only and Cross-Origin-Embedder-Policy-Report-Only HTTP headers allow you to do just that.

  1. Set Cross-Origin-Opener-Policy-Report-Only: same-origin on your top-level document. As the name indicates, this header only sends reports about the impact that COOP: same-origin would have on your site—it won't actually disable communication with popup windows.
  2. Set up reporting and configure a web server to receive and save the reports.
  3. Set Cross-Origin-Embedder-Policy-Report-Only: require-corp on your top-level document. Again, this header lets you see the impact of enabling COEP: require-corp without actually affecting your site's functioning yet. You can configure this header to send reports to the same reporting server that you set up in the previous step.

You can also enable the Domain column in Chrome DevTools Network panel to get a general view of which resources would be impacted.

Caution:

Enabling cross-origin isolation will block the loading of cross-origin resources that you don't explicitly opt-in, and it will prevent your top-level document from being able to communicate with popup windows.

We've been exploring ways to deploy Cross-Origin-Resource-Policy at scale, as cross-origin isolation requires all subresources to explicitly opt-in. And we have come up with the idea of going in the opposite direction: a new COEP "credentialless" mode that allows loading resources without the CORP header by stripping all their credentials. We are figuring out the details of how it should work, but we hope this will lighten your burden of making sure the subresources are sending the Cross-Origin-Resource-Policy header.

Also, it's known that the Cross-Origin-Opener-Policy: same-origin header will break integrations that require cross-origin window interactions such as OAuth and payments. To mitigate this problem, we are exploring relaxing the condition to enable cross-origin isolation to Cross-Origin-Opener-Policy: same-origin-allow-popups. This way the communication with the window opened by itself will be possible.

If you want to enable cross-origin isolation but are blocked by these challenges, we recommend registering for an origin trial and waiting until the new modes are available. We are not planning to terminate the origin trial until these new modes are available.

Mitigate the impact of cross-origin isolation #

After you have determined which resources will be affected by cross-origin isolation, here are general guidelines for how you actually opt-in those cross-origin resources:

  1. On cross-origin resources such as images, scripts, stylesheets, iframes, and others, set the Cross-Origin-Resource-Policy: cross-origin header. On same-site resources, set Cross-Origin-Resource-Policy: same-site header.
  2. Set the crossorigin attribute in the HTML tag on top-level document if the resource is served with CORS (for example, <img src="example.jpg" crossorigin>).
  3. If cross-origin resources loaded into iframes involve another layer of iframes, recursively apply steps described in this section before moving forward.
  4. Once you confirm that all cross-origin resources are opted-in, set the Cross-Origin-Embedder-Policy: require-corp header on the cross-origin resources loaded into iframes.
  5. Make sure there are no cross-origin popup windows that require communication through postMessage(). There's no way to keep them working when cross-origin isolation is enabled. You can move the communication to another document that isn't cross-origin isolated, or use a different communication method (for example, HTTP requests).

Enable cross-origin isolation #

After you have mitigated the impact by cross-origin isolation, here are general guidelines to enable cross-origin isolation:

  1. Set the Cross-Origin-Opener-Policy: same-origin header on your top-level document. If you had set Cross-Origin-Opener-Policy-Report-Only: same-origin, replace it. This blocks communication between your top-level document and its popup windows.
  2. Set the Cross-Origin-Embedder-Policy: require-corp header on your top-level document. If you had set Cross-Origin-Embedder-Policy-Report-Only: require-corp, replace it. This will block the loading of cross-origin resources that are not opted-in.
  3. Check that self.crossOriginIsolated returns true in console to verify that your page is cross-origin isolated.
Gotchas!

Enabling cross-origin isolation on a local server might be a pain as simple servers do not support sending headers. You can launch Chrome with a command line flag --enable-features=SharedArrayBuffer to enable SharedArrayBuffer without enabling cross-origin isolation. Learn how to run Chrome with a command line flag on respective platforms.

Resources #

Last updated: Improve article