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. Beispielsweise, ob sich der Nutzer mit der Einmalanmeldung 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 eine datenschutzfreundliche Weise, da die Menge der Daten, die tatsächlich weitergegeben werden können, kontrolliert wird.

Private State Tokens (früher Trust Tokens) ermöglichen es, das Vertrauen in die Authentizität eines Nutzers von einem Kontext zum nächsten zu übertragen. Außerdem helfen sie Websites, Betrug zu bekämpfen und Bots von echten Menschen zu unterscheiden – ohne passives Tracking.

In diesem Dokument werden die technischen Details zur Implementierung von Private State Tokens (PST) beschrieben. Eine allgemeine Übersicht finden Sie im Hilfeartikel PST-Dateien.

Wie funktionieren Private State Tokens?

Die wichtigste Beziehung in PST ist die zwischen Ausstellern und Einlösern. Aussteller und Einlöser können zum selben Unternehmen gehören.

• Aussteller: Diese Entitäten haben ein Signal zu einem Nutzer (z. B. ob es sich um einen Bot handelt oder nicht) und fügen dieses Signal in ein Token ein, das auf dem Gerät des Nutzers gespeichert wird. Weitere Informationen finden Sie in den nächsten Abschnitten.
• Einlöser: Diese Entitäten haben möglicherweise keine Informationen zu einem Nutzer, benötigen aber Informationen zu ihm (z. B. ob es sich um einen Bot handelt oder nicht) und bitten den Aussteller, ein Token einzulösen, um die Vertrauenswürdigkeit dieses Nutzers zu ermitteln.

Bei jeder PST-Interaktion müssen Aussteller und Einlöser zusammenarbeiten, um Signale im Web auszutauschen. Diese Signale sind grobe Werte, die nicht detailliert genug sind, um Personen zu identifizieren.

Sind Private State Tokens für mich geeignet?

Unternehmen, die Vertrauensentscheidungen treffen und möchten, dass diese Informationen in verschiedenen Kontexten verfügbar sind, können von PSTs profitieren. Weitere Informationen zu potenziellen Anwendungsfällen von PST-Dateien finden Sie in unserer Dokumentation zu PST-Anwendungsfällen.

Tokens ausstellen und einlösen

Die PST-Implementierung erfolgt in drei Phasen:

1. Tokens ausstellen
2. Tokens einlösen
3. Weiterleitung von Einlösungseinträgen

In der ersten Phase werden Tokens für einen Browser ausgestellt (in der Regel nach einer Art Validierung). In der zweiten Phase stellt eine andere Entität eine Anfrage, um das Token einzulösen, das zum Lesen des Werts in diesem Token ausgestellt wurde. In der letzten Phase erhält die Person, die das Guthaben einlöst, einen Gutscheincode mit dem im Token enthaltenen Wert. Diese Person kann diesen Eintrag dann für verschiedene Zwecke als Bestätigung für diesen Nutzer verwenden.

Tokenstrategie definieren

Um Ihre Tokenstrategie zu definieren, müssen Sie die wichtigsten Konzepte von PST (Tokens und Gutscheincodes), Variablen, Verhaltensweisen und Einschränkungen kennen, um ihre potenzielle Verwendung für Ihren Anwendungsfall zu überdenken.

Welche Beziehung besteht zwischen Tokens und Gutscheincodes?

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, aus denen hervorgeht, mit welchem Schlüssel der Aussteller es ausgestellt hat. Anhand dieser Informationen kann beim Einlösen eines Tokens entschieden werden, ob es eingelöst werden soll oder nicht. PST-Daten werden vom Browser intern auf dem Gerät des Nutzers gespeichert und können nur über die PST API abgerufen werden.

