En-tête Cross-Origin-Embedder-Policy (COEP)

Syntaxe

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

Directives

L'en-tête ne doit être défini qu'avec un seul jeton et un point de terminaison report-to optionnel. Définir l'en-tête plus d'une fois ou avec plusieurs jetons équivaut à définir unsafe-none.

La valeur <token> peut être l'une des suivantes :

unsafe-none

Autorise le document à charger des ressources d'origine croisée demandées en mode no-cors sans autorisation explicite via le protocole CORS ou l'en-tête Cross-Origin-Resource-Policy. Il s'agit de la valeur par défaut.

require-corp

Un document ne peut charger que des ressources demandées en mode no-cors depuis la même origine, ou des ressources qui ont explicitement défini l'en-tête Cross-Origin-Resource-Policy à une valeur qui permet leur intégration.

Le chargement de ressources d'origine croisée est bloqué par COEP sauf si :

• La ressource est demandée en mode no-cors et la réponse inclut un en-tête Cross-Origin-Resource-Policy qui autorise son chargement dans l'origine du document.
• La ressource est demandée en mode cors ; par exemple, en HTML avec l'attribut crossorigin, ou en JavaScript en effectuant une requête avec {mode="cors"}. Notez que les requêtes effectuées en mode cors ne seront pas bloquées par COEP et ne déclencheront pas de violations COEP, mais doivent toujours être autorisées par CORS.

credentialless

Un document peut charger des ressources d'origine croisée demandées en mode no-cors sans autorisation explicite via l'en-tête Cross-Origin-Resource-Policy. Dans ce cas, les requêtes sont envoyées sans identifiants : les cookies sont omis dans la requête et ignorés dans la réponse.

Le comportement de chargement cross-origin pour les autres modes de requête est identique à celui de require-corp. Par exemple, une ressource d'origine croisée demandée en mode cors doit prendre en charge (et autoriser) CORS.

Le <parameter> est optionnel et peut être l'un des suivants :

report-to <endpoint_name> Facultatif

<endpoint_name> est le nom du point de terminaison vers lequel les violations de la politique sont envoyées. La correspondance entre le nom et un point de terminaison particulier est définie séparément dans l'en-tête HTTP Reporting-Endpoints.

Description

La politique concernant la possibilité pour une ressource particulière d'être intégrée en inter-site peut être définie pour cette ressource en utilisant l'en-tête Cross-Origin-Resource-Policy (CORP) dans une réponse à une requête no-cors, ou en utilisant le CORS. Si aucune de ces politiques n'est définie, par défaut, les ressources peuvent être chargées ou intégrées dans un document comme si elles ont une valeur CORP de cross-origin (ce qui signifie qu'elles peuvent être chargées inter-origine).

La Cross-Origin-Embedder-Policy permet d'exiger que les en-têtes CORP soient définis, dans les réponses aux requêtes no-cors, afin de charger des ressources inter-origine dans le document actuel. Vous pouvez également définir la politique pour conserver le comportement par défaut, ou pour permettre le chargement des ressources, mais en supprimant les identifiants qui peuvent autrement être envoyés. La politique s'applique aux ressources chargées, ainsi qu'aux ressources dans les <iframe> et les cadres imbriqués.

Isolation inter-origines

COEP et CORS ensemble garantissent que le processus du navigateur ne contient que des ressources qui ont consenti à être partagées, ou qui ne contiennent pas de données privées. C'est l'une des conditions nécessaires pour qu'un document soit isolé inter-origines.

Rapports de violation

Les violations de la politique peuvent être signalées en utilisant l'API de rapport. Les rapports peuvent être observés dans la page pour laquelle la politique est définie en utilisant un ReportingObserver, et envoyés aux points de terminaison du serveur définis dans un en-tête de réponse HTTP Reporting-Endpoints et sélectionnés en utilisant le paramètre report-to. Pour plus d'informations, voir COEPViolationReport.

Exemples

Bloquer et signaler lorsque les ressources ne définissent pas les en-têtes CORP

