Entwicklerleitfaden für Private State Tokens

In der Vergangenheit wurden Drittanbieter-Cookies verwendet, um Informationen Informationen zum Status eines Nutzers, z. B. Anmeldestatus, Informationen zum Gerät oder ob sie bekannt und vertrauenswürdig sind. Wenn zum Beispiel die ob der Nutzer sich per SSO angemeldet hat, und ob er einen bestimmten kompatiblen oder ob der Nutzer bekannt und vertrauenswürdig ist. Mit Unterstützung von Drittanbieter-Cookies wird eingestellt, müssen viele dieser Anwendungsfälle auf andere Weise gestützt werden.

Private State Tokens bieten eine Möglichkeit, Informationen im Web zu teilen, allerdings in einem datenschutzfreundliche Möglichkeiten haben, die Datenmenge zu kontrollieren, weitergegeben werden dürfen.

Private State Tokens (früher Trust Tokens) ermöglichen das Vertrauen in die Authentizität kann von einem Kontext in einen anderen übertragen werden, während Websites Betrug zu bekämpfen und Bots von echten Menschen zu unterscheiden – ohne passives Tracking.

In diesem Dokument werden die technischen Details zur Implementierung des privaten Bundesstaats beschrieben. Tokens (PST): Einen groberen Überblick finden Sie in der PST-Übersicht

<ph type="x-smartling-placeholder">

</ph>

Wie funktionieren Private State Tokens?

In PST ist eine wichtige Beziehung zwischen Ausstellern und Einlösern wichtig. Aussteller und Einlösungsempfänger können zum selben Unternehmen gehören.

• Aussteller: Diese Entitäten haben Signale zu einem Nutzer (für ob dieser Nutzer ein Bot ist oder nicht) und bettet dieses Signal in ein Token, das auf dem Nutzergerät gespeichert ist. Weitere Informationen finden Sie in den nächsten Abschnitten.
• Einlöser: Diese Entitäten haben möglicherweise kein Signal zu einem Nutzer, etwas über sie wissen müssen (zum Beispiel, ob der Nutzer ein Bot ist und bitten Sie den Aussteller, ein Token einzulösen, Vertrauenswürdigkeit dieser Nutzenden.

Bei jeder PST-Interaktion müssen Aussteller und Einlösungspartner zusammenarbeiten, aus dem Web. Diese Signale sind grobe Werte, die nicht detailliert sind. um Personen 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 PST-Dateien profitieren. Weitere Informationen zu möglichen Anwendungsfällen der 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 an einen Browser ausgegeben (normalerweise nach einer Art Validierung). In der zweiten Phase fordert ein anderes Rechtssubjekt das Token, das zum Lesen des Werts in diesem Token ausgegeben wurde. Im Endspiel erhalten, erhält die nutzende Partei einen Einlösungseintrag (RR) mit dem Wert, der im Token enthalten war. Die einlösende Partei kann dann diesen Datensatz als Attestierung dieses Nutzers für verschiedene Zwecke.

<ph type="x-smartling-placeholder">

</ph>

Tokenstrategie definieren

Um Ihre Tokenstrategie zu definieren, müssen Sie die PST-Schlüsselkonzepte (Tokens) verstehen und Einlösungsdatensätze), Variablen, Verhaltensweisen und Einschränkungen über deren mögliche Nutzung für Ihren Anwendungsfall nachdenken.

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

Jedes Gerät kann bis zu 500 Tokens pro Website und Aussteller der obersten Ebene speichern. Außerdem Jedes Token verfügt über Metadaten, die angeben, welchen Schlüssel der Aussteller verwendet hat, um es auszustellen. Das Anhand dieser Informationen kann während der Einlösung entschieden werden, ob ein Token eingelöst werden soll oder nicht. . PST-Daten werden intern vom Browser auf dem Gerät des Nutzers gespeichert und kann nur über die PST API aufgerufen werden.

