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

Des cookies tiers étaient auparavant utilisés pour stocker et transmettre des informations concernant l'état de l'utilisateur, comme sa connexion ou des informations sur l'appareil qu'ils utilisent, ou s'ils sont connus et dignes de confiance. Par exemple, si le l'utilisateur s'est connecté avec l'authentification unique (SSO), qu'il dispose ou non d'un certain type ou si l'utilisateur est connu et digne de confiance. Avec abandon de la compatibilité des cookies tiers, bon nombre de ces 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, protégeant 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 faire confiance de transmettre l'authenticité d'un contexte à un autre tout en aidant les sites luttez contre la fraude et distinguez les robots des humains, sans aucun suivi passif.

Ce document décrit les détails techniques de l'implémentation de l'état privé. Jetons (PST). Pour en savoir plus, consultez la Présentation de PST

<ph type="x-smartling-placeholder">
</ph> Parcours de formation pour PST.
Processus d'apprentissage de PST: ce processus comporte plusieurs étapes, dont la première comprend la compréhension de l'API et la définition de votre propre stratégie de jetons (autres activités liées au produit ou à l'activité). Ensuite, la phase technique consiste à implémenter la version de démonstration dans votre environnement local, puis à l'appliquer à un cas d'utilisation réel.

Fonctionnement des jetons d'état privés

La relation clé à comprendre dans PST est entre les émetteurs et les émetteurs. Les émetteurs et les émetteurs d'offres peuvent appartenir à la même entreprise.

  • Émetteurs : ces entités ont un signal sur un utilisateur (par (par exemple, que l'utilisateur soit un bot ou non) et intègre ce signal dans un qui est stocké sur l'appareil de l'utilisateur (plus de détails dans les sections suivantes).
  • Résolveurs : il est possible que ces entités n'aient pas de signal concernant un utilisateur, mais ont besoin d'en savoir plus sur eux (par exemple, s'il s'agit d'un robot ou non) et demander à obtenir un jeton de l'émetteur pour comprendre de la fiabilité de cet utilisateur.

Pour chaque interaction PST, les émetteurs et les utilisateurs doivent collaborer pour partager sur l'ensemble du Web. Ces signaux sont des valeurs approximatives qui ne sont pas détaillées. pour identifier des individus.

Les jetons d'état privés sont-ils adaptés à ma situation ?

Cas d&#39;utilisation des jetons d&#39;état privés

Les entreprises qui prennent des décisions de confiance et qui veulent que ces informations 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 de PST.

Émettre et utiliser des jetons

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

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

Au cours de la première phase, les jetons sont émis vers un navigateur (généralement après une sorte la validation). Lors de la seconde phase, une autre entité demande à récupérer le jeton émis pour lire la valeur de ce jeton. Lors de la finale la partie effectuant un achat reçoit un enregistrement d'utilisation de la valeur était contenu dans le jeton. Cette partie peut alors utiliser cet enregistrement l'attestation de cet utilisateur à diverses fins.

<ph type="x-smartling-placeholder">
</ph> Flux de base des jetons d&#39;état privés
Diagramme séquentiel: le schéma montre une utilisation basique de PST dans une situation réelle où deux sites Web souhaitent échanger des signaux concernant cette instance Chrome spécifique. Les deux sites Web effectuent les opérations d'émission et d'utilisation à des moments différents, et peuvent ainsi échanger un signal de confiance entre eux.

Définir votre stratégie de jetons

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

Jetons et enregistrements d'utilisation: quelle est la relation entre ces jetons et enregistrements d'utilisation ?

Chaque appareil peut stocker jusqu'à 500 jetons par site Web et émetteur de premier niveau. Par ailleurs, chaque jeton comporte des métadonnées indiquant la clé que l'émetteur a utilisée pour l'émettre. Cela les informations peuvent être utilisées pour décider d'utiliser ou non un jeton au cours de la procédure processus. Les données PST sont stockées en interne par le navigateur sur l'appareil de l'utilisateur et n'est accessible que par l'API PST.

Lorsqu'un jeton est utilisé, l'enregistrement d'utilisation est stocké sur l'appareil. Cet espace de stockage sert de cache aux futures utilisations. La limite est de deux d'utilisation des jetons toutes les 48 heures, par appareil, par page et par émetteur. Nouvelle utilisation utilisent les RR mis en cache dans la mesure du possible, au lieu de provoquer une requête de l'émetteur.

Relation entre PST et RR.
  1. De nouveaux jetons sont émis (500 maximum par émetteur, site et appareil).
  2. Tous les jetons sont stockés sur un magasin de jetons sur l'appareil (comme un magasin de cookies).
  3. Si aucun RR actif n'est identifié, 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 en tant que cache.
  5. Les nouveaux appels d'utilisation se feront dans le cache local (aucun nouvel appel d'utilisation 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 votre RR comme cela va définir le nombre de fois que vous pourrez les utiliser .

Assurez-vous de bien comprendre les comportements et variables critiques suivants avant définir votre stratégie:

Variable / Comportement Description Utilisation potentielle
Métadonnées de clé de jeton Chaque jeton peut être émis à l'aide d'une seule clé cryptographique dans PST, la limite est de six clés par émetteur. Une façon potentielle d'utiliser cette variable consiste à définir une plage de confiance à vos jetons en fonction de vos clés cryptographiques (par exemple, clé 1 = un niveau de confiance élevé, tandis que la clé 6 indique qu'il n'y a aucune confiance).
Date d'expiration du jeton La date d'expiration du jeton est identique à la date d'expiration de la clé. Les clés peuvent être alternées au moins tous les 60 jours et tous les jetons émis avec les clés non valides sont également considérées comme non valides.
Limite du taux d'utilisation des jetons Vous ne pouvez utiliser que deux jetons par appareil et par émetteur au maximum 48 heures. Cela dépend du nombre estimé d'utilisations requises par votre utilisation toutes les 48 heures.
Nombre maximal d'émetteurs par origine de niveau supérieur Le nombre maximal d'émetteurs par origine de niveau supérieur est actuellement de deux. Définissez précisément 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 500. Veillez à ce que le nombre de jetons soit inférieur à 500 par émetteur.

Assurez-vous de gérer les erreurs sur votre page Web lorsque vous tentez de résoudre de jetons.
Rotation des engagements de clés Chaque émetteur PST doit exposer un point de terminaison avec une clé des engagements pouvant être modifiés tous les 60 jours et une rotation plus rapide, que celle-ci sera ignorée. Si vos clés expirent dans moins de 60 jours, il est obligatoire de mettre à jour vos principaux engagements avant cette date afin d'éviter toute perturbation (voir les détails).
Durée de vie de l'enregistrement d'utilisation La durée de vie de RR peut être définie afin de déterminer une expiration la date de début. Les RR sont mis en cache pour éviter de nouveaux appels d'utilisation inutiles. à l'émetteur, il est important d'avoir des informations et les signaux d'utilisation. Puisqu'il existe une limite de taux d'utilisation de deux jetons toutes les 48 heures, il est important de définir la durée de vie de votre RR afin de pouvoir exécuter demandes d'utilisation ayant abouti au cours d'au moins cette période (RR) doit être définie en conséquence). Nous vous recommandons de définir durée de vie de quelques semaines.

Exemples de cas de figure

Scénario 1: La durée de vie d'une demande de remboursement est inférieure à 24 heures (t=t) et l'utilisation plusieurs fois au cours de cette période de 48 heures.

<ph type="x-smartling-placeholder">
</ph> Exemple de scénario 1 de PST: durée de vie limitée.
Dans ce scénario, il existe une fenêtre de 28 heures pendant laquelle l'utilisateur ne peut pas à utiliser de nouveaux jetons, et tous les RR auront expiré.

Scénario 2: la durée de vie des demandes d'inscription est de 24 heures et le remboursement est effectué au cours de cette période de 48 heures.

<ph type="x-smartling-placeholder">
</ph> Exemple de scénario 2 de PST: durée de vie de 24 heures.
Dans ce scénario, étant donné que la durée de vie de RR est de 24 heures, il est possible d'utiliser les cartes pendant 48 heures sans aucune limite.

Scénario 3: la durée de vie des demandes d'inscription est de 48 heures et le remboursement est effectué au cours de cette période de 48 heures.

<ph type="x-smartling-placeholder">
</ph> Exemple de scénario 3 de PST: durée de vie de 48 heures.
Dans ce scénario, étant donné que la durée de vie de RR est de 48 heures, il est possible d'utiliser l'offre pendant 48 heures sans aucune limite.

Lancer la démonstration

Avant d'adopter PST, nous vous recommandons de commencer par configurer la version de démonstration. Pour essayer la démo PST , vous devez exécuter Chrome avec des indicateurs pour activer l'émetteur de démonstration. des engagements de clés (suivez les instructions disponibles dans la vidéo de démonstration .

Écran de démonstration PST.

Si vous exécutez cette démonstration, votre navigateur utilisera l'émetteur et l'utilisateur de démonstration. serveurs pour fournir et consommer des jetons.

Considérations techniques

La démonstration fonctionnera mieux si vous suivez les étapes suivantes:

  • Veillez à arrêter toutes les instances de Chrome avant d'exécuter Chrome avec des indicateurs.
  • Si vous exécutez l'application sur un ordinateur Windows, dans ce guide pour savoir comment transmettre des paramètres au fichier binaire exécutable Chrome.
  • Ouvrez les outils pour les développeurs Chrome sous Applications > Stockage > État privé Jetons lors de l'utilisation de l'application de démonstration pour voir les jetons émis/utilisés par l'émetteur de démonstration.
Écran des outils pour les développeurs Chrome affichant PST.

Configurer pour l'adoption

Devenir émetteur

Les émetteurs jouent un rôle clé dans PST. Ils attribuent des valeurs aux jetons pour déterminer si un utilisateur est un robot ou non. Pour utiliser PST en tant qu'émetteur, vous devez devront s'inscrire en remplissant le Processus d'enregistrement de l'émetteur.

Pour demander à devenir émetteur, l'opérateur de son site Web doit ouvrir un nouveau issue sur le GitHub à l'aide de l'en-tête "Nouveau fichier Émetteur" modèle. Suivez les instructions du dépôt pour remplir le problème. Une fois un point de terminaison validé, il est fusionné avec ce dépôt et L'infrastructure Chrome côté serveur commence à récupérer ces clés.

Serveurs de l'émetteur

Les émetteurs et les émetteurs de la carte sont les acteurs clés de PST. les serveurs et les jetons pour PST. Nous avons déjà fourni des informations sur les jetons documentation GitHub, nous voulions vous donner plus de détails sur les serveurs PST. Pour vous inscrire en tant qu'émetteur de fichiers PST, vous devez disposer des éléments suivants : pour configurer d'abord un serveur émetteur.

Déployer votre environnement: serveurs d'émetteur

Pour implémenter le serveur d'émetteur de jetons, vous devez créer votre propre serveur côté serveur qui expose les points de terminaison HTTP.

Le composant émetteur est composé de deux modules principaux: (1) le serveur de l'émetteur et (2) l'émetteur du jeton.

Composants du serveur émetteur.

Comme pour toutes les applications Web, un niveau de protection supplémentaire à votre serveur d'émetteur.

  1. Serveur émetteur: dans notre exemple de mise en œuvre, le serveur émetteur est un Serveur Node.js qui utilise le framework Express pour héberger le Points de terminaison HTTP de l'émetteur. Vous pouvez consulter l'exemple de code sur GitHub.

  2. Émetteur de jetons: le composant cryptographique de l'émetteur ne nécessite un langage spécifique, mais en raison des exigences de performance de ce composant, nous fournissons l'exemple d'une implémentation C, qui utilise l'en-tête Boring SSL pour gérer les jetons. Vous trouverez l'exemple de code d'émission et plus d'informations sur l'installation sur GitHub

  3. 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 devrez 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): C'est sur ce point de terminaison que les navigateurs auront accès aux détails de votre clé publique de chiffrement pour qu'ils puissent les confirmer pour confirmer la légitimité du serveur.
  • Émission de jetons (par exemple, /.well-known/private-state-token/issuance): Point de terminaison de l'émission de jetons où toutes les requêtes de jetons seront traitées. Ce le point de terminaison est le point d'intégration du composant d'émetteur de jeton.

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

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

Voir un exemple de code

Serveurs de l'utilisateur ayant activé les notifications

Vous devrez implémenter le service d'utilisation des 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 l'exécuteur sur le même serveur (ou groupe de serveurs).

<ph type="x-smartling-placeholder">
</ph> Composants du serveur d&#39;abonnement.
Composants de démonstration PST: il s'agit des principaux composants du serveur d'échange. Serveur d'échange (application Node.js) et échange de jetons (composant cryptographique chargé de vérifier les signatures et les jetons au cours du processus d'utilisation).

Exigences techniques pour les serveurs d'offres

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

  • /.well-known/private-state-token/redemption: point de terminaison où tous l'utilisation des jetons sera traitée. Ce point de terminaison sera l'endroit où le jeton le composant d'échange est intégré <ph type="x-smartling-placeholder">

Envoyer un appel au serveur d'échange

Pour utiliser des jetons, vous devez implémenter un appel de récupération de site Web afin de votre pile pour utiliser les jetons émis auparavant.

    // 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 d'utilisation en procédant comme suit : 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 est effectué et vérifiez que le ou les jetons sont créés en suivant votre logique. Vérifiez dans votre backend que les appels ont été effectués conformément à la spécification. Ensuite, accédez à la page Web sur laquelle l'appel est effectué et confirmez que les RR sont créées, en suivant votre logique.

Déploiement réel

Nous vous recommandons de choisir des sites Web cibles qui font partie de votre utilisation cas:

  • Petit nombre de visites mensuelles (environ < 1 million de visites/mois): vous devez commencer par déployer l'API auprès d'une petite audience
  • Vous en êtes le propriétaire et vous pouvez le contrôler: si nécessaire, vous pouvez désactiver rapidement sans approbations complexes
  • Un seul émetteur: pour limiter le nombre de jetons afin de simplifier les tests.
  • Deux utilisateurs maximum: vous devez simplifier le dépannage dans en cas de problèmes.

Règles relatives aux 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 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. Par défaut, la liste d'autorisation de ces instructions est définie sur "self". Cela signifie que la fonctionnalité n'est disponible que pour la page de premier niveau (et les iFrames de même origine) et n'est pas disponible pour les iFrames multi-origines sans délégation explicite de la page.

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 des applications tierces à PST. En tant que paramètres de la liste des origines de l'en-tête, utilisez self et toutes les origines pour lesquelles 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")

Afin d'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 à l'aide des règles sur les autorisations ou approfondissez vos connaissances sur les Règles sur les autorisations.

Dépannage

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

Dans l'onglet "Réseau" :

<ph type="x-smartling-placeholder">
</ph> Inspection des outils de développement pour l&#39;onglet &quot;Réseau&quot;
Inspection des outils de développement pour PST: accédez à Réseau > Jetons d'état privés pour obtenir toutes les informations pertinentes sur les jetons et les émetteurs d'une page spécifique

Dans l'onglet "Application" :

<ph type="x-smartling-placeholder">
</ph> Inspection des outils de développement pour l&#39;onglet &quot;Application&quot;
Inspection des outils de développement pour PST: accédez à Application > Jetons d'état privés pour obtenir toutes les informations pertinentes sur les jetons et les émetteurs d'une page spécifique.

En savoir plus Intégration des outils de développement.

Bonnes pratiques concernant les clients

Si les fonctions critiques de votre site Web dépendent de certains émetteurs de jetons, donnez-leur la priorité. Appelez hasPrivateToken(issuer) pour ces émetteurs préférés avant de charger d'autres scripts. Cette étape est essentielle pour éviter les échecs d'utilisation potentiels.

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. Vous devez donc sécuriser en amont les émetteurs essentiels 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 concernant les serveurs et dépannage

Pour que l'émetteur et le serveur d'échanges fonctionnent efficacement, nous vous recommandons mettre en œuvre les bonnes pratiques suivantes pour éviter les problèmes les accès, la sécurité, la journalisation ou le trafic pour 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, sécurisées et alignées avec votre accès la politique de contrôle, la stratégie de gestion des clés et les plans de continuité des activités.
  • Ajoutez des métriques d'observabilité à votre pile de la visibilité pour comprendre l'utilisation, les goulots d'étranglement et les problèmes de performances à passer en production.

En savoir plus

  1. Consultez la documentation pour les développeurs: <ph type="x-smartling-placeholder">
      </ph>
    1. Commencez par lire les 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 PST.
    4. Lire également l'API explicer pour en savoir plus. plus de détails à son sujet.
    5. Pour en savoir plus sur la version spécification de l'API.
  2. Participer à la conversation via GitHub problèmes ou W3C les appels.
  3. Pour mieux comprendre la terminologie utilisée, consultez la Glossaire de la Privacy Sandbox
  4. Pour en savoir plus sur les concepts Chrome, comme la phase d'évaluation ou "Flags Chrome" (Indicateurs Chrome), consultez les courtes vidéos et les articles disponibles sur goo.gle/cc