Cet exemple montre un document qui bloque le chargement des ressources demandées en mode no-cors qui ne définissent pas un en-tête CORP approprié.

Le document est un fichier HTML hébergé sur l'origine https://exemple.com, et inclut dans son corps un élément HTML <img> qui définit comme source la ressource (inter-origine) une-image.png. Comme l'élément n'a pas l'attribut cross-origin, il est demandé en mode no-cors :

<img src="https://autre-exemple.com/une-image.png" />

L'en-tête de réponse pour le document définit les en-têtes Cross-Origin-Embedder-Policy et Reporting-Endpoints comme indiqué ci-dessous. Comme la directive require-corp est définie, toutes les ressources inter-origines demandées en mode no-cors doivent être servies avec l'en-tête CORP. Le paramètre report-to définit le nom "coep-endpoint" comme nom du point de terminaison où les rapports doivent être envoyés, et Reporting-Endpoints définit comment ce nom est mis en correspondance à une URL particulière.

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

Pour que une-image.png soit chargée sans déclencher de violation, elle doit définir Cross-Origin-Resource-Policy sur cross-origin. Si l'on omet l'en-tête ou qu'on ne l'inclut pas en tant que cross-origin, une violation se produit.

Le rapport envoyé dans la requête POST de rapport sera similaire à l'objet JSON montré ci-dessous :

[
  {
    "age": 717139,
    "body": {
      "blockedURL": "https://autre-exemple.com/une-image.png",
      "destination": "image",
      "disposition": "enforce",
      "type": "corp"
    },
    "type": "coep",
    "url": "https://exemple.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"
  }
]

Le type du rapport est coep, et son url est le document dans lequel la violation s'est produite. Le body du rapport fournit l'URL de la ressource bloquée (blockedURL), sa destination (image), le type de violation (corp), et indique que le rapport concernait une violation appliquée (disposition).

Fonctionnalités dépendant de l'isolation inter-origines

Certaines fonctionnalités, comme l'accès aux objets SharedArrayBuffer ou l'utilisation de Performance.now() avec des minuteurs non limités, ne sont disponibles que si votre document est isolé inter-origines.

Pour utiliser ces fonctionnalités dans un document, vous devez définir l'en-tête COEP avec la valeur require-corp ou credentialless, et l'en-tête Cross-Origin-Opener-Policy à same-origin. De plus, la fonctionnalité ne doit pas être bloquée par Permissions-Policy : cross-origin-isolated.

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

Vous pouvez utiliser les propriétés Window.crossOriginIsolated et WorkerGlobalScope.crossOriginIsolated pour vérifier si les fonctionnalités sont restreintes respectivement dans les contextes window et worker :

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);
}

Éviter le blocage COEP avec CORS

Si vous activez COEP avec require-corp et souhaitez intégrer une ressource d'origine croisée qui prend en charge CORS, vous devrez explicitement indiquer qu'elle est demandée en mode cors.

Par exemple, pour récupérer une image déclarée en HTML depuis un site tiers qui prend en charge CORS, vous pouvez utiliser l'attribut crossorigin afin qu'elle soit demandée en mode cors :

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

Vous pouvez de la même façon utiliser l'attribut HTMLScriptElement.crossOrigin ou effectuer une requête avec { mode: 'cors' } pour demander un fichier en mode CORS en JavaScript.

Si CORS n'est pas pris en charge pour certaines images, une valeur COEP de credentialless peut être utilisée comme alternative pour charger l'image sans consentement explicite du serveur distant, au prix d'une requête sans cookies.

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'en-tête Cross-Origin-Embedder-Policy-Report-Only
• L'en-tête Cross-Origin-Opener-Policy
• Les propriétés API Window.crossOriginIsolated et WorkerGlobalScope.crossOriginIsolated
• L'interface API ReportingObserver
• L'interface API COEPViolationReport
• L'API Reporting
• Cross Origin Opener Policy ^(angl.) dans Why you need "cross-origin isolated" for powerful features sur web.dev (2020)
• COOP et COEP expliqué : Artur Janc, Charlie Reis, Anne van Kesteren ^(angl.) (2020)