Enable Cross-Origin Isolation Safely

Set COOP and COEP to unlock powerful APIs like SharedArrayBuffer, then handle the resource-loading consequences so the app still works.

~35 minsecuritywebperformance

Task

Enable cross-origin isolation for an app that needs SharedArrayBuffer or high-resolution timers.

When to use this

A feature that requires cross-origin isolation is unavailable, or turning it on breaks images and scripts that do not send the right headers.

Prerequisites

Control over response headers for the app and its resources
Awareness of cross-origin resources used

Steps

1. Set Cross-Origin-Opener-Policy to same-origin and Cross-Origin-Embedder-Policy to require-corp.

Expected output: The page becomes cross-origin isolated.

2. Ensure all cross-origin resources send CORS or CORP headers.

Expected output: Previously optional resources still load.

3. Use crossorigin attributes or CORP on images and fonts that fail.

Expected output: Embedded assets are permitted.

4. Verify crossOriginIsolated is true and the target feature works.

curl -sI https://app.example.com | grep -iE "cross-origin-(opener|embedder)-policy"

Expected output: Isolation is confirmed at runtime.

Troubleshooting

Problem

Images stop loading

Solution

Add crossorigin or ensure the resource sends Cross-Origin-Resource-Policy; isolation blocks unlabeled cross-origin resources.

Problem

Popups break

Solution

COOP same-origin severs opener relationships; open noopener popups and communicate via other channels.

Limitations

Cross-origin isolation can break third-party embeds that do not send the required headers, with no workaround.
It must be applied consistently across the app, or pages will have different capabilities.

Context

Enable cross-origin isolation for an app that needs SharedArrayBuffer or high-resolution timers. A feature that requires cross-origin isolation is unavailable, or turning it on breaks images and scripts that do not send the right headers.

Steps

Set Cross-Origin-Opener-Policy to same-origin and Cross-Origin-Embedder-Policy to require-corp. Expected: The page becomes cross-origin isolated.
Ensure all cross-origin resources send CORS or CORP headers. Expected: Previously optional resources still load.
Use crossorigin attributes or CORP on images and fonts that fail. Expected: Embedded assets are permitted.
Verify crossOriginIsolated is true and the target feature works. Expected: Isolation is confirmed at runtime.

res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
// then: self.crossOriginIsolated === true

Verify

The page becomes cross-origin isolated.
Previously optional resources still load.
Embedded assets are permitted.
Isolation is confirmed at runtime.

Limits

Cross-origin isolation can break third-party embeds that do not send the required headers, with no workaround.
It must be applied consistently across the app, or pages will have different capabilities.