HTTP-заголовок Cross-Origin-Embedder-Policy (COEP) ответа задаёт политику текущего документа для загрузки и встраивания ресурсов из других источников, запрашиваемых в режиме no-cors.

Обратите внимание, что политика встраивания для запросов, выполняемых в режиме cors, задаётся с помощью CORS.

Синтаксис

Cross-Origin-Embedder-Policy: <token>; <parameter>

Директивы

Заголовок должен содержать только один токен и необязательную конечную точку report-to. Установка заголовка несколько раз или с несколькими токенами равносильна установке значения unsafe-none.

Значение <token> может быть одним из следующих:

unsafe-none

Разрешает документу загружать ресурсы из других источников, запрошенные в режиме no-cors, не требуя явного разрешения через заголовок Cross-Origin-Resource-Policy. Это значение используется по умолчанию.

require-corp

Документ может загружать ресурсы, запрошенные в режиме no-cors, только с того же источника либо ресурсы, для которых явно задан заголовок Cross-Origin-Resource-Policy со значением, разрешающим встраивание.

COEP блокирует загрузку ресурсов из других источников, если не выполняется одно из условий:

• Ресурс запрошен в режиме no-cors, а ответ содержит заголовок Cross-Origin-Resource-Policy, разрешающий загрузку в источник документа.
• Ресурс запрошен в режиме cors, например в HTML с помощью атрибута crossorigin или в JavaScript посредством запроса с параметром {mode="cors"}. Обратите внимание: запросы в режиме cors не блокируются COEP и не вызывают нарушений COEP, однако для них по-прежнему требуется разрешение CORS.

credentialless

Документ может загружать ресурсы из других источников, запрошенные в режиме no-cors, не запрашивая явного разрешения через заголовок Cross-Origin-Resource-Policy. В этом случае запросы отправляются без учётных данных: файлы cookie не включаются в запрос и игнорируются в ответе.

Поведение при загрузке ресурсов из других источников для остальных режимов запросов такое же, как для require-corp. Например, ресурс из другого источника, запрошенный в режиме cors, должен поддерживать CORS и иметь соответствующее разрешение.

Параметр <parameter> является необязательным и может иметь одно из следующих значений:

report-to <endpoint_name> Необязательно

Значение <endpoint_name> — это имя конечной точки, на которую будут отправляться сообщения о нарушениях политики. Соответствие между именем и конкретной конечной точкой задаётся отдельно в HTTP-заголовке Reporting-Endpoints.

Описание

Политика, определяющая, можно ли встраивать конкретный ресурс с другого сайта, может быть задана для этого ресурса с помощью заголовка Cross-Origin-Resource-Policy (CORP) в ответе на запрос no-cors или с помощью CORS. Если ни одна из этих политик не задана, по умолчанию ресурсы можно загружать или встраивать в документ так, как если бы для них было установлено значение CORP cross-origin (то есть их можно загружать из другого источника).

Заголовок Cross-Origin-Embedder-Policy позволяет требовать установки заголовков CORP в ответах на запросы no-cors, чтобы загружать ресурсы с других сайтов в текущий документ. Также можно сохранить поведение по умолчанию или разрешить загрузку ресурсов, но удалить все учётные данные, которые в противном случае могли бы быть отправлены. Политика применяется к загружаемым ресурсам, а также к ресурсам во <iframe> и вложенных фреймах.

Изоляция от других источников

COEP и CORS вместе гарантируют, что процесс браузера содержит только ресурсы, согласившиеся на совместное использование, или ресурсы, не содержащие личных данных. Это одно из условий, необходимых для изоляции документа от других источников.

Отчёты о нарушениях

О нарушениях политики можно сообщать с помощью Reporting API. Отчёты можно отслеживать на странице, для которой задана политика, используя ReportingObserver, а также отправлять на конечные точки сервера, заданные в HTTP-заголовке ответа Reporting-Endpoints и выбранные с помощью параметра report-to. Подробнее см. в разделе COEPViolationReport.

Примеры

Блокировка и отправка отчётов, если для ресурсов не заданы заголовки CORP

В этом примере показан документ, блокирующий загрузку ресурсов, запрошенных в режиме no-cors, если для них не задан подходящий заголовок CORP.

