Header guide · COOP, COEP and CORP

COOP, COEP and CORP: cross-origin isolation without breaking your site

What COOP, COEP and CORP do, what each one breaks, how WebSec0 adds up to 10 points for them, and tested configurations for Nginx, Apache, Caddy and Traefik.

  • By
  • Updated
  • 8 min read
  • Tested on Chromium 152, nginx 1.28 to 1.31, Apache httpd 2.4.58 to 2.4.69, Caddy 2.9 to 2.11, Traefik 2.11 to 3.7 and Helmet 8.3 on Express 5.3
A page sends Cross-Origin-Opener-Policy: same-origin, Cross-Origin-Embedder-Policy: require-corp and Cross-Origin-Resource-Policy: same-origin, worth 5, 3 and 2 bonus points in WebSec0. Under COEP, a cross-origin image without CORP is blocked and one with CORP cross-origin loads, and the page is cross-origin isolated.YOUR PAGECross-Origin-Opener-Policy: same-origin+5Cross-Origin-Embedder-Policy: require-corp+3Cross-Origin-Resource-Policy: same-origin+2CROSS-ORIGIN IMAGEUNDER COEPno CORP headerblockedCORP: cross-originloadedcrossOriginIsolated: true
In short4 points
  • Cross-Origin-Opener-Policy: same-origin cuts the link between your page and windows from other sites. Cross-Origin-Resource-Policy: same-origin stops other sites from loading your files with tags such as <img> or <script>. Both are safe defaults for most sites.
  • Cross-Origin-Embedder-Policy blocks every cross-origin resource that does not opt in. With COOP same-origin, it makes the page cross-origin isolated, which SharedArrayBuffer needs. Turn it on only when you need that.
  • WebSec0 adds 5 points for COOP same-origin, 3 for any COEP and 2 for any CORP on your home page. The score stays capped at 100.
  • Send each header once. In our Chromium test, a header sent twice, by the application and by the proxy, was ignored as if it were missing.

What are COOP, COEP and CORP?

COOP, COEP and CORP are three response headers that keep other sites away from your pages and files. Cross-Origin-Opener-Policy (COOP) separates your page from windows opened by or for other sites. Cross-Origin-Resource-Policy (CORP) decides which sites may embed your files. Cross-Origin-Embedder-Policy (COEP) makes your page refuse cross-origin files that have not agreed to be embedded.

For most sites, two of them are safe to send everywhere:

HTTP
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: same-origin

The third, COEP, blocks more than it protects unless you need what it unlocks: cross-origin isolation, and with it SharedArrayBuffer.

Why do these headers exist?

They are a response to Spectre. web.dev’s explanation says Spectre makes any data loaded into the same browsing context group as a page’s code potentially readable, and that precise timers speed the attack up. MDN notes that high-resolution timers were effectively disabled at the start of 2018, and browsers now hide SharedArrayBuffer from pages that are not cross-origin isolated. These headers are how a site earns them back, by showing that nothing from another site shares its context without consent.

The W3C’s Post-Spectre Web Development draft recommends the restrictive values by default: CORP same-origin for resources, and COOP same-origin for documents where possible, loosened only where a feature needs it.

What does each header do?

Cross-Origin-Opener-Policy

COOP decides whether your page shares a browsing context group with windows from other origins. When the two are separated, the opener and the popup lose their references to each other: window.opener is null.

Value Effect, according to MDN
unsafe-none The default: the page shares its context with any other
same-origin-allow-popups Like same-origin, but popups that your page opens with window.open() keep their link to it
same-origin Only same-origin pages with the same policy stay linked; every other window is cut off
noopener-allow-popups The page is cut off from the window that opened it, even on the same origin, but keeps its popups; Chrome 131 and Safari 18.4, not Firefox

same-origin breaks flows in which your page and a popup on another origin talk to each other, such as some OAuth sign-ins and payment windows. Google’s sign-in documentation warns that COOP can leave its popup blank when FedCM is off, and points to same-origin-allow-popups.

Cross-Origin-Resource-Policy

CORP is set on the resource, not on the page. It tells the browser which sites may load it through no-cors requests: <img>, <script>, <link>, <video> and similar tags.