Wenn ein Token eingelöst wird, wird der Gutscheincode (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 zwei Tokens eingelöst werden. Bei neuen Aufrufen zur Gutscheineinlösung werden nach Möglichkeit im Cache gespeicherte RRs verwendet, anstatt eine Anfrage an den Aussteller zu senden.

1. Es werden neue Tokens ausgegeben (max. 500 pro Aussteller, Website und Gerät).
2. Alle Tokens werden im On-Device-Token-Speicher gespeichert (ähnlich wie ein Cookie-Speicher).
3. Wenn kein aktiver RR gefunden wird, können nach der Ausstellung neue RRs generiert werden (maximal zwei alle 48 Stunden).
4. RRs gelten bis zum Ablauf als aktiv und werden als lokaler Cache verwendet.
5. Neue Aufrufe zur Gutscheineinlösung werden im lokalen Cache abgerufen (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 definieren, sollten Sie die folgenden wichtigen Verhaltensweisen und Variablen kennen:

Variable / Verhalten	Beschreibung	Potenzielle Nutzung
Metadaten für Tokenschlüssel	Jedes Token kann mit genau einem kryptografischen Schlüssel ausgestellt werden. In PST ist die Anzahl der Schlüssel pro Aussteller auf sechs begrenzt.	Eine mögliche Verwendung dieser Variablen besteht darin, anhand Ihrer kryptografischen Schlüssel einen Vertrauensbereich für Ihre Tokens zu definieren (z. B. Schlüssel 1 = hohes Vertrauen, Schlüssel 6 = kein Vertrauen).
Ablaufdatum des Tokens	Das Ablaufdatum des Tokens entspricht dem Ablaufdatum des Schlüssels.	Schlüssel können mindestens alle 60 Tage rotiert werden. Alle mit ungültigen Schlüsseln ausgestellten Tokens gelten ebenfalls als ungültig.
Begrenzung der Tokeneinlösungsrate	Pro Gerät und Aussteller können alle 48 Stunden maximal zwei Tokens eingelöst werden.	Abhängig von der geschätzten Anzahl der Einlösungen, die für Ihren Anwendungsfall alle 48 Stunden erforderlich sind.
Maximale Anzahl Aussteller pro Ursprung der obersten Ebene	Die maximale Anzahl von Ausstellern pro Ursprung der obersten Ebene beträgt derzeit zwei.	Definieren Sie die Aussteller der einzelnen Seiten sorgfältig.
Tokens pro Aussteller auf einem Gerät	Die maximale Anzahl von Tokens pro Aussteller auf einem bestimmten Gerät beträgt derzeit 500.	Die Anzahl der Tokens darf pro Aussteller nicht mehr als 500 betragen. Achten Sie darauf, Fehler auf Ihrer Website zu behandeln, wenn Sie versuchen, Tokens auszustellen.
Schlüsselbindungen tauschen	Jeder PST-Aussteller muss einen Endpunkt mit wichtigen Zusagen bereitstellen, die alle 60 Tage geändert werden können. Eine schnellere Rotation wird ignoriert.	Wenn Ihre Schlüssel in weniger als 60 Tagen ablaufen, müssen Sie Ihre Schlüsselverpflichtungen vor diesem Datum aktualisieren, um Unterbrechungen zu vermeiden (Details).
Lebensdauer des Einlösungseintrags	Die Lebensdauer von RR kann definiert werden, um ein Ablaufdatum zu bestimmen. Da RRs im Cache gespeichert werden, um unnötige neue Aufrufe zur Gutscheineinlösung an den Aussteller zu vermeiden, ist es wichtig, dass die Einlösungssignale aktuell sind.	Da die Abfolge von Gutscheincodes auf zwei Gutscheincodes alle 48 Stunden begrenzt ist, ist es wichtig, die Gültigkeitsdauer des Gutscheincodes so zu definieren, dass Gutscheincode-Aufrufe mindestens in diesem Zeitraum erfolgreich ausgeführt werden können. Die Gültigkeitsdauer des Gutscheincodes sollte entsprechend festgelegt werden. Wir empfehlen, diese Lebensdauer auf einige Wochen festzulegen.

Beispielszenarien

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

Szenario 2: Die Gültigkeitsdauer des Gutscheincodes beträgt 24 Stunden und die Einlösung erfolgt mehrmals innerhalb des 48-Stunden-Zeitraums.

Szenario 3: Die Gültigkeitsdauer des Gutscheincodes beträgt 48 Stunden und die Einlösung erfolgt mehrmals innerhalb dieses Zeitraums.

Demo ausführen

Bevor Sie PST verwenden, empfehlen wir Ihnen, zuerst die Demo einzurichten. Wenn Sie die PST-Demo ausprobieren möchten, müssen Sie Chrome mit Flags ausführen, um die wichtigsten Verpflichtungen des Ausstellers der Demo zu aktivieren. Folgen Sie dazu der Anleitung auf der Demoseite.

Wenn Sie diese Demo ausführen, verwendet Ihr Browser die Server für Aussteller und Einlöser der Demo, um Tokens bereitzustellen und zu verwenden.

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 Chrome auf einem Windows-Computer verwenden, lesen Sie diesen Leitfaden, um zu erfahren, wie Sie Parameter an die ausführbare Chrome-Binärdatei übergeben.
• Öffnen Sie die Chrome-Entwicklertools unter Anwendungen > Speicher > Private-State-Tokens, während Sie die Demo-Anwendung verwenden, um die vom Aussteller der Demo ausgestellten/eingelösten Tokens zu sehen.

Für die Einführung einrichten

Aussteller werden

Aussteller spielen bei PST eine wichtige Rolle. 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. Führen Sie dazu den Registrierungsprozess für Aussteller durch.

Wenn der Betreiber der Website des Ausstellers die Zertifizierung als Aussteller beantragen möchte, muss er im GitHub-Repository mit der Vorlage „New PST Issuer“ ein neues Problem erstellen. Folgen Sie der Anleitung im Repository, um das Problem zu melden. Sobald ein Endpunkt verifiziert wurde, wird er in dieses Repository zusammengeführt 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. Hier möchten wir weitere Informationen zu PST-Servern anbieten. Wenn Sie als Aussteller von PST-Tickets registriert 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 erstellen, die HTTP-Endpunkte bereitstellt.

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

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

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

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

3. Schlüssel: Die Tokenausstellerkomponente verwendet benutzerdefinierte EC-Schlüssel, um Tokens zu verschlüsseln. Diese Schlüssel müssen geschützt und in einem sicheren Speicher abgelegt werden.

Technische Anforderungen an Ausstellerserver

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

• Schlüsselbindung (z. B. /.well-known/private-state-token/key-commitment): Über diesen Endpunkt sind die Details Ihres öffentlichen Verschlüsselungsschlüssels für Browser verfügbar, um zu bestätigen, dass Ihr Server legitim ist.
  • Beispielcode
• Tokenausgabe (z. B. /.well-known/private-state-token/issuance): Der Tokenausgabeendpunkt, an dem alle Tokenanfragen verarbeitet werden. Dieser Endpunkt ist der Integrationspunkt für die Tokenausstellerkomponente.
  • Beispielcode

Wie bereits erwähnt, empfehlen wir aufgrund des erwarteten hohen Traffics, den dieser Server möglicherweise verarbeiten wird, die Bereitstellung mit einer skalierbaren Infrastruktur (z. B. in einer Cloud-Umgebung), damit Sie Ihr Backend an die schwankende Nachfrage anpassen können.

Aufruf an den Ausstellerserver senden

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

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

Codebeispiel

Redeemer-Server

Sie müssen den Token-Einlösungsdienst 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 du Gutscheincodes einlösen und die mit diesen Gutscheincodes verknüpften Einlösungseinträge lesen kannst.

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

Technische Anforderungen an Gutscheinserver

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

• /.well-known/private-state-token/redemption: Endpunkt, über den alle Token eingelöst werden. An diesem Endpunkt wird die Komponente zum Einlösen von Tokens eingebunden.
  • Beispielcode

Aufruf an den Gutscheinserver senden

Wenn du Tokens einlösen möchtest, musst du einen Website-Abrufaufruf in deinen Gutscheincode-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 du ein Token eingelöst hast, kannst du den Einlösungsdatensatz (Redemption Record, RR) senden, indem du einen weiteren Abruf aufrufst:

    // 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 Ihrer Implementierung zuerst die Webseite auf, auf der der Ausstelleraufruf 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. Rufe dann die Webseite auf, auf der der Aufruf zum Einlösen erfolgt, und prüfe, ob die RRs gemäß deiner Logik erstellt wurden.

Einsatz in der Praxis

Wir empfehlen, Zielwebsites auszuwählen, die zu Ihrem konkreten Anwendungsfall gehören:

• Wenig monatliche Zugriffe (ca. < 1 Million Zugriffe/Monat): Sie sollten die API zuerst für eine kleine Zielgruppe bereitstellen.
• Sie sind Eigentümer und steuern die Lösung: Bei Bedarf können Sie die Implementierung schnell und ohne komplexe Genehmigungen deaktivieren.
• Nicht mehr als ein Aussteller: So wird die Anzahl der Tokens begrenzt, um die Tests zu vereinfachen.
• Maximal zwei Nutzer können das Angebot einlösen: Sie müssen die Fehlerbehebung im Falle von Problemen vereinfachen.

Richtlinie zu Berechtigungen

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

Der Token-Anfragevorgang 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 Anweisungen standardmäßig auf * (alle Ursprünge) festgelegt. Das bedeutet, dass die Funktion für die Seite der obersten Ebene, für iFrames mit demselben Ursprung und für ursprungsübergreifende iFrames ohne explizite Delegierung verfügbar ist.

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

Sie können auch die Permissions-Policy-Überschrift verwenden, um den Zugriff von Drittanbietern auf PST zu steuern. Verwende als Parameter für die Liste der Header-Quellen self und alle Quellen, für die du den Zugriff auf die API zulassen möchtest. Wenn Sie beispielsweise die Verwendung von PST in allen Browserkontexten außer Ihrem eigenen Ursprung 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 plattformübergreifenden Ressourcen aktivieren möchten, legen Sie die Ursprungsliste auf * fest.

Weitere Informationen finden Sie unter Privacy Sandbox-Funktionen mit der Berechtigungsrichtlinie steuern und Berechtigungsrichtlinie.

Fehlerbehebung

Sie können PSTs auf den Tabs „Netzwerk“ und „Anwendung“ in den Chrome-Entwicklertools prüfen.

Auf dem Tab „Netzwerk“:

Auf dem Tab „Anwendung“:

Weitere Informationen zur DevTools-Integration

Best Practices für Kunden

Wenn die wichtigen Funktionen Ihrer Website von bestimmten Tokenausstellern abhängen, priorisieren Sie diese. Rufe hasPrivateToken(issuer) für diese bevorzugten Aussteller auf, bevor du andere Scripts lädst. Das ist wichtig, um potenzielle Probleme bei der Einlösung zu vermeiden.

Die Anzahl der Aussteller pro oberste Ebene ist auf zwei begrenzt. Drittanbieter-Scripts können auch versuchen, hasPrivateToken(issuer) aufzurufen, um ihre eigenen bevorzugten Aussteller zu priorisieren. Achten Sie daher darauf, die wichtigsten Aussteller im Voraus zu sichern, 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 Gutscheineinlösungsserver effizient funktioniert, empfehlen wir die Implementierung der folgenden Best Practices, damit Sie keine Probleme mit Zugriff, Sicherheit, Protokollierung oder Traffic für PST haben.

• Ihre Endpunkte müssen eine starke Kryptografie mit TLS 1.3 oder 1.2 anwenden.
• Ihre Infrastruktur muss in der Lage sein, mit variablen Besucherzahlen (einschließlich Spitzen) umzugehen.
• Achten Sie darauf, dass Ihre Schlüssel geschützt und sicher sind und mit Ihrer Zugriffssteuerungsrichtlinie, Ihrer Schlüsselverwaltungsstrategie und Ihren Notfallwiederherstellungsplänen übereinstimmen.
• Fügen Sie Ihrem Stack Messwerte zur Observability hinzu, damit Sie nach der Produktionseinführung die Nutzung, Engpässe und Leistungsprobleme nachvollziehen können.

Weitere Informationen

1. Entwicklerdokumentation ansehen:
   1. Lesen Sie zuerst die Übersicht, um sich mit PST und seinen Funktionen vertraut zu machen.
   2. Sehen Sie sich das Einführungsvideo zu PST an.
   3. PST-Demo ansehen
   4. Weitere Informationen finden Sie auch im Erläuterungsartikel zur API.
   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 zu den Begriffen finden Sie im Glossar zur Privacy Sandbox.
4. Weitere Informationen zu Chrome-Konzepten wie „Ursprungstest“ oder „Chrome-Flags“ finden Sie in den kurzen Videos und Artikeln unter goo.gle/cc.