Entwicklerleitfaden für Private State Tokens

In der Vergangenheit wurden Drittanbieter-Cookies verwendet, um Informationen zum Status eines Nutzers zu speichern und zu übertragen, z. B. seinen Anmeldestatus, Informationen zum verwendeten Gerät oder ob er bekannt und vertrauenswürdig ist. Das kann beispielsweise davon abhängen, ob sich der Nutzer mit SSO angemeldet hat, ob er ein bestimmtes kompatibles Gerät verwendet oder ob er bekannt und vertrauenswürdig ist. Da Drittanbieter-Cookies eingestellt werden, müssen viele dieser Anwendungsfälle auf andere Weise unterstützt werden.

Private State Tokens bieten eine Möglichkeit, Informationen im Web zu teilen, aber auf datenschutzfreundliche Weise durch Kontrollen der Menge an Daten, die tatsächlich geteilt werden können.

Private State Tokens (früher als Trust Tokens bezeichnet) ermöglichen es, das Vertrauen in die Authentizität eines Nutzers von einem Kontext zum nächsten zu übertragen. So können Websites Betrugsversuche besser bekämpfen und Bots von echten Menschen unterscheiden – ohne passives Tracking.

In diesem Dokument werden die technischen Details für die Implementierung von Private State Tokens (PST) beschrieben. Eine allgemeine Übersicht finden Sie unter PST – Übersicht.

Wie funktionieren Private State Tokens?

Die wichtigste Beziehung, die Sie in PST verstehen müssen, ist die zwischen Ausstellern und Einlösern. Aussteller und Einlöser können dasselbe Unternehmen sein.

• Aussteller: Diese Einheiten haben ein Signal zu einem Nutzer (z. B. ob der Nutzer ein Bot ist oder nicht) und betten dieses Signal in ein Token ein, das auf dem Gerät des Nutzers gespeichert wird (weitere Informationen in den nächsten Abschnitten).
• Einlöser: Diese Entitäten haben möglicherweise kein Signal zu einem Nutzer, müssen aber etwas über ihn wissen (z. B. ob es sich um einen Bot handelt) und bitten den Aussteller, ein Token einzulösen, um die Vertrauenswürdigkeit des Nutzers zu ermitteln.

Für jede PST-Interaktion müssen Aussteller und Einlöser zusammenarbeiten, um Signale im Web zu teilen. Diese Signale sind grobe Werte, die nicht detailliert genug sind, um Einzelpersonen zu identifizieren.

Sind Private State Tokens das Richtige für mich?

Unternehmen, die Vertrauensentscheidungen treffen und möchten, dass diese Informationen kontextübergreifend verfügbar sind, können von PSTs profitieren. Weitere Informationen zu möglichen Anwendungsfällen von PSTs

Tokens ausstellen und einlösen

Die Implementierung von PST erfolgt in drei Phasen:

1. Tokens ausstellen
2. Tokens einlösen
3. Weiterleitung von Einlösungsdatensätzen

In der ersten Phase werden Tokens an einen Browser ausgegeben (in der Regel nach einer Art von Validierung). In der zweiten Phase wird von einer anderen Einheit eine Anfrage zum Einlösen des Tokens gestellt, das zum Lesen des Werts in diesem Token ausgestellt wurde. In der letzten Phase erhält der Einlösende einen Einlösungsdatensatz (Redemption Record, RR) mit dem Wert, der im Token enthalten war. Die einlösende Partei kann diesen Datensatz dann für verschiedene Zwecke als Bestätigung für diesen Nutzer verwenden.

Tokenstrategie festlegen

Um Ihre Tokenstrategie zu definieren, müssen Sie die wichtigsten Konzepte von PST (Tokens und Einlösungsdatensätze), Variablen, Verhaltensweisen und Einschränkungen kennen, damit Sie überlegen können, wie sie für Ihren Anwendungsfall eingesetzt werden können.

Tokens und Einlösungsdatensätze: Wie hängen sie zusammen?

Auf jedem Gerät können bis zu 500 Tokens pro Website der obersten Ebene und Aussteller gespeichert werden. Außerdem enthält jedes Token Metadaten, die darüber informieren, welcher Schlüssel vom Aussteller verwendet wurde. Anhand dieser Informationen kann entschieden werden, ob ein Token während des Einlösens eingelöst werden soll. PST-Daten werden intern vom Browser auf dem Gerät des Nutzers gespeichert und können nur über die PST API aufgerufen werden.

Wenn ein Token eingelöst wird, wird der Einlösungsdatensatz (Redemption Record, RR) auf dem Gerät gespeichert. Dieser Speicher dient als Cache für zukünftige Einlösungen. Pro Gerät, Seite und Aussteller können alle 48 Stunden nur zwei Gutscheine eingelöst werden. Bei neuen Einlösungsaufrufen werden nach Möglichkeit im Cache gespeicherte RRs verwendet, anstatt eine Anfrage an den Aussteller zu senden.