Beim Einlösen eines Tokens wird der Einlösungsnachweis auf dem Gerät gespeichert. Dieser Speicher dient als Cache für zukünftige Einlösungen. Es sind maximal zwei Einlösung von Tokens alle 48 Stunden pro Gerät, Seite und Aussteller. Neue Einlösung werden nach Möglichkeit im Cache gespeicherte RRs verwendet, statt eine Anfrage an die Aussteller.

1. Neue Tokens werden ausgestellt (max. 500 pro Aussteller, Website und Gerät).
2. Alle Tokens werden auf dem Gerät gespeichert (ähnlich wie ein Cookie-Speicher).
3. Wenn keine aktive RR gefunden wird, können nach der Ausstellung neue RRs generiert werden (maximal zwei pro 48 Stunden).
4. RRs gelten bis zum Ablauf als aktiv und werden als lokale Cache gespeichert werden.
5. Neue Einlösungsaufrufe erreichen den lokalen Cache (es werden keine neuen RRs generiert).

Nachdem Sie Ihren Anwendungsfall definiert haben, müssen Sie die Lebensdauer definieren Sie, wie oft Sie sie in Ihrem Fall.

Machen Sie sich mit den folgenden kritischen Verhaltensweisen und Variablen vertraut, beim Definieren der Strategie:

Variable / Verhalten	Beschreibung	Mögliche Nutzung
Metadaten des Tokenschlüssels	Jedes Token kann mit nur einem kryptografischen Schlüssel und einem In PST gilt eine Beschränkung von sechs Schlüsseln pro Aussteller.	Eine Möglichkeit, diese Variable zu verwenden, ist das Definieren eines Vertrauensbereichs basierend auf Ihren kryptografischen Schlüsseln (z. B. key 1 = hohes Vertrauen, während Schlüssel 6 = kein Vertrauen).
Ablaufdatum des Tokens	Das Ablaufdatum des Tokens ist mit dem Ablaufdatum des Schlüssels identisch.	Schlüssel können mindestens alle 60 Tage rotiert werden und alle Tokens, die mit ungültige Schlüssel ebenfalls als ungültig angesehen.
Limit für die Einlösungsrate von Tokens	Tokens können maximal zwei pro Gerät und Aussteller pro 48 Stunden.	Hängt von der geschätzten Anzahl der Einlösungen ab, die für Ihre Nutzung erforderlich sind Hülle alle 48 Stunden.
Maximale Anzahl von Ausstellern pro Ursprung auf oberster Ebene	Die maximale Anzahl von Ausstellern pro Ursprung auf oberster Ebene ist derzeit zwei.	Definieren Sie die Aussteller jeder Seite genau.
Tokens pro Aussteller auf einem Gerät	Die maximale Anzahl von Tokens pro Aussteller auf einem bestimmten Gerät ist derzeit 500.	Die Anzahl der Tokens pro Aussteller darf 500 nicht überschreiten. Gehen Sie unbedingt mit Fehlern auf Ihrer Webseite um, wenn Sie versuchen, Tokens.
Rotation wichtiger Zusicherungen	Jeder PST-Aussteller muss einen Endpunkt mit einem Schlüssel verfügbar machen Zusicherungen, die alle 60 Tage und jede Rotation schneller geändert werden können werden sie ignoriert.	Schlüssel müssen in weniger als 60 Tagen ablaufen, , um Ihre wichtigsten Verpflichtungen vor diesem Datum zu aktualisieren, um Unterbrechungen zu vermeiden Weitere Informationen
Laufzeit des Einlösungseintrags	Die Lebensdauer der RR kann definiert werden, um ein Ablaufdatum zu bestimmen. Datum. Da RRs im Cache gespeichert werden, um unnötige neue Einlösungsaufrufe zu vermeiden, an den Aussteller gesendet werden, ist es wichtig, Einlösungssignale.	Da die Einlösungsfrist von zwei Tokens alle 48 Stunden begrenzt ist, ist es wichtig, die Lebensdauer Ihrer RR zu definieren, Einlösungsaufrufe mit Erfolg über mindestens diesen Zeitraum (RR) Lebensdauer muss entsprechend festgelegt werden). Es wird empfohlen, diese die Lebenserwartung in Wochen.