Value Who may load the resource
same-origin Only pages on the same scheme, host and port
same-site Pages on the same site, so your other subdomains too
cross-origin Any site

In our Chromium test, a page on another site could load an image without CORP or with cross-origin, and the browser blocked the ones with same-origin or same-site. CORP does not apply to requests made with CORS, such as fetch() or an <img crossorigin>: those follow Access-Control-Allow-Origin.

Cross-Origin-Embedder-Policy

COEP is set on the page. It makes the page refuse cross-origin resources that have not opted in, with CORP or with CORS.

Value Cross-origin resources without CORP or CORS
unsafe-none Load as usual; the default
require-corp Blocked
credentialless Loaded without cookies; Chrome 96 and Firefox 119, not Safari

COEP also covers iframes: a document embedded in an isolated page must opt in too, as web.dev’s rollout guide notes.

What does cross-origin isolation enable?

A page is cross-origin isolated when it sends COOP same-origin and COEP require-corp or credentialless. MDN’s crossOriginIsolated page lists what that unlocks: SharedArrayBuffer, a more precise performance.now(), and performance.measureUserAgentSpecificMemory(). WebAssembly threads need SharedArrayBuffer, so a page that runs a multithreaded build of a game engine, a video encoder or a database needs isolation.

Our test in Chromium 152, with a page on localhost that loaded images from another site. COOP is same-origin in every row that has it:

Page sends Isolated No CORP CORP cross-origin
Nothing No Loaded Loaded
COOP No Loaded Loaded
COOP, COEP unsafe-none No Loaded Loaded
COOP, COEP require-corp Yes Blocked Loaded
COOP, COEP credentialless Yes Loaded Loaded

The last two columns are images on the other site, without a Cross-Origin-Resource-Policy header and with cross-origin.

typeof SharedArrayBuffer was "function" only on the two isolated pages, and "undefined" on the others.

How WebSec0 grades COOP, COEP and CORP

These headers are not among the six graded headers. WebSec0 reads them on the response to your home page and adds bonus points to the headers score:

Header on the home page Bonus
Cross-Origin-Opener-Policy: same-origin +5
Cross-Origin-Opener-Policy with any other value Shown as a warning, no bonus
Cross-Origin-Embedder-Policy, any value +3
Cross-Origin-Resource-Policy, any value +2

The score is capped at 100, so the bonus only helps a site that loses points elsewhere. A site at 95 for a version in its Server header gets back to 100 with COOP same-origin alone.

The checks are simple, and three details follow from them:

  • COOP needs exactly same-origin. same-origin; report-to="coop" earns nothing, although browsers apply it: our test page with that value was cross-origin isolated.
  • COEP and CORP earn their points with any value, including unsafe-none and cross-origin, which change nothing in the browser.
  • WebSec0 reads the first line of each header. Browsers ignore a header that is sent twice (see below), so the bonus can show for a header that has no effect.

A safe default: COOP and CORP same-origin

Most sites can send these two headers on every response:

HTTP
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: same-origin

Before you do, check the two things they can break:

  • Popups that talk to your page. Sign-in and payment popups on another origin lose window.opener. If yours stop working, use same-origin-allow-popups on the pages that open them.
  • Files that other sites load. Fonts, images or scripts used by your other subdomains need same-site. Files that any site may embed, such as public web fonts or images on a CDN, need cross-origin.

Neither header blocks a visitor who follows a link to your site, and crawlers that fetch your pages directly do not apply them.

Send each header once

A header sent twice breaks in the browser, even with the same value twice. MDN notes that COEP set more than once is equivalent to unsafe-none. Our tests in Chromium 152 found the same for the other two:

Sent twice Result
Cross-Origin-Opener-Policy: same-origin Ignored: the page was not cross-origin isolated
Cross-Origin-Embedder-Policy: require-corp Ignored: images without CORP loaded
Cross-Origin-Resource-Policy: same-origin Ignored: another site could load the image

The usual cause is a proxy that adds a header the application already sends. Helmet, the Express middleware, sends Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Resource-Policy: same-origin by default; in our test with Helmet 8.3, COEP appeared only once enabled, as require-corp. Set each header in one place. The configurations below remove the application’s copy first.