1. Es werden neue Tokens ausgestellt (maximal 500 pro Aussteller, Website und Gerät).
2. Alle Tokens werden im On-Device-Tokenspeicher (ähnlich wie im Cookie-Speicher) gespeichert.
3. Wenn kein aktiver RR gefunden wird, können nach der Ausstellung neue RRs generiert werden (maximal 2 alle 48 Stunden).
4. RRs gelten bis zum Ablauf als aktiv und werden als lokaler Cache verwendet.
5. Neue Einlösungsaufrufe werden im lokalen Cache gespeichert (es werden keine neuen RRs generiert).

Nachdem Sie Ihren Anwendungsfall definiert haben, müssen Sie die Lebensdauer Ihrer RR sorgfältig festlegen, da dies bestimmt, wie oft Sie sie in Ihrem Fall verwenden können.

Bevor Sie Ihre Strategie festlegen, sollten Sie die folgenden wichtigen Verhaltensweisen und Variablen kennen:

Beispielszenarien

Szenario 1: Die Lebensdauer des RR beträgt weniger als 24 Stunden (t=t) und die Einlösung erfolgt mehrmals innerhalb des 48-Stunden-Zeitraums.

Szenario 2: Die Lebensdauer der Reichweite und Häufigkeit beträgt 24 Stunden und die Einlösung erfolgt mehrmals innerhalb des 48-Stunden-Zeitraums.

Szenario 3: Die Lebensdauer des Angebots ist 48 Stunden und die Einlösung erfolgt mehrmals innerhalb von 48 Stunden.

Demo ausführen

Bevor Sie PST verwenden, empfehlen wir, die Demo einzurichten.

Wenn Sie diese Demo ausführen, verwendet Ihr Browser die Demo-Aussteller- und Einlöserserver, um Tokens bereitzustellen und zu nutzen.

Technische Aspekte

Die Demo funktioniert am besten, wenn Sie die folgenden Schritte ausführen:

• Beenden Sie alle Chrome-Instanzen, bevor Sie Chrome mit Flags ausführen.
• Wenn Sie Windows verwenden, finden Sie in dieser Anleitung Informationen dazu, wie Sie Parameter an die ausführbare Chrome-Datei übergeben.
• Öffnen Sie die Chrome-Entwicklertools unter Anwendungen > Speicher > Private State Tokens, während Sie die Demoanwendung verwenden, um die vom Demoaussteller ausgegebenen oder eingelösten Tokens zu sehen.

Einrichtung für die Einführung

In diesem Abschnitt werden die Voraussetzungen für die Ausstellung oder Einlösung von PSTs erläutert.

Aussteller werden

Aussteller spielen eine wichtige Rolle bei PST. Sie weisen den Tokens Werte zu, um festzustellen, ob ein Nutzer ein Bot ist oder nicht. Wenn Sie als Aussteller mit PST beginnen möchten, müssen Sie sich registrieren. Dazu müssen Sie die Ausstellerregistrierung abschließen.

Um sich als Aussteller zu bewerben, muss der Betreiber der Ausstellerwebsite ein neues Problem im GitHub-Repository mit der Vorlage „New PST Issuer“ (Neuer PST-Aussteller) erstellen. Folgen Sie der Anleitung im Repository, um das Problem zu beschreiben. Sobald ein Endpunkt bestätigt wurde, wird er in dieses Repository eingefügt und die serverseitige Chrome-Infrastruktur beginnt, diese Schlüssel abzurufen.

Ausstellerserver

Aussteller und Einlöser sind die wichtigsten Akteure für PST. Server und Tokens sind die wichtigsten Tools für PST. Wir haben bereits einige Details zu Tokens und in der GitHub-Dokumentation bereitgestellt, möchten aber noch weitere Informationen zu PST-Servern geben. Wenn Sie PST-Aussteller werden möchten, müssen Sie zuerst einen Ausstellerserver einrichten.

Umgebung bereitstellen: Ausstellerserver

Um den Tokenausstellerserver zu implementieren, müssen Sie eine eigene serverseitige Anwendung mit HTTP-Endpunkten erstellen.

Die Ausstellerkomponente besteht aus zwei Hauptmodulen: (1) dem Ausstellerserver und (2) dem Tokenaussteller.

Wie bei allen webbasierten Anwendungen empfehlen wir eine zusätzliche Schutzebene für Ihren Ausstellerserver.

1. Ausstellerserver: In unserer Beispielimplementierung ist unser Ausstellerserver ein Node.js-Server, auf dem die HTTP-Endpunkte des Ausstellers mit dem Express-Framework gehostet werden. Beispielcode auf GitHub