Документ представляет собой HTML-файл, размещённый на источнике https://example.com. В его теле содержится элемент <img>, в качестве источника которого указан ресурс some-image.png (из другого источника). Поскольку у элемента отсутствует атрибут cross-origin, запрос будет выполнен в режиме no-cors:

<img src="https://another-example.com/some-image.png" />

В заголовке ответа для документа задаются заголовки Cross-Origin-Embedder-Policy и Reporting-Endpoints, как показано ниже. Поскольку задана директива require-corp, все ресурсы из других источников, запрошенные в режиме no-cors, должны предоставляться с заголовком CORP. Параметр report-to задаёт имя "coep-endpoint" для конечной точки, на которую следует отправлять отчёты, а Reporting-Endpoints указывает, как это имя соотносится с конкретным URL.

Reporting-Endpoints: coep-endpoint="https://some-example.com/coep"
Cross-Origin-Embedder-Policy: require-corp; report-to="coep-endpoint"

Чтобы загрузить some-image.png без нарушения политики, для него необходимо задать Cross-Origin-Resource-Policy со значением cross-origin. Если опустить этот заголовок или не указать в нём значение cross-origin, произойдёт нарушение.

Отчёт, отправленный в POST-запросе, будет похож на показанный ниже объект JSON:

[
  {
    "age": 717139,
    "body": {
      "blockedURL": "https://another-example.com/some-image.png",
      "destination": "image",
      "disposition": "enforce",
      "type": "corp"
    },
    "type": "coep",
    "url": "https://example.com",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"
  }
]

Значение type в отчёте — coep, а значение url — это документ, в котором произошло нарушение. Значение body в отчёте содержит URL заблокированного ресурса (blockedURL), его назначение (image), тип нарушения (corp), а также указывает, что отчёт относится к принудительно применённому нарушению (disposition).

Функции, зависящие от изоляции от других источников

Некоторые функции, например доступ к объектам SharedArrayBuffer или использование Performance.now() с таймерами без ограничения частоты, доступны только в том случае, если ваш документ изолирован от других источников.

Чтобы использовать эти функции в документе, необходимо задать заголовку COEP значение require-corp или credentialless, а заголовку Cross-Origin-Opener-Policy — значение same-origin. Кроме того, функция не должна блокироваться политикой Permissions-Policy: cross-origin-isolated.

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

С помощью свойств Window.crossOriginIsolated и WorkerGlobalScope.crossOriginIsolated можно проверить, ограничены ли функции в контекстах окна и рабочего процесса соответственно:

const myWorker = new Worker("worker.js");

if (crossOriginIsolated) {
  const buffer = new SharedArrayBuffer(16);
  myWorker.postMessage(buffer);
} else {
  const buffer = new ArrayBuffer(16);
  myWorker.postMessage(buffer);
}

Как избежать блокировки COEP с помощью CORS

Если вы включили COEP с помощью require-corp и хотите встроить ресурс из другого источника, поддерживающий CORS, необходимо явно указать, что запрос выполняется в режиме cors.

Например, чтобы загрузить изображение, объявленное в HTML и размещённое на стороннем сайте с поддержкой CORS, можно использовать атрибут crossorigin, чтобы запрос выполнялся в режиме cors:

<img src="https://thirdparty.com/img.png" crossorigin />

Аналогично, чтобы запросить файл в режиме CORS с помощью JavaScript, можно использовать атрибут HTMLScriptElement.crossOrigin или выполнить запрос с параметром { mode: 'cors' }.

Если некоторые изображения не поддерживают CORS, можно использовать значение COEP credentialless. Это позволит загружать изображение без явного разрешения со стороны сервера другого источника, но запрос будет отправлен без файлов cookie.

Спецификации

Совместимость с браузерами

См. также

• Cross-Origin-Embedder-Policy-Report-Only
• Cross-Origin-Opener-Policy
• Window.crossOriginIsolated и WorkerGlobalScope.crossOriginIsolated
• ReportingObserver
• COEPViolationReport
• Reporting API
• Cross Origin Opener Policy в статье Почему для мощных функций необходима «изоляция от других источников» на web.dev (2020)
• COOP и COEP: объяснение от Артура Янца, Чарли Рейса и Анны ван Кестерен (2020)