Guide du développeur sur les jetons d'état privés

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, beaucoup de ces cas d'utilisation devront être pris en charge par d'autres moyens.

Les jetons d'état privé permettent de partager des informations sur le Web, mais en préservant la confidentialité grâce à des contrôles sur la quantité de données pouvant réellement être partagées.

Les jetons d'état privés (anciennement appelés "Trust Tokens") permettent de transmettre la confiance en l'authenticité d'un utilisateur d'un contexte à un autre. Ils aident ainsi les sites à lutter contre la fraude et à distinguer les robots des humains, sans suivi passif.

Ce document décrit les détails techniques de l'implémentation des jetons d'état privés (PST). Pour obtenir un aperçu plus général, consultez la présentation de PST.

Comment fonctionnent les jetons d'état privés ?

Dans PST, la relation clé à comprendre est celle entre les émetteurs et les bénéficiaires. Les émetteurs et les bénéficiaires peuvent appartenir à la même entreprise.

• Émetteurs : ces entités disposent d'un signal concernant un utilisateur (par exemple, pour savoir si cet utilisateur est un robot ou non) et l'intègrent dans un jeton stocké sur l'appareil de l'utilisateur (plus de détails dans les sections suivantes).
• Bénéficiaires : ces entités peuvent ne pas disposer d'un signal concernant un utilisateur, mais ont besoin d'en savoir plus sur lui (par exemple, s'il s'agit d'un robot ou non). Elles demandent à échanger un jeton auprès de l'émetteur pour comprendre la fiabilité de cet utilisateur.

Chaque interaction PST nécessite que les émetteurs et les bénéficiaires collaborent pour partager des signaux sur le Web. Ces signaux sont des valeurs approximatives qui ne sont pas assez détaillées pour identifier des personnes.

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 différents contextes peuvent bénéficier des PST. Pour en savoir plus sur les cas d'utilisation potentiels des PST, consultez notre documentation sur les cas d'utilisation des PST.

Émettre et utiliser des jetons

L'implémentation du PST se déroule en trois phases :

1. Émission de jetons
2. Utiliser des jetons
3. Transfert des enregistrements d'utilisation

Lors de la première phase, des jetons sont émis pour un navigateur (généralement après une forme de validation). Dans la deuxième phase, une autre entité envoie une demande pour utiliser le jeton qui a été émis afin de lire la valeur de ce jeton. Lors de la phase finale, le bénéficiaire reçoit un enregistrement de l'échange (RR, Redemption Record) avec la valeur contenue dans le jeton. L'entité qui effectue l'échange peut ensuite utiliser cet enregistrement comme attestation de l'utilisateur à diverses fins.

Définir votre stratégie de jetons

Pour définir votre stratégie de jetons, vous devez comprendre les concepts clés de PST (jetons et enregistrements d'échange), les variables, les comportements et les limites afin de pouvoir réfléchir à leur utilisation potentielle pour votre cas d'utilisation.

Jetons et enregistrements des utilisations : quel est le lien entre eux ?

Chaque appareil peut stocker jusqu'à 500 jetons par site Web de premier niveau et émetteur. De plus, chaque jeton comporte 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'échange. 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 de l'utilisation (RR, Redemption Record) est stocké sur l'appareil. Ce stockage sert de cache pour les futurs échanges. Vous ne pouvez utiliser que deux jetons toutes les 48 heures, par appareil, page et émetteur. Les nouveaux appels de validation utiliseront des RR mis en cache dans la mesure du possible, au lieu d'envoyer une requête à l'émetteur.

1. De nouveaux jetons sont émis (500 maximum par émetteur, site et appareil).
2. Tous les jetons sont stockés dans le magasin de jetons de l'appareil (semblable à un magasin de cookies).
3. Si aucun RR actif n'est trouvé, de nouveaux RR peuvent être générés après l'émission (deux maximum toutes les 48 heures).
4. Les RR sont considérés comme actifs jusqu'à leur expiration et seront utilisés comme cache local.
5. Les nouveaux appels à l'échange toucheront le cache local (aucune nouvelle RR ne sera générée).

Après avoir défini votre cas d'utilisation, vous devez définir avec soin la durée de vie de vos RR, car cela déterminera le nombre de fois que vous pourrez les utiliser dans votre cas.

Avant de définir votre stratégie, assurez-vous de bien comprendre les comportements et les variables critiques suivants :

Exemples de cas de figure

Scénario 1 : La durée de vie de la récompense et de la remise est inférieure à 24 heures (t=t) et l'utilisateur l'utilise plusieurs fois au cours de la période de 48 heures.

Scénario 2 : La durée de vie de la récompense instantanée est de 24 heures et elle est utilisée plusieurs fois au cours de la période de 48 heures.

Scénario 3 : La durée de vie de la récompense et de la remise est de 48 heures, et l'utilisateur l'utilise plusieurs fois pendant cette période.

Exécuter la démo

Avant d'adopter PST, nous vous recommandons de configurer la démonstration.

En exécutant cette démo, votre navigateur utilise les serveurs de l'émetteur et du destinataire de la démo pour fournir et consommer des jetons.

Considérations techniques

Pour que la démo fonctionne de manière optimale, suivez les étapes suivantes :

• Assurez-vous d'arrêter toutes les instances de Chrome avant d'exécuter Chrome avec des flags.
• Si vous utilisez une machine Windows, consultez ce guide pour savoir comment transmettre des paramètres au fichier exécutable binaire Chrome.
• Ouvrez les outils de développement Chrome sous Applications > Stockage > Jetons d'état privé lorsque vous utilisez l'application de démonstration pour afficher les jetons émis ou utilisés par l'émetteur de démonstration.

Configurer pour l'adoption

Cette section explique les conditions à remplir pour devenir émetteur ou bénéficiaire de PST.

Devenir un é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 les jetons d'état privés en tant qu'émetteur, vous devez vous enregistrer en suivant la procédure d'enregistrement des émetteurs.

Pour demander à devenir un émetteur, l'opérateur du site Web de l'émetteur doit ouvrir un nouveau problème dans le dépôt GitHub à l'aide du modèle "New PST Issuer" (Nouvel émetteur PST). Suivez les instructions du dépôt pour remplir 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 à récupérer ces clés.

Serveurs de l'émetteur

Les émetteurs et les bénéficiaires sont les acteurs clés des PST. Les serveurs et les jetons sont les outils clés des PST. Nous avons déjà fourni des informations sur les jetons et dans la documentation GitHub, mais nous voulions vous en dire plus sur les serveurs PST. Pour configurer un serveur d'émission de PST, vous devez d'abord configurer un serveur d'émission.

Déployer votre environnement : serveurs émetteurs

Pour implémenter le serveur émetteur de jetons, vous devrez créer votre propre application côté serveur exposant 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 Web, nous vous recommandons d'ajouter une couche de protection supplémentaire à votre serveur émetteur.

1. Serveur émetteur : dans notre exemple d'implémentation, notre serveur é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 des exemples de code sur GitHub.

2. É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 un exemple d'implémentation en C, qui utilise la bibliothèque BoringSSL pour gérer les jetons. Vous trouverez l'exemple de code de l'émetteur et plus d'informations sur l'installation sur GitHub.

3. Clés : le composant é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 de l'émetteur

Conformément au protocole, vous devrez implémenter au moins deux points de terminaison HTTP sur votre serveur émetteur :

• Engagement de clé (par exemple, /.well-known/private-state-token/key-commitment) : ce point de terminaison permet aux navigateurs d'accéder aux informations sur votre clé publique de chiffrement pour confirmer que votre serveur est légitime.
  • Exemple de code sur GitHub
  • Voir la démonstration
• Émission de jetons (par exemple, /.well-known/private-state-token/issuance) : point de terminaison d'émission de jetons où toutes les demandes de jetons seront traitées. Ce point de terminaison sera le point d'intégration du composant émetteur de jetons.
  • Exemple de code sur GitHub
  • Voir la démonstration

Comme mentionné précédemment, en raison du trafic élevé attendu que ce serveur est susceptible de gérer, nous vous recommandons de le déployer à l'aide d'une infrastructure évolutive (par exemple, dans un environnement cloud) pour 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 dans votre pile d'émetteur pour émettre de nouveaux jetons.

 // issuer request
    await fetch("/.well-known/private-state-token/issuance", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request"
      }
    });

