Auparavant, les cookies tiers étaient utilisés pour stocker et transmettre des informations sur l'état d'un utilisateur, comme son état de connexion, des informations sur l'appareil qu'il utilise ou s'il est connu et fiable. Par exemple, si l'utilisateur s'est connecté avec le SSO, s'il dispose d'un certain type d'appareil compatible ou s'il est connu et fiable. Étant donné que la prise en charge des cookies tiers est abandonnée, de nombreux cas d'utilisation devront être pris en charge par d'autres moyens.
Les jetons d'état privés permettent de partager des informations sur le Web, mais de manière respectueuse de la confidentialité grâce à des contrôles sur la quantité de données pouvant être partagées.
Les jetons d'état privés (anciennement appelés jetons de confiance) permettent de transmettre la confiance en l'authenticité d'un utilisateur d'un contexte à un autre, tout en aidant les sites à lutter contre la fraude et à distinguer les robots des humains, sans suivi passif.
Ce document présente les détails techniques de l'implémentation des jetons d'état privé (PST). Pour obtenir une présentation plus générale, consultez la présentation du PST.
Comment fonctionnent les jetons d'état privés ?
La relation clé à comprendre dans le PST est celle entre les émetteurs et les utilisateurs. Les émetteurs et les utilisateurs peuvent appartenir à la même entreprise.
- Émetteurs : ces entités disposent d'un signal sur un utilisateur (par exemple, s'il s'agit d'un robot ou non) et intègrent ce signal dans un jeton stocké sur l'appareil de l'utilisateur (plus d'informations dans les sections suivantes).
- Utilisateurs : ces entités n'ont peut-être pas de signal sur un utilisateur, mais elles doivent en savoir quelque chose (par exemple, s'il s'agit d'un robot ou non) et demander à utiliser un jeton auprès de l'émetteur pour comprendre la fiabilité de cet utilisateur.
Chaque interaction avec un PST nécessite que les émetteurs et les utilisateurs se mettent d'accord pour partager des signaux sur le Web. Ces signaux sont des valeurs grossières qui ne sont pas suffisamment détaillées pour identifier des individus.
Les jetons d'état privés sont-ils adaptés à mes besoins ?
Les entreprises qui prennent des décisions de confiance et souhaitent que ces informations soient disponibles dans tous les contextes peuvent bénéficier des PST. Pour en savoir plus sur les cas d'utilisation potentiels des fichiers PST, consultez notre documentation sur les cas d'utilisation des fichiers PST.
Émettre et utiliser des jetons
L'implémentation du PST se déroule en trois phases:
- Émettre des jetons
- Utiliser des jetons
- Transfert des enregistrements d'offres
Dans la première phase, des jetons sont émis pour un navigateur (généralement après une validation). Dans la deuxième phase, une autre entité envoie une requête pour utiliser le jeton qui a été émis afin de lire la valeur de ce jeton. Dans la phase finale, le bénéficiaire reçoit un enregistrement de rachat (RR) avec la valeur contenue dans le jeton. Cette partie peut ensuite utiliser cet enregistrement comme attestation de cet utilisateur à diverses fins.
Définir votre stratégie de jetons
Pour définir votre stratégie de jeton, vous devez comprendre les concepts clés des PST (jetons et enregistrements de rachat), les variables, les comportements et les limites afin de pouvoir réfléchir à leur utilisation potentielle pour votre cas d'utilisation.
Jetons et enregistrements d'échange: quelle est la relation entre eux ?
Chaque appareil peut stocker jusqu'à 500 jetons par site Web de niveau supérieur et émetteur. De plus, chaque jeton contient des métadonnées indiquant la clé utilisée par l'émetteur pour l'émettre. Ces informations peuvent être utilisées pour décider d'utiliser ou non un jeton lors du processus d'utilisation. Les données PST sont stockées en interne par le navigateur sur l'appareil de l'utilisateur et ne sont accessibles que par l'API PST.
Lorsqu'un jeton est utilisé, l'enregistrement d'utilisation (RR) est stocké sur l'appareil. Ce stockage sert de cache pour les futures utilisations. Vous ne pouvez utiliser que deux jetons toutes les 48 heures, par appareil, par page et par émetteur. Dans la mesure du possible, les nouveaux appels de rachat utiliseront les RR mis en cache plutôt que d'envoyer une requête à l'émetteur.
- De nouveaux jetons sont émis (500 maximum par émetteur, site et appareil).
- Tous les jetons sont stockés dans un magasin de jetons sur l'appareil (comme un magasin de cookies).
- Si aucun RR actif n'est trouvé, de nouveaux RR peuvent être générés après l'émission (deux au maximum toutes les 48 heures).
- Les RR sont considérés comme actifs jusqu'à leur expiration et sont utilisés comme cache local.
- Les nouveaux appels de rachat seront enregistrés dans le cache local (aucun nouveau RR n'est généré).
Après avoir défini votre cas d'utilisation, vous devez définir soigneusement la durée de vie de vos RR, car cela déterminera le nombre de fois où vous pourrez les utiliser dans votre cas.
Avant de définir votre stratégie, assurez-vous de bien comprendre les comportements et variables critiques suivants:
| Variable / Comportement | Description | Utilisation potentielle |
|---|---|---|
| Métadonnées de la clé de jeton | Chaque jeton peut être émis à l'aide d'une seule et unique clé cryptographique. Dans PST, il est limité à six clés par émetteur. | Une façon d'utiliser cette variable consiste à définir une plage de confiance pour vos jetons en fonction de vos clés cryptographiques (par exemple, la clé 1 = confiance élevée, tandis que la clé 6 = aucune confiance). |
| Date d'expiration du jeton | La date d'expiration du jeton est identique à celle de la clé. | Les clés peuvent être alternées au moins tous les 60 jours, et tous les jetons émis avec des clés non valides sont également considérés comme non valides. |
| Limite de débit d'échange de jetons | Vous ne pouvez utiliser qu'un maximum de deux jetons par appareil et par émetteur toutes les 48 heures. | Dépend du nombre estimé de bons à utiliser requis par votre cas d'utilisation toutes les 48 heures. |
| Nombre maximal d'émetteurs par origine de niveau supérieur | Le nombre maximal d'émetteurs par origine de premier niveau est actuellement de deux. | Définissez soigneusement les émetteurs de chaque page. |
| Jetons par émetteur sur un appareil | Le nombre maximal de jetons par émetteur sur un appareil spécifique est actuellement de 500. | Veillez à limiter le nombre de jetons à 500 par émetteur. Assurez-vous de gérer les erreurs sur votre page Web lorsque vous essayez d'émettre des jetons. |
| Rotation des engagements de clé | Chaque émetteur de PST doit exposer un point de terminaison avec des engagements de clé pouvant être modifiés tous les 60 jours. Toute rotation plus rapide sera ignorée. | Si vos clés expirent dans moins de 60 jours, vous devez impérativement mettre à jour vos engagements de clé avant cette date pour éviter toute interruption (voir les détails). |
| Durée de vie des enregistrements d'utilisation | La durée de vie de la RR peut être définie afin de déterminer une date d'expiration. Étant donné que les RR sont mis en cache pour éviter les nouveaux appels de rachat inutiles à l'émetteur, il est important de s'assurer que les signaux de rachat sont suffisamment récents. | Étant donné qu'il existe une limite de deux jetons par 48 heures, il est important de définir la durée de vie de votre RR pour pouvoir exécuter des appels de rachat avec succès pendant au moins cette période (la durée de vie du RR doit être définie en conséquence). Nous vous recommandons de définir cette durée de vie sur plusieurs semaines. |
Exemples de cas de figure
Scénario 1: la durée de vie de la RR est inférieure à 24 heures (t=t) et l'utilisation est effectuée plusieurs fois au cours de la période de 48 heures.
Scénario 2: la durée de vie de la RR est de 24 heures et l'échange est effectué plusieurs fois au cours de la période de 48 heures.
Scénario 3: la durée de vie de la RR est de 48 heures et l'échange est effectué plusieurs fois au cours de cette période.
Exécuter la démo
Avant d'adopter PST, nous vous recommandons de commencer par configurer la version de démonstration. Pour essayer la démonstration PST , vous devez exécuter Chrome avec des indicateurs pour activer les engagements de clé d'émetteur de démonstration (suivez les instructions disponibles sur la page de démonstration).
En exécutant cette démonstration, votre navigateur utilise les serveurs d'émetteur et d'échangeur de la démonstration pour fournir et consommer des jetons.
Considérations techniques
Pour que la démonstration fonctionne correctement, procédez comme suit:
- Assurez-vous d'arrêter toutes les instances de Chrome avant d'exécuter Chrome avec des indicateurs.
- Si vous exécutez le programme sur une machine Windows, consultez ce guide pour savoir comment transmettre des paramètres au binaire exécutable Chrome.
- Ouvrez les outils pour les développeurs Chrome sous Applications > Stockage > Jetons d'état privé lorsque vous utilisez l'application de démonstration pour afficher les jetons émis/utilisés par l'émetteur de démonstration.
Configuration pour l'adoption
Devenir émetteur
Les émetteurs jouent un rôle clé dans le PST. Ils attribuent des valeurs aux jetons pour déterminer si un utilisateur est un robot ou non. Si vous souhaitez commencer à utiliser PST en tant qu'émetteur, vous devez vous inscrire en suivant la procédure d'enregistrement des émetteurs.
Pour demander à devenir émetteur, l'opérateur du site Web de l'émetteur doit ouvrir une nouvelle demande dans le dépôt GitHub à l'aide du modèle "Nouveau PST Émetteur". Suivez les instructions du dépôt pour décrire le problème. Une fois qu'un point de terminaison a été validé, il est fusionné dans ce dépôt et l'infrastructure côté serveur de Chrome commence à extraire ces clés.
Serveurs de l'émetteur
Les émetteurs et les utilisateurs sont les principaux acteurs du PST. Les serveurs et les jetons sont les principaux outils du PST. Nous avons déjà fourni quelques informations sur les jetons et dans la documentation GitHub, mais nous souhaitions en dire plus sur les serveurs PST. Pour être configuré en tant qu'émetteur de PST, vous devez d'abord configurer un serveur d'émission.
Déployer votre environnement: serveurs d'émetteur
Pour implémenter le serveur d'émetteur de jetons, vous devez créer votre propre application côté serveur qui expose des points de terminaison HTTP.
Le composant émetteur se compose de deux modules principaux: (1) le serveur de l'émetteur et (2) l'émetteur de jetons.
Comme pour toutes les applications exposées sur le Web, nous vous recommandons d'ajouter une couche de protection supplémentaire à votre serveur d'émetteur.
Serveur d'émetteur: dans notre exemple d'implémentation, notre serveur d'émetteur est un serveur Node.js qui utilise le framework Express pour héberger les points de terminaison HTTP de l'émetteur. Vous pouvez consulter un exemple de code sur GitHub.
Émetteur de jetons: le composant cryptographique de l'émetteur ne nécessite aucun langage spécifique, mais en raison des exigences de performances de ce composant, nous fournissons une implémentation en C à titre d'exemple, qui utilise la bibliothèque Boring SSL pour gérer les jetons. Vous trouverez l'exemple de code d'émetteur et plus d'informations sur l'installation sur GitHub.
Clés: le composant d'émetteur de jetons utilise des clés EC personnalisées pour chiffrer les jetons. Ces clés doivent être protégées et stockées dans un espace de stockage sécurisé.
Exigences techniques pour les serveurs d'émetteur
Conformément au protocole, vous devez implémenter au moins deux points de terminaison HTTP dans votre serveur d'émetteur:
- Engagement de clé (par exemple,
/.well-known/private-state-token/key-commitment) : les informations de votre clé publique de chiffrement seront disponibles sur ce point de terminaison pour les navigateurs afin de confirmer que votre serveur est légitime. - Émission de jetons (par exemple,
/.well-known/private-state-token/issuance) : point de terminaison d'émission de jetons où toutes les requêtes de jetons seront traitées. Ce point de terminaison sera le point d'intégration du composant d'émetteur de jetons.
Comme indiqué précédemment, en raison du trafic élevé attendu que ce serveur pourra potentiellement gérer, nous vous recommandons de le déployer à l'aide d'une infrastructure évolutive (par exemple, dans un environnement cloud) afin de pouvoir ajuster votre backend en fonction d'une demande variable.
Envoyer un appel au serveur de l'émetteur
Implémentez un appel de récupération de site Web à votre pile d'émetteur afin d'émettre de nouveaux jetons.
// issuer request
await fetch("/.well-known/private-state-token/issuance", {
method: "POST",
privateToken: {
version: 1,
operation: "token-request"
}
});
Serveurs de rachat
Vous devrez implémenter le service d'échange de jetons en créant votre propre application côté serveur. Vous pourrez ainsi lire les jetons qu'un émetteur envoie. Les étapes suivantes expliquent comment utiliser des jetons et lire les enregistrements d'utilisation associés à ces jetons.
Vous pouvez choisir d'exécuter l'émetteur et le bénéficiaire sur le même serveur (ou groupe de serveurs).
Exigences techniques pour les serveurs d'échange
Conformément au protocole, vous devez implémenter au moins deux points de terminaison HTTP pour votre serveur de rachat:
/.well-known/private-state-token/redemption: point de terminaison où toutes les utilisations de jetons seront gérées. C'est à ce point de terminaison que le composant de récupération de jetons sera intégré.
Envoyer un appel au serveur de l'émetteur
Pour utiliser des jetons, vous devez implémenter un appel de récupération de site Web dans votre pile de récupérateur afin d'utiliser les jetons émis précédemment.
// redemption request
await fetch("/.well-known/private-state-token/redemption", {
method: "POST",
privateToken: {
version: 1,
operation: "token-redemption",
refreshPolicy: "none"
}
});
Consultez l'exemple de code.
Une fois qu'un jeton a été utilisé, vous pouvez envoyer l'enregistrement d'utilisation (RR) en effectuant un autre appel de récupération:
// attach redemption records from the issuers to the request
await fetch("<DESTINATION_RESOURCE>", {
method: "POST",
privateToken: {
version: 1,
operation: "send-redemption-record",
issuers: [<ISSUER_DOMAIN>]
}
});
Consultez l'exemple de code.
Déployer votre implémentation
Pour tester votre implémentation, accédez d'abord à la page Web sur laquelle l'appel d'émission est effectué et vérifiez que le ou les jetons sont créés conformément à votre logique. Vérifiez dans votre backend que les appels ont été effectués conformément aux spécifications. Accédez ensuite à la page Web sur laquelle l'appel de rachat est effectué et vérifiez que les RR sont créés, en suivant votre logique.
Déploiement réel
Nous vous recommandons de choisir des sites Web cibles qui font partie de votre cas d'utilisation spécifique:
- Petit nombre de visites mensuelles (environ moins d'un million de visites par mois): vous devez commencer par déployer l'API auprès d'une petite audience.
- Vous en êtes le propriétaire et le contrôlez: si nécessaire, vous pouvez rapidement désactiver l'implémentation sans approbation complexe.
- Un seul émetteur: pour limiter le nombre de jetons afin de simplifier les tests.
- Deux utilisateurs maximum: vous devez simplifier le dépannage en cas de problème.
Règles sur les autorisations
Pour fonctionner correctement, l'API PST doit être disponible pour la page de niveau supérieur et toutes les sous-ressources qui l'utilisent.
L'opération de requête de jeton est contrôlée par la directive private-state-token-issuance. Les opérations token-redemption et send-redemption-record sont contrôlées par la directive private-state-token-redemption. Dans Chrome 132 et versions ultérieures, la liste d'autorisation de ces directives est définie sur * (toutes les origines) par défaut. Cela signifie que la fonctionnalité est disponible pour la page de premier niveau, les iFrames de même origine et les iFrames inter-origines sans délégation explicite.
Vous pouvez désactiver l'émission ou l'utilisation de jetons PST pour des pages spécifiques de votre site en incluant private-state-token-issuance=() et private-state-token-redemption=() dans l'en-tête Permissions-Policy de chaque page.
Vous pouvez également utiliser l'en-tête Permissions-Policy pour contrôler l'accès tiers aux fichiers PST. Utilisez self et toutes les origines auxquelles vous souhaitez autoriser l'accès à l'API comme paramètres de la liste des origines de l'en-tête. Par exemple, pour désactiver complètement l'utilisation du fuseau horaire PST dans tous les contextes de navigation, à l'exception de votre propre origine et de https://example.com, définissez les en-têtes de réponse HTTP suivants:
Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")
Pour activer l'API pour toutes les ressources multi-origines, définissez la liste des origines sur *.
Découvrez comment contrôler les fonctionnalités de la Privacy Sandbox avec la stratégie d'autorisations ou approfondissez vos connaissances sur la stratégie d'autorisations.
Dépannage
Vous pouvez inspecter les fichiers PST dans les onglets "Réseau" et "Application" de Chrome DevTools.
Dans l'onglet "Network" (Réseau) :
Dans l'onglet "Application" :
En savoir plus sur cette intégration aux outils pour les développeurs
Bonnes pratiques concernant les clients
Si les fonctions essentielles de votre site Web dépendent de certains émetteurs de jetons, priorisez-les. Appelez hasPrivateToken(issuer) pour ces émetteurs privilégiés avant de charger d'autres scripts. Cette étape est cruciale pour éviter les échecs potentiels de l'échange.
Le nombre d'émetteurs par niveau supérieur est limité à deux. Les scripts tiers peuvent également essayer d'appeler hasPrivateToken(issuer) pour donner la priorité à leurs propres émetteurs préférés. Protégez donc vos émetteurs essentiels dès le départ pour vous assurer que votre site fonctionne comme prévu.
// Prioritize your critical token issuer.
document.hasPrivateToken('https://critical-issuer.example')
.then(hasToken => {
if (hasToken) {
// Use the token or perform actions based on its availability.
} else {
// Handle the case where the token is not available.
}
});
// Load third-party scripts or secure another token issuer (up to two in total).
Bonnes pratiques et dépannage pour les serveurs
Pour que votre serveur d'émetteur et de rachat fonctionne efficacement, nous vous recommandons d'appliquer les bonnes pratiques suivantes afin de vous assurer que vous ne rencontrez aucun problème d'accès, de sécurité, de journalisation ou de trafic pour le PST.
- Vos points de terminaison doivent appliquer une cryptographie renforcée à l'aide de TLS 1.3 ou 1.2.
- Votre infrastructure doit être prête à gérer des volumes de trafic variables (y compris les pics).
- Assurez-vous que vos clés sont protégées et sécurisées, et qu'elles sont conformes à votre stratégie de gestion des clés, à votre stratégie de gestion des clés et à vos plans de continuité d'activité.
- Ajoutez des métriques d'observabilité à votre pile pour vous assurer d'avoir une visibilité suffisante pour comprendre l'utilisation, les goulots d'étranglement et les problèmes de performances après le passage en production.
En savoir plus
- Consultez la documentation destinée aux développeurs :
- Commencez par lire la présentation pour vous familiariser avec le PST et ses fonctionnalités.
- Regardez la vidéo de présentation du PST.
- Essayez la démo du PST.
- Consultez également la présentation de l'API pour en savoir plus.
- En savoir plus sur la spécification actuelle de l'API
- Participez à la conversation via des problèmes GitHub ou des appels au W3C.
- Pour mieux comprendre la terminologie, consultez le glossaire de la Privacy Sandbox.
- Pour en savoir plus sur les concepts Chrome, tels que les "phases d'évaluation d'origine" ou les "options Chrome", regardez les courtes vidéos et consultez les articles disponibles sur goo.gle/cc.