Configure it on your server

These configurations send COOP and CORP same-origin on every response, error pages included, and CORP cross-origin on public web fonts. Each was run behind an application that sent its own values for all three headers, and checked with curl on the home page, a 404, a font and a missing font.

Nginx

A map in the http block picks the CORP value from the path:

Nginx
map $uri $corp_policy {
    default   "same-origin";
    ~^/fonts/ "cross-origin";
}

Add two lines to the security headers snippet that every server and location includes, as in the Nginx security headers guide:

Nginx
add_header Cross-Origin-Opener-Policy "same-origin" always;
add_header Cross-Origin-Resource-Policy $corp_policy always;

Then hide the application’s copies in the server block:

Nginx
server {
    # ...
    include snippets/security-headers.conf;
    proxy_hide_header Cross-Origin-Opener-Policy;
    proxy_hide_header Cross-Origin-Embedder-Policy;
    proxy_hide_header Cross-Origin-Resource-Policy;

    location / {
        proxy_pass http://127.0.0.1:8080;
    }

    location /fonts/ {
        root /var/www/example.com;
    }
}

On nginx 1.28, 1.30 and 1.31, every response carried one COOP and one CORP, with cross-origin on fonts and their 404s. Without the proxy_hide_header lines, the home page carried both the application’s values and Nginx’s.

Apache

Apache
<VirtualHost *:443>
    ServerName example.com
    # ...
    ProxyPass "/fonts/" "!"
    ProxyPass "/" "http://127.0.0.1:8080/"

    Header unset Cross-Origin-Opener-Policy
    Header unset Cross-Origin-Embedder-Policy
    Header unset Cross-Origin-Resource-Policy
    Header always set Cross-Origin-Opener-Policy "same-origin"
    Header always set Cross-Origin-Resource-Policy "same-origin"

    <Location "/fonts/">
        Header always set Cross-Origin-Resource-Policy "cross-origin"
    </Location>
</VirtualHost>

The application’s headers sit in the table that Header unset edits, and yours in the always table. On httpd 2.4.58, 2.4.62 and 2.4.69, each response carried one of each header. Without the three Header unset lines, the home page carried both sets. The <Location> block replaces CORP for fonts.

Caddy

Set CORP inside each handle block:

Caddyfile
example.com {
	header Cross-Origin-Opener-Policy "same-origin"

	handle /fonts/* {
		header Cross-Origin-Resource-Policy "cross-origin"
		root * /var/www/example.com
		file_server
	}
	handle {
		header Cross-Origin-Resource-Policy "same-origin"
		reverse_proxy 127.0.0.1:8080 {
			header_down -Cross-Origin-Opener-Policy
			header_down -Cross-Origin-Embedder-Policy
			header_down -Cross-Origin-Resource-Policy
		}
	}
}

On Caddy 2.9, 2.10 and 2.11, every response carried one COOP and one CORP, with cross-origin on fonts. Our first attempt set CORP same-origin for the whole site and header /fonts/* Cross-Origin-Resource-Policy "cross-origin" next to it: fonts came back with same-origin, because the site-wide line ran last.

Traefik

Traefik has no dedicated option for these headers. Set them with customResponseHeaders, which replace the application’s values; an empty value removes a header:

YAML
http:
  middlewares:
    isolation:
      headers:
        customResponseHeaders:
          Cross-Origin-Opener-Policy: "same-origin"
          Cross-Origin-Resource-Policy: "same-origin"
          Cross-Origin-Embedder-Policy: ""
    public-fonts:
      headers:
        customResponseHeaders:
          Cross-Origin-Opener-Policy: "same-origin"
          Cross-Origin-Resource-Policy: "cross-origin"
          Cross-Origin-Embedder-Policy: ""

  routers:
    site:
      rule: "Host(`example.com`)"
      entryPoints: [websecure]
      tls: {}
      service: backend
      middlewares: [isolation]
    fonts:
      rule: "Host(`example.com`) && PathPrefix(`/fonts/`)"
      entryPoints: [websecure]
      tls: {}
      service: backend
      middlewares: [public-fonts]

The longer rule of fonts takes priority over site. On Traefik 2.11, 3.6 and 3.7, every response carried one COOP and one CORP, with cross-origin on fonts. Add these lines to your existing security headers middleware rather than chaining a second one.

Turn on COEP when you need isolation

Enable COEP on the pages that need SharedArrayBuffer, in the steps that web.dev’s rollout guide recommends:

  1. Send COOP same-origin on those pages, as above.
  2. Make every cross-origin resource they load opt in. Ask the provider to send CORP cross-origin or CORS headers, and add the crossorigin attribute to tags that load resources with CORS. Files on the same origin need nothing, but your other subdomains count as cross-origin.
  3. Send Cross-Origin-Embedder-Policy-Report-Only: require-corp first. In our test, it blocked nothing: the image without CORP still loaded. web.dev explains how to collect the reports with the Reporting API.
  4. Switch to the enforcing header once no resource fails.
Server Line to add
Nginx add_header Cross-Origin-Embedder-Policy "require-corp" always; in the snippet
Apache Header always set Cross-Origin-Embedder-Policy "require-corp" after the Header unset lines
Caddy header Cross-Origin-Embedder-Policy "require-corp" next to the COOP line
Traefik Cross-Origin-Embedder-Policy: "require-corp" instead of "" in the isolation middleware

Use credentialless instead if most of your cross-origin resources are public files from providers that you cannot change, and you do not need Safari to be isolated. When COEP blocks a resource, Chromium logs net::ERR_BLOCKED_BY_RESPONSE.NotSameOriginAfterDefaultedToSameOriginByCoep in the console; a CORP block shows as NotSameOrigin or NotSameSite.

Verify it

Check the headers on the home page and on a file that other sites load. Use your own URLs:

Shell
curl -sI https://example.com/ | grep -i "^cross-origin-"
curl -sI https://example.com/fonts/inter.woff2 | grep -i "^cross-origin-"

The home page should show each header once, with same-origin. The font should show cross-origin-resource-policy: cross-origin. On a page where you enabled COEP, run self.crossOriginIsolated in the browser console: it should print true. Then scan the site with WebSec0; the headers report lists the three headers under the additional headers.

Questions

Frequently asked questions

What is cross-origin isolation?

A page is cross-origin isolated when it sends Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp or credentialless. self.crossOriginIsolated is then true, and the page can use SharedArrayBuffer, a more precise performance.now() and performance.measureUserAgentSpecificMemory().

Does COOP same-origin break OAuth or payment popups?

It can. With same-origin, a popup on another origin loses its link to your page. Google's documentation warns that this can leave its sign-in popup blank when FedCM is off, and points to same-origin-allow-popups. That value earns no bonus in WebSec0, but a working sign-in matters more than 5 points.

Should I set Cross-Origin-Embedder-Policy if I don't need SharedArrayBuffer?

No. COEP's only purpose is to allow cross-origin isolation, and it blocks every cross-origin resource that does not opt in. WebSec0 gives 3 points for any value, including unsafe-none, which is the browser's default and changes nothing.

What is the difference between require-corp and credentialless?

require-corp blocks cross-origin resources that send neither Cross-Origin-Resource-Policy nor CORS headers. credentialless loads them without cookies instead. According to MDN's compatibility data, Chrome supports credentialless since version 96 and Firefox since 119; Safari does not support it.

Which Cross-Origin-Resource-Policy value should I use?

same-origin for most responses. Use same-site for files that your other subdomains load, and cross-origin for files that any site may embed, such as public web fonts or images on a CDN.

Why does WebSec0 not give the COOP bonus to my site?

WebSec0 gives the 5 points only when the value is exactly same-origin. same-origin-allow-popups, noopener-allow-popups and same-origin; report-to="…" earn nothing, even though browsers apply the last one.

References

Sources

About the author

Portrait of Joshua Martinelle

Security engineer at Tenable

Security engineer at Tenable and web security researcher. He has disclosed more than 60 CVEs since 2020 and builds WebSec0.

Verify the change

Deployed it? Check it.

WebSec0 grades your TLS setup and security headers, including COOP, COEP and CORP, in a few seconds. Free, no account.

Scan your site