2. Tokenaussteller: Für die kryptografische Komponente des Ausstellers ist keine bestimmte Sprache erforderlich. Aufgrund der Leistungsanforderungen dieser Komponente stellen wir jedoch eine C-Implementierung als Beispiel zur Verfügung, in der die BoringSSL-Bibliothek zum Verwalten von Tokens verwendet wird. Beispielcode für Aussteller und weitere Informationen zur Installation auf GitHub

3. Schlüssel: Die Tokenausstellerkomponente verwendet benutzerdefinierte EC-Schlüssel zum Verschlüsseln von Tokens. Diese Schlüssel müssen geschützt und in einem sicheren Speicher aufbewahrt werden.

Technische Anforderungen an Ausstellerserver

Gemäß dem Protokoll müssen Sie mindestens zwei HTTP-Endpunkte auf Ihrem Ausstellerserver implementieren:

• Schlüssel-Commitment (z. B. /.well-known/private-state-token/key-commitment): An diesem Endpunkt sind die Details Ihres öffentlichen Verschlüsselungsschlüssels für Browser verfügbar, um zu bestätigen, dass Ihr Server legitim ist.
  • Codebeispiel auf GitHub
  • Demo ansehen
• Tokenausstellung (z. B. /.well-known/private-state-token/issuance): Der Endpunkt für die Tokenausstellung, an dem alle Tokenanfragen verarbeitet werden. Dieser Endpunkt ist der Integrationspunkt für die Tokenausstellerkomponente.
  • Codebeispiel auf GitHub
  • Demo ansehen

Wie bereits erwähnt, wird dieser Server voraussichtlich viel Traffic verarbeiten. Wir empfehlen daher, ihn mit einer skalierbaren Infrastruktur (z. B. in einer Cloud-Umgebung) bereitzustellen, damit Sie Ihr Backend an eine variable Nachfrage anpassen können.

Anruf an den Server des Ausstellers senden

Implementieren Sie einen Website-Abrufaufruf in Ihrem Aussteller-Stack, um neue Tokens auszugeben.

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

Codebeispiel ansehen

Einlösende Server

Sie müssen den Dienst zum Einlösen von Tokens implementieren, indem Sie eine eigene serverseitige Anwendung erstellen. So können Sie die vom Aussteller gesendeten Tokens lesen. In den folgenden Schritten wird beschrieben, wie Sie Tokens einlösen und die Einlösungsdatensätze lesen, die mit diesen Tokens verknüpft sind.

Sie können den Aussteller und den Einlöser auf demselben Server (oder derselben Gruppe von Servern) ausführen.

Technische Anforderungen für Einlösungs-Server

Gemäß dem Protokoll müssen Sie mindestens zwei HTTP-Endpunkte für Ihren Einlöseserver implementieren:

• /.well-known/private-state-token/redemption: Endpunkt, an dem die Einlösung aller Tokens erfolgt. An diesem Endpunkt wird die Komponente zur Einlösung von Tokens integriert.
  • Beispielcode auf GitHub
  • Demo

Anruf an den Einlösungsserver senden

Um Tokens einzulösen, müssen Sie einen Website-Abruf in Ihren Einlösungs-Stack implementieren, um zuvor ausgestellte Tokens einzulösen.

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

Codebeispiel

Nachdem Sie ein Token eingelöst haben, können Sie den Einlösungsdatensatz (Redemption Record, RR) mit einem weiteren Abruf senden:

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

Codebeispiel

Implementierung bereitstellen

Rufen Sie zum Testen der Implementierung zuerst die Webseite auf, auf der der Ausstellungsaufruf erfolgt, und prüfen Sie, ob die Tokens gemäß Ihrer Logik erstellt werden. Prüfen Sie in Ihrem Backend, ob die Aufrufe gemäß der Spezifikation erfolgt sind. Rufen Sie dann die Webseite auf, auf der der Einlösungsaufruf erfolgt, und prüfen Sie, ob die RRs gemäß Ihrer Logik erstellt wurden.

Bereitstellung in der Praxis

Wir empfehlen, Zielwebsites auszuwählen, die zu Ihrem spezifischen Anwendungsfall passen:

• Geringe Anzahl monatlicher Besuche (ca. <1 Million Besuche/Monat): Sie sollten die API zuerst für eine kleine Zielgruppe bereitstellen.
• Sie sind der Eigentümer und haben die Kontrolle: Bei Bedarf können Sie die Implementierung schnell und ohne komplexe Genehmigungen deaktivieren.
• Maximal ein Aussteller: Um die Anzahl der Tokens zu begrenzen und das Testen zu vereinfachen.
• Maximal zwei Einlöser: Sie müssen die Fehlerbehebung im Falle von Problemen vereinfachen.

Richtlinie für Berechtigungen

