How COEP Requires Opt-In for Embedded Media

The Cross-Origin Embedder Policy (COEP) is a browser security mechanism that prevents a document from loading cross-origin resources that have not explicitly granted permission to be embedded. This article explains how COEP enforces strict opt-in requirements for external media—such as images, video, and audio—why this behavior is necessary to unlock high-performance browser capabilities, and the specific response headers developers must implement to safely load third-party assets.

The Role of COEP in Modern Web Security

Web browsers introduced COEP primarily to defend against speculative side-channel attacks, such as Spectre. To protect sensitive data from being leaked across execution boundaries, modern browsers require a document to be in a "cross-origin isolated" state before enabling powerful features like SharedArrayBuffer or high-resolution timers (performance.now()).

To achieve cross-origin isolation, a top-level document must serve two headers:

  1. Cross-Origin-Opener-Policy: same-origin (COOP)
  2. Cross-Origin-Embedder-Policy: require-corp (COEP)

Once Cross-Origin-Embedder-Policy: require-corp is applied, the browser enters a defensive mode where it refuses to load any cross-origin resource unless the server hosting that resource explicitly approves its embedding.

The Blocking Mechanism for Embedded Media

Under standard browser security rules, media elements like <img>, <video>, and <audio> can be embedded across origins without restriction, though the loading page cannot read their raw bytes directly.

However, under COEP, this default permissive loading is disabled. When a page with COEP enabled attempts to load a resource from another origin, the browser intercepts the network response. If the response headers do not contain an explicit grant of permission, the browser blocks the resource entirely, causing network fetch errors in developer tools and broken media on the page.

Methods for Providing Explicit Opt-In

Servers hosting media files must provide an explicit opt-in header to be successfully embedded in a COEP-protected page. There are two primary mechanisms to grant this permission:

1. Cross-Origin Resource Policy (CORP)

The simplest and most direct way for a media server to opt in is by serving the Cross-Origin-Resource-Policy header. This header explicitly informs the browser who is allowed to embed the asset.

To allow any site to embed the media, the server must return:

Cross-Origin-Resource-Policy: cross-origin

If the media is hosted on a sub-domain or related site within the same registrable domain, it can alternatively return:

Cross-Origin-Resource-Policy: same-site

When the browser detects a valid CORP header matching the embedding context, the media is rendered normally.

2. Cross-Origin Resource Sharing (CORS)

Media elements can also satisfy COEP requirements through standard CORS validation. To use this pathway:

  1. The HTML element must declare the crossorigin attribute:

    <img src="https://media.example.com/photo.jpg" crossorigin="anonymous" />
<video src="https://media.example.com/video.mp4" crossorigin="anonymous"></video>

  2. The media server must respond with appropriate CORS headers, such as:

    Access-Control-Allow-Origin: *

Because a CORS request explicitly delegates data access to the client, the browser accepts a successful CORS response as sufficient opt-in under COEP rules.

The Alternative: COEP Credentialless

Configuring external CDNs or third-party platforms to add CORP or CORS headers is not always possible. To address this friction, modern browsers support an alternative policy:

Cross-Origin-Embedder-Policy: credentialless

With credentialless, the browser allows cross-origin media to load without a CORP header, provided the request is sent without ambient credentials (such as cookies or client certificates). This prevents cross-origin data exposure while avoiding the need for universal third-party server updates.

Nested Documents and Media Iframes

If media is embedded via an <iframe> rather than standard media tags, the embedded document must also adhere to the policy. An embedded iframe must send:

Cross-Origin-Embedder-Policy: require-corp

If the child iframe fails to declare COEP, the parent document's COEP configuration will block the entire iframe from rendering.

Summary

COEP shifts the web’s security default from implicit inclusion to explicit consent. To embed external media within a secure, cross-origin isolated application, developers must ensure that every external media asset confirms its availability via Cross-Origin-Resource-Policy: cross-origin, passes a CORS check using the crossorigin attribute, or is handled via Cross-Origin-Embedder-Policy: credentialless.