Consultez un exemple de code.

Serveurs de rachat

Vous devrez implémenter le service d'échange de jetons en créant votre propre application côté serveur. Cela vous permettra de lire les jetons qu'un émetteur envoie. Les étapes suivantes expliquent comment utiliser des jetons et comment 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 de validation

Conformément au protocole, vous devrez implémenter au moins deux points de terminaison HTTP pour votre serveur de validation :

• /.well-known/private-state-token/redemption : point de terminaison où toutes les utilisations de jetons seront traitées. Ce point de terminaison correspond à l'emplacement où le composant d'échange de jetons sera intégré.
  • Exemple de code sur GitHub
  • Démo

Envoyer un appel au serveur de validation

Pour échanger des jetons, vous devrez implémenter un appel d'extraction de site Web dans votre pile d'échange afin d'échanger 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 un exemple de code.

Après avoir utilisé un jeton, vous pouvez envoyer l'enregistrement de l'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 un 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 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. Ensuite, accédez à la page Web où l'appel de validation est effectué et vérifiez que les RR sont créés, en suivant votre logique.

Déploiement dans le monde 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) : commencez par déployer l'API auprès d'une petite audience.
• Vous en êtes propriétaire et vous le contrôlez : si nécessaire, vous pouvez désactiver rapidement l'implémentation sans avoir à obtenir d'approbations complexes.
• Pas plus d'un émetteur : pour limiter le nombre de jetons afin de simplifier les tests.
• Pas plus de deux bénéficiaires : 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 premier niveau et toutes les sous-ressources qui l'utilisent.