Beispielszenarien

Szenario 1: Die Lebensdauer von RR beträgt weniger als 24 Stunden (t=t) und die Einlösung erfolgt mehrere Male in diesem 48-Stunden-Zeitfenster durchgeführt wurden.

<ph type="x-smartling-placeholder">

</ph>

Szenario 2: Die Lebensdauer von RR beträgt 24 Stunden und die Einlösung wird ausgeführt. während des 48-Stunden-Fensters.

<ph type="x-smartling-placeholder">

</ph>

Szenario 3: Die Lebensdauer der RR beträgt 48 Stunden und die Einlösung wird ausgeführt. während des 48-Stunden-Zeitraums.

<ph type="x-smartling-placeholder">

</ph>

Demo ausführen

Bevor Sie das PST verwenden, sollten Sie zuerst die Demo einrichten. Zum Ausprobieren PST-Demo verwenden, müssen Sie Chrome mit Flags ausführen, um den Demo-Aussteller zu aktivieren. wichtige Zusicherungen (siehe Anleitung in der Demo) ).

Wenn du diese Demo ausführst, verwendet dein Browser den Demo-Aussteller und -Einlöser zum Bereitstellen und Verbrauchen von Tokens.

Technische Aspekte

Die Demo funktioniert am besten, wenn Sie die folgenden Schritte implementieren:

• Beenden Sie daher alle Chrome-Instanzen, bevor Sie Chrome mit Flags ausführen.
• Wenn Sie mit einem Windows-Rechner arbeiten, in diesem Leitfaden zur Übergabe von Parametern an die ausführbare Chrome-Binärdatei.
• Öffnen Sie die Chrome-Entwicklertools unter Anwendungen > Speicher > Privater Bundesstaat Tokens während der Nutzung der Demoanwendung, um zu sehen, welche Tokens ausgestellt/eingelöst wurden vom Demo-Aussteller.

Zur Akzeptanz vorbereiten

Aussteller werden

Aussteller spielen in PST eine wichtige Rolle. Sie weisen den Tokens Werte zu, um ob ein Nutzer ein Bot ist oder nicht. Wenn Sie PST als Aussteller verwenden möchten, müssen Sie sich registrieren, indem Sie Registrierungsvorgang des Ausstellers.

Wenn Sie sich als Aussteller bewerben möchten, muss der Betreiber der Website des Ausstellers ein neues issue auf GitHub im Repository unter Verwendung der Aussteller“ Vorlage. Folgen Sie der Anleitung für das Repository, um das Problem auszufüllen. Sobald ein Endpunkt verifiziert wurde, wird er in diesem Repository zusammengeführt und Die serverseitige Infrastruktur von Chrome beginnt damit, diese Schlüssel abzurufen.

Ausstellerserver

Aussteller und Einlösungsempfänger sind die Hauptakteure für PST. und Tokens sind der Schlüssel Tools für PST. Wir haben bereits einige Details zu Tokens und in der GitHub-Dokumentation bieten weitere Details zu PST-Servern. Um als Aussteller von PST einzurichten, müssen Sie um zuerst einen ausstellenden Server einzurichten.

Umgebung bereitstellen: Ausstellerserver

Um den Server des Tokenausstellers zu implementieren, müssen Sie eine eigene Serverseite erstellen Anwendung, die HTTP-Endpunkte bereitstellt.

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

Wie bei allen webbasierten Anwendungen empfehlen wir eine zusätzliche Sicherheitsebene mit dem Ausstellerserver.

1. Ausstellerserver: In unserer Beispielimplementierung ist der ausstellende Server ein Node.js-Server, auf dem das Express-Framework gehostet wird HTTP-Endpunkte des Ausstellers. Sie können sich Beispielcode auf GitHub ansehen.

2. Token-Aussteller: Die kryptografische Komponente des Ausstellers erfordert keine Sprache sprechen. Aufgrund der Leistungsanforderungen dieser Komponente stellen wir als Beispiel eine C-Implementierung bereit, die das Boring- SSL-Bibliothek zum Verwalten von Tokens. Du findest das Codebeispiel des Ausstellers und weitere Informationen zur Installation. auf GitHub

