Ensembles de sites Web associés: guide du développeur

Les ensembles de sites Web associés sont un mécanisme de plate-forme Web qui aide les navigateurs à comprendre les relations entre une collection de domaines. Cela permet aux navigateurs de prendre des décisions clés pour activer certaines fonctions du site (par exemple, autoriser ou non l'accès aux cookies multisites) et de présenter ces informations aux utilisateurs.

De nombreux sites s'appuient sur plusieurs domaines pour offrir une expérience utilisateur unique. Les organisations peuvent souhaiter conserver différents domaines de premier niveau pour plusieurs cas d'utilisation, tels que des domaines spécifiques à un pays ou des domaines de service pour héberger des images ou des vidéos. Les ensembles de sites Web associés permettent aux sites de partager des données entre les domaines, avec des contrôles spécifiques.

Qu'est-ce qu'un ensemble de sites Web associés ?

De manière générale, un Ensemble de sites Web associés est une collection de domaines pour lesquels il existe un seul "site principal" et potentiellement plusieurs "sites membres".

Dans l'exemple suivant, primary liste le domaine principal et associatedSites liste les domaines qui répondent aux exigences du sous-ensemble associé.

{
  "primary": "https://primary.com",
  "associatedSites": ["https://associate1.com", "https://associate2.com", "https://associate3.com"]
}

Les ensembles de sites Web associés sont listés dans un fichier JSON public hébergé sur GitHub. Il s'agit de la source canonique pour tous les ensembles approuvés. Les navigateurs utilisent ce fichier pour déterminer si les sites appartiennent ou non au même ensemble de sites Web associés.

Seules les personnes disposant d'un contrôle administratif sur un domaine peuvent créer un ensemble avec ce domaine. Les personnes qui envoient des données doivent déclarer la relation entre chaque "membre de l'ensemble" et son "ensemble principal". Les membres d'un ensemble peuvent inclure différents types de domaines et doivent faire partie d'un sous-ensemble basé sur un cas d'utilisation.

Si votre application dépend de l'accès aux cookies multisites (également appelés cookies tiers) sur les sites d'un même ensemble de sites Web associés, vous pouvez utiliser l'API Storage Access et l'API requestStorageAccessFor pour demander l'accès à ces cookies. Selon le sous-ensemble auquel appartient chaque site, le navigateur peut traiter la requête différemment.

Pour en savoir plus sur la procédure et les exigences concernant l'envoi d'ensembles, consultez les Consignes d'envoi. Les ensembles envoyés feront l'objet de divers contrôles techniques pour valider les envois.

Cas d'utilisation des ensembles de sites Web associés

Les ensembles de sites Web associés sont adaptés aux cas où une organisation a besoin d'une forme d'identité partagée sur différents sites de premier niveau.

Voici quelques cas d'utilisation des ensembles de sites Web associés :

• Personnalisation par pays : Utiliser des sites localisés tout en s'appuyant sur une infrastructure partagée (par exemple, example.co.uk peut s'appuyer sur un service hébergé par example.ca).
• Intégration du domaine de service : Exploitation de domaines de services avec lesquels les utilisateurs n'interagissent jamais directement, mais qui fournissent des services sur les sites de la même organisation (example-cdn.com, par exemple).
• Séparation du contenu utilisateur Accès aux données sur différents domaines qui séparent le contenu importé par les utilisateurs du reste du contenu du site pour des raisons de sécurité, tout en autorisant l'accès du domaine sandboxé aux cookies d'authentification (et autres). Si vous diffusez du contenu inactif importé par les utilisateurs, vous pouvez également l'héberger en toute sécurité sur le même domaine en suivant les bonnes pratiques.
  • Contenu authentifié intégré : Prise en charge du contenu intégré provenant de propriétés affiliées (vidéos, documents ou ressources réservés à l'utilisateur connecté sur le site de premier niveau).
• Se connecter Prise en charge de la connexion sur les propriétés affiliées. L'API FedCM peut également être appropriée pour certains cas d'utilisation.
• Analytics. Déployer des analyses et des mesures des parcours utilisateur sur les propriétés affiliées pour améliorer la qualité des services.

Détails de l'intégration des ensembles de sites Web associés

API Storage Access

L'API Storage Access (SAA) permet au contenu intégré multi-origines d'accéder au stockage auquel il n'aurait normalement accès que dans un contexte propriétaire.

Les ressources intégrées peuvent utiliser les méthodes SAA pour vérifier si elles ont actuellement accès au stockage et pour demander l'accès à l'agent utilisateur.

Lorsque les cookies tiers sont bloqués, mais que les ensembles de sites Web associés (RWS) sont activés, Chrome accorde automatiquement l'autorisation dans les contextes intra-RWS et affiche une invite à l'utilisateur dans les autres cas. (Un "contexte intra-RWS" est un contexte, tel qu'un iframe, dont le site intégré et le site de premier niveau se trouvent dans le même RWS.)

Vérifier l'accès au stockage et le demander

Pour vérifier s'ils ont actuellement accès au stockage, les sites intégrés peuvent utiliser la méthode Document.hasStorageAccess().

La méthode renvoie une promesse qui se résout avec une valeur booléenne indiquant si le document a déjà accès à ses cookies ou non. La promesse renvoie également la valeur "true" si l'iFrame a la même origine que le frame de premier niveau.

Pour demander l'accès aux cookies dans un contexte inter-sites, les sites intégrés peuvent utiliser Document.requestStorageAccess() (rSA).

L'API requestStorageAccess() est conçue pour être appelée depuis un iFrame. Cet iFrame doit avoir récemment reçu une interaction de l'utilisateur (un geste de l'utilisateur, qui est requis par tous les navigateurs). Toutefois, Chrome exige également que l'utilisateur ait visité le site propriétaire de cet iFrame et ait interagi avec ce site spécifiquement au cours des 30 derniers jours, en tant que document de premier niveau et non dans un iFrame.

requestStorageAccess() renvoie une promesse qui se résout si l'accès au stockage a été accordé. La promesse est refusée, en indiquant le motif, si l'accès a été refusé pour une raison quelconque.

requestStorageAccessFor dans Chrome

L'API Storage Access n'autorise les sites intégrés à demander l'accès au stockage qu'à partir d'éléments <iframe> ayant fait l'objet d'une interaction de l'utilisateur.

Cela pose des problèmes pour l'adoption de l'API Storage Access pour les sites de premier niveau qui utilisent des images ou des balises de script multisites nécessitant des cookies.

Pour résoudre ce problème, Chrome a mis en place un moyen pour les sites de premier niveau de demander l'accès au stockage au nom d'origines spécifiques avec Document.requestStorageAccessFor() (rSAFor).

 document.requestStorageAccessFor('https://target.site')

L'API requestStorageAccessFor() est conçue pour être appelée par un document de premier niveau. Ce document doit également avoir fait l'objet d'une interaction utilisateur récente. Toutefois, contrairement à requestStorageAccess(), Chrome ne recherche pas d'interaction dans un document de premier niveau au cours des 30 derniers jours, car l'utilisateur se trouve déjà sur la page.

Vérifier les autorisations d'accès au stockage

L'accès à certaines fonctionnalités du navigateur, comme l'appareil photo ou la géolocalisation, dépend des autorisations accordées par l'utilisateur. L'API Permissions permet de vérifier l'état des autorisations d'accès à une API (accordées, refusées ou nécessitant une forme d'interaction utilisateur, comme cliquer sur une invite ou interagir avec la page).

Vous pouvez interroger l'état des autorisations à l'aide de navigator.permissions.query().

Pour vérifier l'autorisation d'accès au stockage pour le contexte actuel, vous devez transmettre la chaîne 'storage-access' :

navigator.permissions.query({name: 'storage-access'})

Pour vérifier l'autorisation d'accès au stockage pour une origine spécifique, vous devez transmettre la chaîne 'top-level-storage-access' :

navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'})

Notez que, pour protéger l'intégrité de l'origine intégrée, cette vérification ne concerne que les autorisations accordées par le document de premier niveau à l'aide de document.requestStorageAccessFor.

Selon que l'autorisation peut être accordée automatiquement ou qu'elle nécessite un geste de l'utilisateur, elle renvoie prompt ou granted.

Modèle par frame

Les autorisations rSA s'appliquent par frame. Les autorisations rSA et rSAFor sont traitées comme des autorisations distinctes.

Chaque nouvelle frame devra demander l'accès au stockage individuellement, et l'accès lui sera automatiquement accordé. Seule la première requête nécessite un geste de l'utilisateur. Les requêtes ultérieures initiées par l'iFrame, telles que la navigation ou les sous-ressources, n'auront pas besoin d'attendre un geste de l'utilisateur, car celui-ci sera accordé pour la session de navigation par la requête initiale.

Si vous actualisez, rechargez ou recréez l'iFrame, vous devrez de nouveau demander l'accès.

Exigences concernant les cookies

Les cookies doivent spécifier les attributs SameSite=None et Secure, car rSA fournit uniquement l'accès aux cookies déjà marqués pour une utilisation dans des contextes multisites.

Les cookies avec SameSite=Lax, SameSite=Strict ou sans attribut SameSite sont réservés à un usage propriétaire et ne seront jamais partagés dans un contexte intersites, quel que soit le RSA.

Sécurité

Pour rSAFor, les requêtes de sous-ressources nécessitent des en-têtes Cross-Origin Resource Sharing (CORS) ou l'attribut crossorigin sur les ressources, ce qui garantit un consentement explicite.

Exemples d'intégration

Demander l'accès au stockage depuis un iFrame intégré d'origine différente

Vérifier si vous avez accès au stockage

Pour vérifier si vous avez déjà accès au stockage, utilisez document.hasStorageAccess().

Si la promesse renvoie la valeur "true", vous pouvez accéder au stockage dans le contexte multisite. Si la valeur renvoyée est "false", vous devez demander l'accès au stockage.

document.hasStorageAccess().then((hasAccess) => {
    if (hasAccess) {
      // You can access storage in this context
    } else {
      // You have to request storage access
    }
});

Demander l'accès à l'espace de stockage

Si vous devez demander l'accès au stockage, vérifiez d'abord l'autorisation d'accès au stockage navigator.permissions.query({name: 'storage-access'}) pour voir si elle nécessite un geste de l'utilisateur ou si elle peut être accordée automatiquement.

Si l'autorisation est granted, vous pouvez appeler document.requestStorageAccess() et l'opération devrait réussir sans geste de l'utilisateur.

Si l'état de l'autorisation est prompt, vous devez lancer l'appel document.requestStorageAccess() après un geste de l'utilisateur, comme un clic sur un bouton.

Exemple :

navigator.permissions.query({name: 'storage-access'}).then(res => {
  if (res.state === 'granted') {
    // Permission has already been granted
    // You can request storage access without any user gesture
    rSA();
  } else if (res.state === 'prompt') {
    // Requesting storage access requires user gesture
    // For example, clicking a button
    const btn = document.createElement("button");
    btn.textContent = "Grant access";
    btn.addEventListener('click', () => {
      // Request storage access
      rSA();
    });
    document.body.appendChild(btn);
  }
});

function rSA() {
  if ('requestStorageAccess' in document) {
    document.requestStorageAccess().then(
      (res) => {
        // Use storage access
      },
      (err) => {
        // Handle errors
      }
    );
  }
}

Les requêtes, navigations ou sous-ressources ultérieures provenant du frame seront automatiquement autorisées à accéder aux cookies intersites. hasStorageAccess() renvoie la valeur "true", et les cookies multisites du même ensemble de sites Web associés seront envoyés avec ces requêtes sans aucun appel JavaScript supplémentaire.

Sites de premier niveau demandant l'accès aux cookies pour le compte de sites d'origines croisées

Les sites de premier niveau peuvent utiliser requestStorageAccessFor() pour demander l'accès au stockage au nom d'origines spécifiques.

hasStorageAccess() vérifie uniquement si le site qui l'appelle a accès au stockage. Un site de premier niveau peut donc vérifier les autorisations d'une autre origine.

Pour savoir si l'utilisateur sera invité à accorder l'accès au stockage ou si cet accès a déjà été accordé à l'origine spécifiée, appelez navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'}).

Si l'autorisation est granted, vous pouvez appeler document.requestStorageAccessFor('https://target.site'). Elle doit réussir sans geste de l'utilisateur.

Si l'autorisation est prompt, vous devrez associer l'appel document.requestStorageAccessFor('https://target.site') au geste de l'utilisateur, comme un clic sur un bouton.

Exemple :

navigator.permissions.query({name:'top-level-storage-access',requestedOrigin: 'https://target.site'}).then(res => {
  if (res.state === 'granted') {
    // Permission has already been granted
    // You can request storage access without any user gesture
    rSAFor();
  } else if (res.state === 'prompt') {
    // Requesting storage access requires user gesture
    // For example, clicking a button
    const btn = document.createElement("button");
    btn.textContent = "Grant access";
    btn.addEventListener('click', () => {
      // Request storage access
      rSAFor();
    });
    document.body.appendChild(btn);
  }
});

function rSAFor() {
  if ('requestStorageAccessFor' in document) {
    document.requestStorageAccessFor().then(
      (res) => {
        // Use storage access
      },
      (err) => {
        // Handle errors
      }
    );
  }
}

Après un appel requestStorageAccessFor() réussi, les requêtes multisites incluront des cookies si elles incluent CORS ou l'attribut crossorigin. Les sites peuvent donc attendre avant de déclencher une requête.

Les requêtes doivent utiliser l'option credentials: 'include' et les ressources doivent inclure l'attribut crossorigin="use-credentials".

function checkCookie() {
    fetch('https://related-website-sets.glitch.me/getcookies.json', {
        method: 'GET',
        credentials: 'include'
      })
      .then((response) => response.json())
      .then((json) => {
      // Do something
      });
  }

Tester en local

Prérequis

Pour tester les ensembles de sites Web associés en local, utilisez Chrome 119 ou version ultérieure lancé à partir de la ligne de commande et activez le test-third-party-cookie-phaseout flag Chrome.

Activer le flag Chrome

Pour activer le flag Chrome nécessaire, accédez à chrome://flags#test-third-party-cookie-phaseout depuis la barre d'adresse et définissez le flag sur Enabled. Veillez à redémarrer le navigateur après avoir modifié les indicateurs.

Lancer Chrome avec un ensemble de sites Web associés locaux

Pour lancer Chrome avec un ensemble de sites Web associés déclaré localement, créez un objet JSON contenant les URL membres d'un ensemble et transmettez-le à --use-related-website-set.

Découvrez comment exécuter Chromium avec des indicateurs.

--use-related-website-set="{\"primary\": \"https://related-website-sets.glitch.me\", \"associatedSites\": [\"https://rws-member-1.glitch.me\"]}" \
https://related-website-sets.glitch.me/

Exemple

Pour activer les ensembles de sites Web associés en local, vous devez activer test-third-party-cookie-phaseout dans chrome://flags et lancer Chrome à partir de la ligne de commande avec l'indicateur --use-related-website-set et l'objet JSON contenant les URL membres d'un ensemble.

--use-related-website-set="{\"primary\": \"https://related-website-sets.glitch.me\", \"associatedSites\": [\"https://rws-member-1.glitch.me\"]}" \
https://related-website-sets.glitch.me/

Vérifiez que vous avez accès aux cookies multisites.

Appelez les API (rSA ou rSAFor) à partir des sites testés et validez l'accès aux cookies multisites.

Processus d'envoi des ensembles de sites Web associés

Suivez les étapes ci-dessous pour déclarer la relation entre les domaines et spécifier le sous-ensemble auquel ils appartiennent.

1. Identifier votre RWS

Identifiez les domaines concernés, y compris les sites principaux et les sites membres qui feront partie de l'ensemble de sites Web associés. Identifiez également le type de sous-ensemble auquel appartient chaque membre de l'ensemble.

2. Créer votre envoi RWS

Créez une copie locale (clone ou fork) du dépôt GitHub. Dans une nouvelle branche, apportez les modifications au fichier related_website_sets.JSON pour refléter votre ensemble. Pour vous assurer que votre ensemble possède le format et la structure JSON appropriés, vous pouvez utiliser l'outil de génération JSON.

3. Vérifier que votre RWS répond aux exigences techniques

Assurez-vous de respecter les conditions requises pour la formation des ensembles et les conditions requises pour la validation des ensembles.

4. Tester votre RWS en local

Avant de créer une demande d'extraction pour envoyer votre ensemble, testez votre envoi localement pour vous assurer qu'il passe toutes les vérifications requises.

5. Envoyer votre RWS

Envoyez l'ensemble de sites Web associés en créant une demande d'extraction pour le fichier related_website_sets.JSON, où Chrome héberge la liste canonique des ensembles de sites Web associés. (Un compte GitHub est requis pour créer des demandes d'extraction. Vous devrez également signer un contrat de licence du contributeur (CLA) avant de pouvoir contribuer à la liste.)

Une fois la demande de pull créée, une série de vérifications est effectuée pour s'assurer que les exigences de l'étape 3 sont respectées, par exemple en vérifiant que vous avez signé le CLA et que le fichier .well-known est valide.

Si l'opération réussit, la demande d'extraction indique que les vérifications ont été effectuées. Les demandes de pull approuvées seront fusionnées manuellement par lots dans la liste canonique des ensembles de sites Web associés une fois par semaine (le mardi à 12h, heure de l'Est). Si l'une des vérifications échoue, l'auteur de la demande sera averti par un échec de la demande sur GitHub. Le contributeur peut corriger les erreurs et mettre à jour la demande de pull. Voici quelques points à retenir :

• Si la demande de modification échoue, un message d'erreur fournit des informations supplémentaires sur la raison de l'échec. (exemple).
• Toutes les vérifications techniques régissant les envois d'ensembles sont effectuées sur GitHub. Par conséquent, tous les échecs d'envoi résultant de vérifications techniques seront visibles sur GitHub.

Règles pour les entreprises

Chrome propose deux règles pour répondre aux besoins des utilisateurs Enterprise :

• Les systèmes qui ne peuvent pas s'intégrer aux ensembles de sites Web associés peuvent désactiver cette fonctionnalité dans toutes les instances Enterprise de Chrome à l'aide de la règle RelatedWebsiteSetsEnabled.
  • Certains systèmes d'entreprise comportent des sites internes uniquement (comme un intranet) avec des domaines enregistrables qui diffèrent de ceux de leur ensemble de sites Web associés. S'ils doivent traiter ces sites comme faisant partie de leur ensemble de sites Web associés sans les exposer publiquement (car les domaines peuvent être confidentiels), ils peuvent compléter ou remplacer leur liste publique d'ensembles de sites Web associés avec la règle RelatedWebsiteSetsOverrides.

Chrome résout toute intersection des ensembles public et Enterprise de deux manières, selon que replacements ou additions sont spécifiés.

Par exemple, pour l'ensemble public {primary: A, associated: [B, C]} :

Résoudre les problèmes liés aux ensembles de sites Web associés

"Requête utilisateur" et "geste de l'utilisateur"

Une "invite utilisateur" et un "geste utilisateur" sont deux choses différentes. Chrome n'affiche pas d'invite d'autorisation pour les sites qui appartiennent au même ensemble de sites Web associés, mais exige toujours que l'utilisateur ait interagi avec la page. Avant d'accorder l'autorisation, Chrome exige un geste de l'utilisateur, également appelé "interaction de l'utilisateur" ou "activation par l'utilisateur". En effet, l'utilisation de l'API Storage Access en dehors d'un ensemble de sites Web associés (à savoir requestStorageAccess()) nécessite également un geste de l'utilisateur, en raison des principes de conception de la plate-forme Web.

Accéder aux cookies ou au stockage d'autres sites

Les ensembles de sites Web associés ne fusionnent pas le stockage pour différents sites. Ils permettent simplement des appels requestStorageAccess() plus faciles (sans invite). Les ensembles de sites Web associés ne font que réduire les frictions liées à l'utilisation de l'API Storage Access, mais ne dictent pas ce qu'il faut faire une fois l'accès rétabli. Si A et B sont des sites différents du même ensemble de sites Web associés, et que A intègre B, B peut appeler requestStorageAccess() et accéder au stockage first party sans inviter l'utilisateur. Les ensembles de sites Web associés n'effectuent aucune communication multisite. Par exemple, la configuration d'un ensemble de sites Web associés n'entraînera pas l'envoi des cookies appartenant à B à A. Si vous souhaitez partager ces données, vous devrez le faire vous-même, par exemple en envoyant un window.postMessage d'un iFrame B à un iFrame A.

Accès aux cookies non partitionnés par défaut

Les ensembles de sites Web associés n'autorisent pas l'accès implicite aux cookies non partitionnés sans appeler d'API. Les cookies multisites ne sont pas disponibles par défaut dans l'ensemble. Les ensembles de sites Web associés permettent simplement aux sites de l'ensemble de passer l'invite d'autorisation de l'API Storage Access. Un iFrame doit appeler document.requestStorageAccess() s'il souhaite accéder à ses cookies, ou la page de premier niveau peut appeler document.requestStorageAccessFor().

Envoyer des commentaires

En envoyant un ensemble sur GitHub et en utilisant l'API Storage Access et l'API requestStorageAccessFor, vous pouvez partager votre expérience avec le processus et les problèmes que vous rencontrez.

Pour participer aux discussions sur les ensembles de sites Web associés :

• Rejoignez la liste de diffusion publique des Ensembles de sites Web associés.
  • Signalez les problèmes et suivez la discussion sur le dépôt GitHub des ensembles de sites Web associés.