L'opération de demande 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 pour 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 d'origine croisée sans délégation explicite.

Vous pouvez désactiver l'émission ou l'échange 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 des tiers aux PST. En tant que paramètres de la liste des origines d'en-tête, utilisez self et toutes les origines auxquelles vous souhaitez autoriser l'accès à l'API. Par exemple, pour désactiver complètement l'utilisation de 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 d'origines croisées, définissez la liste des origines sur *.

Découvrez comment contrôler les fonctionnalités de la Privacy Sandbox avec la règle relative aux autorisations ou apprenez-en plus sur la règle relative aux autorisations.

Dépannage

Vous pouvez inspecter les PST depuis les onglets "Réseau" et "Application" des outils pour les développeurs Chrome.

Dans l'onglet "Réseau" :

Dans l'onglet "Application" :

En savoir plus sur cette intégration des outils de développement

Bonnes pratiques concernant les clients

Si les fonctions essentielles de votre site Web dépendent de certains émetteurs de jetons, accordez-leur la priorité. Appelez hasPrivateToken(issuer) pour ces émetteurs privilégiés avant de charger d'autres scripts. Cette étape est essentielle pour éviter d'éventuels échecs d'é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. Sécurisez donc vos émetteurs essentiels à l'avance 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 émetteur et votre serveur de bénéficiaire fonctionnent efficacement, nous vous recommandons d'appliquer les bonnes pratiques suivantes afin de ne pas rencontrer de problèmes d'accès, de sécurité, de journalisation ou de trafic pour PST.

• Vos points de terminaison doivent appliquer un chiffrement renforcé en utilisant TLS 1.3 ou 1.2.
• Votre infrastructure doit être en mesure de 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, conformément à votre stratégie de gestion des clés, à votre règlement sur le contrôle des accès et à vos plans de continuité d'activité.
• Ajoutez des métriques d'observabilité à votre pile pour vous assurer d'avoir une visibilité sur l'utilisation, les goulots d'étranglement et les problèmes de performances après le passage en production.

En savoir plus

1. Consultez la documentation pour les développeurs :
   1. Commencez par lire la présentation pour vous familiariser avec PST et ses fonctionnalités.
   2. Regardez la vidéo de présentation de PST.
   3. Essayez la démonstration de PST.
   4. Consultez également l'explication de l'API pour en savoir plus.
   5. En savoir plus sur la spécification actuelle de l'API
2. Participez à la conversation à l'aide des problèmes GitHub ou des appels W3C.
3. Pour mieux comprendre la terminologie, consultez le glossaire Privacy Sandbox.
4. Pour en savoir plus sur les concepts Chrome, tels que les phases d'évaluation d'origine ou les indicateurs Chrome, consultez les courtes vidéos et les articles disponibles sur goo.gle/cc.