3. Schlüssel: Die Komponente des Tokenausstellers verwendet benutzerdefinierte EC-Schlüssel zum Verschlüsseln von Tokens. Diese Schlüssel müssen geschützt und sicher aufbewahrt werden.

Technische Anforderungen an Ausstellerserver

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

• Schlüsselzusicherung (z. B. /.well-known/private-state-token/key-commitment): An diesem Endpunkt können Browser die Details des öffentlichen Verschlüsselungsschlüssels bestätigen dass Ihr Server seriös ist.
  • Beispielcode
• Tokenausstellung (z. B. /.well-known/private-state-token/issuance): Der Token ausstellende Endpunkt, an dem alle Tokenanfragen verarbeitet werden. Dieses Der Endpunkt ist der Integrationspunkt für die Komponente des Tokenausstellers.
  • Beispielcode

Wie bereits erwähnt, wird dieser Server aufgrund des zu erwartenden hohen Traffics empfehlen wir Ihnen, es mit einem skalierbaren (zum Beispiel in einer Cloud-Umgebung), um Ihren Back-End auf Basis einer variablen Nachfrage.

Aufruf an den Ausstellerserver senden

Implementieren Sie einen Websiteabrufaufruf an Ihren Ausstellerstack, um einen neuen Aufruf zu senden Tokens.

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

Codebeispiel ansehen

Erlöser-Server

Sie müssen den Token-Einlösungsdienst implementieren, indem Sie Ihren eigenen serverseitigen Anwendung. So können Sie die Tokens lesen, die ein Aussteller sendet. In den folgenden Schritten erfahren Sie, wie Sie Tokens einlösen und die Tokens lesen. die Einlösungsdatensätze, die mit diesen Tokens verknüpft sind.

Sie können festlegen, dass der Aussteller und der Einlösungsempfänger auf demselben Server (oder in derselben Gruppe von Server).

<ph type="x-smartling-placeholder">

</ph>

Technische Anforderungen an Einlösungsserver

Gemäß Protokoll müssen Sie mindestens zwei HTTP-Endpunkte für Ihrem Einlösungsserver:

• /.well-known/private-state-token/redemption: Endpunkt, an dem alle erfolgt die Einlösung des Tokens. An diesem Endpunkt wird das Token Einlöser-Komponente wird integriert <ph type="x-smartling-placeholder">
  </ph>
  • Beispielcode

Anruf an den Einlösungsserver senden

Zum Einlösen von Tokens müssen Sie einen Aufruf zum Abrufen der Website 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

Nach dem Einlösen eines Tokens können Sie den Einlösungseintrag (RR) senden, indem Sie einen weiteren Abrufaufruf:

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

Um Ihre Implementierung zu testen, rufen Sie zuerst die Webseite auf, auf der die ausstellende Website -Aufruf durchgeführt wird, und bestätigen Sie, dass die Tokens gemäß Ihrer Logik erstellt werden. Überprüfen Sie in Ihrem Back-End, ob die Aufrufe gemäß der Spezifikation erfolgt sind. Rufe dann die Webseite auf, auf der der Anruf eingelöst wird, und bestätige, dass werden die RRs gemäß Ihrer Logik erstellt.

Implementierung in der Praxis

Wir empfehlen Ihnen, die Kampagnen auf Websites auszurichten, die Ihrem spezifischen Zweck entsprechen. Fall:

• Geringe Anzahl monatlicher Besuche (~ < 1 Million Besuche/Monat): Sie sollten Sie die API zuerst für eine kleine Zielgruppe bereitstellen.
• Sie sind Inhaber und Kontrolle: Bei Bedarf können Sie die ohne komplexe Genehmigungen
• Nicht mehr als einen Aussteller: Damit wird die Anzahl der Tokens begrenzt, Tests vereinfachen.
• Nicht mehr als zwei Einlöser: Sie müssen die Fehlerbehebung in und Probleme auftreten.