Damit die PST API richtig funktioniert, muss sie für die Seite der obersten Ebene und alle untergeordneten Ressourcen verfügbar sein, die die API verwenden.

Der Tokenanfragevorgang wird durch die private-state-token-issuance-Anweisung gesteuert. Die Vorgänge token-redemption und send-redemption-record werden durch die Anweisung private-state-token-redemption gesteuert. In Chrome 132 und höher ist die Zulassungsliste für diese Direktiven standardmäßig auf * (alle Ursprünge) festgelegt. Das bedeutet, dass die Funktion für die Seite der obersten Ebene, iFrames mit demselben Ursprung und ursprungsübergreifende iFrames ohne explizite Delegation verfügbar ist.

Sie können die Ausstellung oder Einlösung von PST-Tokens für bestimmte Seiten Ihrer Website deaktivieren, indem Sie private-state-token-issuance=() und private-state-token-redemption=() in den Permissions-Policy-Header für jede Seite einfügen.

Sie können auch den Permissions-Policy-Header verwenden, um den Zugriff von Drittanbietern auf PST zu steuern. Verwenden Sie self und alle Ursprünge, für die Sie den Zugriff auf die API zulassen möchten, als Parameter für die Header-Ursprungsliste. Wenn Sie beispielsweise die Verwendung von PST in allen Browserkontexten mit Ausnahme Ihres eigenen Ursprungs und https://example.com vollständig deaktivieren möchten, legen Sie die folgenden HTTP-Antwortheader fest:

Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")

Wenn Sie die API für alle ursprungsübergreifenden Ressourcen aktivieren möchten, legen Sie die Ursprungsliste auf * fest.

Informationen zum Steuern von Privacy Sandbox-Funktionen mit der Berechtigungsrichtlinie und weitere Informationen zur Berechtigungsrichtlinie

Fehlerbehebung

Sie können PSTs über die Tabs „Netzwerk“ und „Anwendung“ in den Chrome-Entwicklertools untersuchen.

Auf dem Tab „Network“ (Netzwerk):

Auf dem Tab „Anwendung“:

Weitere Informationen zur Integration der Entwicklertools

Best Practices für Kunden

Wenn die wichtigsten Funktionen Ihrer Website von bestimmten Token-Ausstellern abhängen, sollten Sie diese priorisieren. Rufen Sie hasPrivateToken(issuer) für diese bevorzugten Aussteller auf, bevor Sie andere Skripts laden. Das ist wichtig, um potenzielle Probleme beim Einlösen zu vermeiden.

Die Anzahl der Aussteller pro oberster Ebene ist auf zwei begrenzt. Drittanbieterskripts können auch versuchen, hasPrivateToken(issuer) aufzurufen, um ihre bevorzugten Aussteller zu priorisieren. Sichern Sie daher Ihre wichtigsten Aussteller im Voraus, damit Ihre Website wie erwartet funktioniert.

  // 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).

Best Practices für Server und Fehlerbehebung

Damit Ihr Aussteller- und Einlösungs-Server effektiv funktionieren, empfehlen wir, die folgenden Best Practices zu implementieren, um Zugriffs-, Sicherheits-, Protokollierungs- oder Traffic-Probleme für PST zu vermeiden.

• Für Ihre Endpunkte muss eine starke Verschlüsselung mit TLS 1.3 oder 1.2 verwendet werden.
• Ihre Infrastruktur muss in der Lage sein, variable Traffic-Volumen (einschließlich Spitzen) zu bewältigen.
• Achten Sie darauf, dass Ihre Schlüssel gemäß Ihrer Richtlinie zur Zugriffssteuerung, Ihrer Schlüsselverwaltungsstrategie und Ihren Plänen zur Geschäftskontinuität geschützt und sicher sind.
• Fügen Sie Ihrem Stack Observability-Messwerte hinzu, damit Sie nach der Produktionsumstellung Einblick in die Nutzung, Engpässe und Leistungsprobleme erhalten.

Weitere Informationen

1. Entwicklerdokumentation ansehen:
   1. Lesen Sie zuerst die Übersicht, um sich mit PST und seinen Funktionen vertraut zu machen.
   2. Video zur Einführung in PST
   3. PST-Demo ausprobieren
   4. Lesen Sie auch die API-Erklärung, um weitere Details zu erfahren.
   5. Weitere Informationen zur aktuellen Spezifikation der API
2. Sie können sich über GitHub-Probleme oder W3C-Anrufe an der Diskussion beteiligen.
3. Weitere Informationen zur Terminologie finden Sie im Privacy Sandbox-Glossar.
4. Weitere Informationen zu Chrome-Konzepten wie „Origin Trial“ oder „Chrome-Flags“ finden Sie in den kurzen Videos und Artikeln unter goo.gle/cc.