Skip to content

Cross Origin Isolation

Jump to bottom
Josselin Guillozet edited this page Oct 19, 2026 · 2 revisions

Target version: 7.0+

A document becomes cross-origin isolated when it sets both of:

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

The SDK does not need either header, and gains nothing from them. Face detection runs single-threaded WebAssembly by design, so SharedArrayBuffer is never used and there is no faster path to unlock.

This page is for integrations that set these headers for their own reasons. Both have consequences for the SDK, and one of them breaks it silently.

⚠️ Do not set Cross-Origin-Opener-Policy: same-origin if you rely on the Iframe Bridge

The Iframe Bridge runs the claim in a top-level tab and posts the result back with window.opener.postMessage. Cross-Origin-Opener-Policy: same-origin severs window.opener for any document that lands in a different browsing-context group from its opener. A same-origin document that sends the same policy stays in the group — but a window opened from a cross-origin iframe does not, and a cross-origin iframe is the only situation in which the bridge runs at all.

The failure is silent and total: the claim runs to completion in the new tab, and the passed or failed result never reaches your integrator callbacks.

Two documents matter here, and they are easy to conflate. COOP is a top-level header, so the document that sets it is the page at the top of the tab. The document that embeds <iproov-me> and sets assets_url is a cross-origin iframe within that page — frequently a different party. Anything you change about the frame or the bridge tab says nothing about the top-level page's COOP.

The bridge activates for Firefox on Android inside a cross-origin iframe, where Gecko will not deliver device motion to a third-party frame. If that combination is in scope for you, the change has to be made on the top-level page, which must either:

  • omit Cross-Origin-Opener-Policy entirely, or
  • send Cross-Origin-Opener-Policy: same-origin-allow-popups, which keeps the opener reference for windows you open while still isolating your document from ones that open you.

There is nothing you can configure on the SDK's side of this. Serving the assets from your own origin does not help, and neither does sending Cross-Origin-Opener-Policy: same-origin with the bridge page itself: measured on Firefox 155 for Android, a window opened from a cross-origin iframe loses window.opener under a top-level same-origin policy in every combination of bridge origin and bridge policy.

same-origin-allow-popups does not grant cross-origin isolation. That costs the SDK nothing, for the reason above — so on Firefox for Android there is no trade to weigh, only a bridge that works or one that does not.

Cross-Origin-Embedder-Policy: require-corp

require-corp makes the browser refuse any subresource that does not opt in with Cross-Origin-Resource-Policy or CORS. Not every asset the SDK fetches is requested in CORS mode — the rotate-to-portrait animation is a plain <img>, for one — so CORS headers alone do not cover them. If you set this header, the assets_url origin must return Cross-Origin-Resource-Policy: cross-origin. Our CDN sends it; a self-hosted origin is yours to configure, and Serving Assets And CORS lists what else it needs.

If you set require-corp and the assets are not served correctly, the SDK cannot load at all.

Clone this wiki locally