Berechtigungsrichtlinie

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 Vorgang der Tokenanfrage wird von der Anweisung private-state-token-issuance gesteuert. Die Vorgänge token-redemption und send-redemption-record werden von der private-state-token-redemption-Anweisung gesteuert. Standardmäßig ist die Zulassungsliste für diese Anweisungen auf „self“ gesetzt. Das bedeutet, dass die Funktion nur für die Seite der obersten Ebene (und für Same-Origin-iFrames) und nur für ursprungsübergreifende iFrames ohne ausdrückliche Delegierung durch die Seite 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=() im Header Permissions-Policy jeder Seite angeben.

Sie können auch den Permissions-Policy-Header verwenden, um den Zugriff von Drittanbietern auf das PST zu steuern. Verwenden Sie als Parameter für die Liste der Header-Quellen self und alle Ursprünge, für die Sie den Zugriff auf die API zulassen möchten. 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.

Weitere Informationen zur Steuerung der Privacy Sandbox-Funktionen über die Richtlinie für Berechtigungen und zur Richtlinie für Berechtigungen

Fehlerbehebung

Sie können PST-Dateien in den Chrome-Entwicklertools auf den Tabs „Netzwerk“ und „Anwendung“ einsehen.

Auf dem Tab "Network" (Netzwerk):

<ph type="x-smartling-placeholder">

</ph>

Auf dem Tab „Anwendung“:

<ph type="x-smartling-placeholder">

</ph>

Weitere Informationen Entwicklertools-Integration:

Best Practices für Kunden

Wenn die kritischen Funktionen Ihrer Website von bestimmten Tokenausstellern abhängen, priorisieren Sie diese. Rufen Sie hasPrivateToken(issuer) für diese bevorzugten Aussteller auf, bevor Sie weitere Skripts laden. Dies ist wichtig, um potenzielle Fehler beim Einlösen zu vermeiden.

Die Anzahl der Aussteller pro übergeordneter Ebene ist auf zwei begrenzt und Skripts von Drittanbietern können auch versuchen, hasPrivateToken(issuer) aufzurufen, um ihre eigenen bevorzugten Aussteller zu priorisieren. Sichern Sie sich deshalb vorab die erforderlichen Aussteller, 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 der Aussteller und der Einlösungsserver effektiv arbeiten können, empfehlen wir, die folgenden Best Practices anwenden, um Zugriffs-, Sicherheits-, Logging- oder Traffic-Herausforderungen für das PST.

• Ihre Endpunkte müssen mithilfe von TLS 1.3 oder 1.2 starke Kryptografie anwenden.
• Ihre Infrastruktur muss auf schwankende Trafficvolumen vorbereitet sein (einschließlich Spitzen).
• Achten Sie darauf, dass Ihre Schlüssel entsprechend Ihrem Zugriffstyp geschützt und sicher sind Kontrollrichtlinien, Schlüsselverwaltungsstrategien und Pläne zur Aufrechterhaltung des Geschäftsbetriebs.
• Fügen Sie Ihrem Stack Beobachtbarkeitsmesswerte hinzu, um sicherzustellen, Transparenz, um Nutzung, Engpässe und Leistungsprobleme zu verstehen, in die Produktion gehen.

Weitere Informationen

1. Entwicklerdokumentation ansehen: <ph type="x-smartling-placeholder">
   </ph>
   1. Lesen Sie zuerst die Übersicht , um sich mit PST und dessen Funktionen vertraut zu machen.
   2. Sehen Sie sich das PST-Einführungsvideo an.
   3. Probieren Sie die PST-Demo aus.
   4. API lesen Erklärung, um mehr zu erfahren Details dazu.
   5. Weitere Informationen zum aktuellen Spezifikation der API.
2. Über GitHub zu Unterhaltungen beitragen Probleme oder W3C Anrufe
3. Um die Terminologie besser zu verstehen, sehen Sie sich die Glossar zur Privacy Sandbox
4. Weitere Informationen zu Chrome-Konzepten, z. B. „Ursprungstest“ oder „Chrome-Meldungen“ findet, findet ihr hier die kurzen Videos und Artikel auf goo.gle/cc