A guide to enable cross-origin isolation | Articles

Using Chrome DevTools

Chrome DevTools allows developers to inspect websites.

Open the Chrome DevTools on the page you suspect might be using


     SharedArrayBuffer

Select the Console panel.

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

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.

(Advanced) Using Deprecation Reporting

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

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.

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"}]}

Once the header starts to propagate, the endpoint you registered to should start collecting deprecation reports.

See an example implementation here: https://cross-origin-isolation.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.

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.

Set up reporting and configure a web server to receive and save the reports.

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.

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 hope this will lighten your burden of making sure the subresources are sending the


     Cross-Origin-Resource-Policy

header. Though


     credentialless

mode is available on Chrome from version 96, it's not supported by any other browsers yet, this may cause some developers find it challenging to deploy COOP or COEP at this stage. 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:

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.

For resources loadable using CORS , make sure it is enabled, by setting the


     crossorigin

attribute in its HTML tag (for example,


     <img src="example.jpg" crossorigin>

). For JavaScript fetch request, make sure


     request.mode

is set to


     cors

If you want to use powerful features such as


     SharedArrayBuffer

inside a loaded iframe, append


     allow="cross-origin-isolated"

to the


     <iframe>

If cross-origin resources loaded into iframes or worker scripts involve another layer of iframes or worker scripts, recursively apply steps described in this section before moving forward.

Once you confirm that all cross-origin resources are opted-in, set the


     Cross-Origin-Embedder-Policy: require-corp

header on iframes and worker scripts (This is required regardless of same-origin or cross-origin).

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:

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.

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.

Check that


     self.crossOriginIsolated

returns


     true

in console to verify that your page is cross-origin isolated.

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

Making your website "cross-origin isolated" using COOP and COEP

SharedArrayBuffer updates in Android Chrome 88 and Desktop Chrome

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License , and code samples are licensed under the Apache 2.0 License . For details, see the Google Developers Site Policies . Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2021-02-09 UTC.

[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2021-02-09 UTC."],[],[],null,[]]