In passato, i cookie di terze parti venivano utilizzati per memorizzare e trasmettere informazioni sullo stato di un utente, ad esempio lo stato di accesso e le informazioni sul dispositivo che utilizzano o se sono noti e attendibili. Ad esempio, se l'utente abbia effettuato l'accesso con SSO, indipendentemente dal fatto che l'utente disponga di un certo tipo di compatibilità dispositivo o se l'utente è noto e attendibile. Con il supporto dei cookie di terze parti verrà ritirato, molti di questi casi d'uso dovranno essere supportati con altri mezzi.
I token di stato privati consentono di condividere informazioni sul web, ma in modo che tutela la privacy attraverso controlli sulla quantità di dati che possono effettivamente essere condivisi.
I token di stato privati (precedentemente noti come token attendibili) consentono l'attendibilità nel contesto di un utente l'autenticità di essere trasmessa da un contesto all'altro aiutando i siti combatte le frodi e distingui i bot dagli esseri umani reali, senza il monitoraggio passivo.
Questo documento illustra i dettagli tecnici per l'implementazione dello stato privato. Token (PST). Per una panoramica più generale, consulta Panoramica di PST.
![Flusso di apprendimento per PST.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--a7powvbg65.png?authuser=8&hl=it)
Come funzionano i token di stato privati?
La relazione chiave da comprendere in PST è tra emittenti e utenti che hanno utilizzato la pubblicità. Emittenti e riscattatori possono essere all'interno della stessa azienda.
- Issuer (Emittenti): queste entità presentano alcuni indicatori sull'utente (ad ad esempio se l'utente è un bot o meno) e incorpora questo indicatore in un memorizzato sul dispositivo dell'utente (maggiori dettagli nelle sezioni successive).
- Utilizzatori: queste entità potrebbero non avere un indicatore relativo a un utente, ma hanno bisogno di sapere qualcosa su di loro (ad esempio, se l'utente è un bot o meno) e chiedere di utilizzare un token dell'emittente per comprendere l'affidabilità di quell'utente.
Ogni interazione PST richiede che emittenti e riscattatori collaborino per la condivisione e indicatori sul web. Questi indicatori sono valori approssimativi non dettagliati. identificare le persone.
I token di stato privati sono adatti al mio caso?
![Casi d'uso dei token di stato privati.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--k013opby06j.png?authuser=8&hl=it)
Aziende che prendono decisioni basate sulla fiducia e vogliono che le informazioni vengano disponibili in diversi contesti può trarre vantaggio dai PST. Per saperne di più sui potenziali casi d'uso di PST, consulta la nostra documentazione sui casi d'uso di PST.
Emetti e utilizza i token
L'implementazione di PST avviene in tre fasi:
- Emissione di token
- Utilizzo dei token
- Inoltro record di utilizzo
Nella prima fase, i token vengono emessi su un browser (di solito dopo una sorta di convalida). Nella seconda fase, un'altra persona giuridica richiederà l'utilizzo dell'offerta il token che è stato emesso per leggere il valore al suo interno. Nel finale , la parte utilizzante riceve un record di riscatto (RR) con il valore era contenuto nel token. La parte che utilizza la carta può quindi utilizzare tale record come dell'utente per vari scopi.
![Flusso base di token di stato privati.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--mpu9o98yv8s.png?authuser=8&hl=it)
Definisci la strategia dei token
Per definire la strategia dei token, devi comprendere i concetti chiave dei token PST (token e sui dati di utilizzo), le variabili, i comportamenti e le limitazioni per poter pensa al loro potenziale utilizzo nel tuo caso d'uso.
Token e dati di utilizzo: qual è il loro rapporto?
Ogni dispositivo può memorizzare fino a 500 token per sito web di primo livello e emittente. Inoltre, ogni token dispone di metadati che indicano la chiave utilizzata dall'emittente per emetterla. Questo può essere usato per decidere se utilizzare o meno un token durante e il processo di sviluppo. I dati PST vengono archiviati internamente dal browser sul dispositivo dell'utente e sono accessibili solo dall'API PST.
Quando viene riscattato un token, il Redemption Record (RR) viene memorizzato sul dispositivo. che funge da cache per utilizzi futuri. Il numero massimo è due utilizzo dei token ogni 48 ore, per dispositivo, pagina ed emittente. Nuovo utilizzo utilizzeranno le richieste RR memorizzate nella cache, ove possibile, invece di generare una richiesta emittente.
![Relazione tra PST e RR.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--k3dv3b99emg.png?authuser=8&hl=it)
- Vengono emessi nuovi token (massimo 500 per emittente, sito e dispositivo).
- Tutti i token vengono memorizzati nell'archivio di token sul dispositivo (simile all'archivio dei cookie).
- Se non viene trovato alcun RR attivo, sarà possibile generare nuovi RR dopo l’emissione (massimo 2 ogni 48 ore).
- Le RR sono considerate attive fino alla scadenza e verranno utilizzate come .
- Le nuove chiamate di utilizzo andranno a finire nella cache locale (non verranno generati nuovi RR).
Dopo aver definito il caso d'uso, è necessario definire attentamente la durata del RR Qui puoi definire quante volte potrai usarle per verificare se è così.
Assicurati di comprendere i seguenti comportamenti e variabili fondamentali prima di definire la strategia:
Variabile / comportamento | Descrizione | Utilizzo potenziale |
---|---|---|
Metadati della chiave del token | Ogni token può essere emesso utilizzando una sola chiave di crittografia e nel PST esiste un limite di sei chiavi per emittente. | Un modo potenziale per utilizzare questa variabile è definire un intervallo di attendibilità ai token in base alle tue chiavi di crittografia (ad esempio, chiave 1 = attendibilità elevata e chiave 6 = nessuna attendibilità). |
Data di scadenza del token | La data di scadenza del token corrisponde a quella della chiave. | Le chiavi possono essere ruotate almeno ogni 60 giorni e tutti i token emessi con anche le chiavi non valide sono considerate non valide. |
Limite per la frequenza di utilizzo del token | Esiste un limite di due utilizzi di token per dispositivo ed emittente ogni 48 ore. | Dipende dal numero stimato di utilizzi richiesti dall'utilizzo ogni 48 ore. |
Numero massimo di emittenti per origine di primo livello | Al momento, il numero massimo di emittenti per origine di primo livello è due. | Definisci attentamente gli emittenti di ogni pagina. |
Token per emittente su un dispositivo | Al momento è valido il numero massimo di token per emittente su un dispositivo specifico 500. | Assicurati di mantenere il numero di token inferiore a 500 per emittente. Assicurati di gestire gli errori nella tua pagina web quando provi a risolvere il problema di token. |
Rotazione impegni chiave | Ogni emittente PST deve esporre un endpoint con una chiave impegni che possono essere modificati ogni 60 giorni e qualsiasi rotazione più velocemente viene ignorato. | Se le tue chiavi scadranno tra meno di 60 giorni, è obbligatorio aggiornare i tuoi impegni chiave entro questa data per evitare interruzioni (vedi i dettagli). |
Durata del record di utilizzo | La durata di una RR può essere definita per determinare una scadenza data. Poiché le RR sono memorizzate nella cache per evitare nuove chiamate di riscatto non necessarie all'emittente, è importante assicurarsi di disporre di dati sufficienti indicatori di utilizzo. | Poiché esiste un limite di frequenza di riscatto di due token ogni 48 ore, è importante definire la durata del RR per poter eseguire le chiamate di riscatto con successo almeno in questo periodo di tempo (RR deve essere impostata di conseguenza). Ti consigliamo di impostarla nell'ordine delle settimane. |
Scenari di esempio
Scenario 1: la durata del RR è inferiore a 24 ore (t=t) e il riscatto è eseguito più volte in un periodo di 48 ore.
![Scenario di esempio 1 di PST: durata ridotta.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--vfxzghqns1.png?authuser=8&hl=it)
Scenario 2: la durata del ripristino di emergenza è di 24 ore e il riscatto viene eseguito più volte durante la finestra di 48 ore.
![Scenario di esempio 2 di PST: durata di 24 ore.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--msmzxvv5hfj.png?authuser=8&hl=it)
Scenario 3: la durata del ripristino di emergenza è di 48 ore e il riscatto viene eseguito più volte durante la finestra di 48 ore.
![Scenario di esempio 3 di PST: 48 ore di durata.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--c1w59jiklah.png?authuser=8&hl=it)
Esegui la demo
Prima di adottare PST, ti consigliamo di effettuare la configurazione con la demo. Per provare demo PST , dovrai eseguire Chrome con i flag per abilitare l'emittente della demo gli impegni principali (segui le istruzioni disponibili nella demo pagina).
![Schermata demo PST.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--ztx8xb2m1j.png?authuser=8&hl=it)
Se esegui questa demo, il tuo browser utilizza l'emittente e l'utilizzatore della demo per fornire e utilizzare token.
Considerazioni tecniche
La demo funzionerà meglio se implementi i seguenti passaggi:
- Assicurati di arrestare tutte le istanze di Chrome prima di eseguire Chrome con i flag.
- Se è in esecuzione su un computer Windows, dai un'occhiata in questa guida su come trasferire i parametri al file binario eseguibile di Chrome.
- Apri Chrome DevTools in Applicazioni > Spazio di archiviazione > Stato privato Token durante l'utilizzo dell'applicazione demo per vedere i token emessi/utilizzati dell'emittente della demo.
![Schermata di Chrome DevTools che mostra PST.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--t4a5yb69zzp.png?authuser=8&hl=it)
Configura per l'adozione
Diventa un emittente
Gli emittenti svolgono un ruolo fondamentale nel PST. Assegnano valori ai token per determinare se un utente è un bot o meno. Se vuoi iniziare a utilizzare PST in qualità di emittente, che dovranno registrarsi completando Procedura di registrazione dell'emittente.
Per richiedere di diventare emittente, l'operatore del sito web dell'emittente deve aprire una nuova issue sul sito web repositoryutilizzando il repository "New PST Emittente" modello. Segui le indicazioni presenti nel repository per risolvere il problema. Una volta verificato, un endpoint verrà unito a questo repository e L'infrastruttura lato server di Chrome inizierà a recuperare queste chiavi.
Server emittente
Emittenti e riscattatori sono i principali attori del PST; e token sono la chiave per i PST. Abbiamo già fornito alcuni dettagli sui token e nel documentazione di GitHub, volevamo offrire maggiori dettagli sui server PST. Per effettuare la configurazione come emittente di PST, devi avere per configurare prima un server emittente.
Esegui il deployment dell'ambiente: server emittenti
Per implementare il server emittente del token, devi creare il tuo lato server un'applicazione che espone gli endpoint HTTP.
Il componente dell'emittente è composto da due moduli principali: (1) il server dell'emittente e (2) l'emittente del token.
![Componenti server emittente.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/protections/private-state-tokens/images/Issuer.png?authuser=8&hl=it)
Come per tutte le applicazioni web, consigliamo un ulteriore livello di protezione al server emittente.
Issuer server: nella nostra implementazione di esempio, il nostro server emittente Node.js che utilizza il framework Express per ospitare il file Endpoint HTTP dell'emittente Puoi controllare il codice campione su GitHub.
Emittente token: il componente crittografico dell'emittente non richiede una lingua specifica ma, per via dei requisiti di prestazioni di questo componente, stiamo fornendo un'implementazione C come esempio, che utilizza la classe Boring SSL per gestire i token. Puoi trovare un esempio di codice emittente e ulteriori informazioni sull'installazione su GitHub
Chiavi: il componente emittente utilizza chiavi EC personalizzate per criptare i token. Queste chiavi devono essere protette e archiviate in uno spazio di archiviazione sicuro.
Requisiti tecnici per i server dell'emittente
Secondo il protocollo, sarà necessario implementare almeno due endpoint HTTP in il server emittente:
- Impegno chiave (ad esempio,
/.well-known/private-state-token/key-commitment
): È qui che i dettagli della chiave pubblica di crittografia saranno disponibili per i browser per conferma che il tuo server sia legittimo. - Emissione di token (ad esempio
/.well-known/private-state-token/issuance
): L'endpoint di emissione del token in cui verranno gestite tutte le richieste di token. Questo sarà il punto di integrazione per il componente dell'emittente del token.
Come accennato in precedenza, a causa del traffico elevato previsto, questo server la gestione della potenziale gestione, ti consigliamo di eseguirne il deployment utilizzando dell'infrastruttura (ad esempio, in un ambiente cloud) per poter regolare in base a una domanda variabile.
Invia una chiamata al server dell'emittente
Implementa una chiamata di recupero del sito web nello stack dell'emittente per emettere nuovi di token.
// issuer request
await fetch("/.well-known/private-state-token/issuance", {
method: "POST",
privateToken: {
version: 1,
operation: "token-request"
}
});
Server che utilizzano l'offerta
Dovrai implementare il servizio di riscatto dei token creandone uno applicazione lato server. In questo modo potrai leggere i token che un emittente inviate. I passaggi seguenti spiegano come riscattare i token e leggere i record di utilizzo associati a questi token.
Puoi scegliere di gestire l'emittente e l'utilizzatore nello stesso server (o gruppo di server).
![Componenti del server dell'autore dell'offerta.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/protections/private-state-tokens/images/redeemer.png?authuser=8&hl=it)
Requisiti tecnici per i server degli utilizzatori
Secondo il protocollo, sarà necessario implementare almeno due endpoint HTTP per il server che utilizzi per riscattare l'offerta:
/.well-known/private-state-token/redemption
: endpoint in cui tutti l'utilizzo del token verrà gestito. Questo endpoint sarà il punto in cui il componente acquirente sarà integrato
Invia una chiamata al server dell'utilizzatore
Per utilizzare i token, devi implementare una chiamata di recupero del sito web a il tuo stack utilizzabile per riscattare i token emessi prima.
// redemption request
await fetch("/.well-known/private-state-token/redemption", {
method: "POST",
privateToken: {
version: 1,
operation: "token-redemption",
refreshPolicy: "none"
}
});
Vedi l'esempio di codice.
Dopo aver utilizzato un token, puoi inviare il codice di riscatto (RR) svolgendo un'altra chiamata di recupero:
// 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>]
}
});
Vedi l'esempio di codice.
Esegui il deployment della tua implementazione
Per testare l'implementazione, accedi innanzitutto alla pagina web in cui e verificare che i token siano creati seguendo la logica. Verifica nel backend che le chiamate siano state effettuate in base alle specifiche. Quindi, visita la pagina web in cui viene effettuata la chiamata e verifica che vengono create le RR, in base alla tua logica.
Deployment nel mondo reale
Ti consigliamo di scegliere siti web target che rientrano nel tuo utilizzo specifico case:
- Numero ridotto di visite mensili (~ <1 milione di visite/mese): dovresti iniziare eseguendo il deployment dell'API per un pubblico ristretto
- Sei il proprietario e il controllo: se necessario, puoi disattivare rapidamente il implementazione senza approvazioni complesse
- Non più di un emittente: per limitare la quantità di token al fine di semplificare i test.
- Non più di due utenti: devi semplificare la risoluzione dei problemi in caso di problemi.
Norme relative alle autorizzazioni
Per funzionare correttamente, l'API PST deve essere disponibile per la pagina di primo livello e tutte le risorse secondarie che la utilizzano.
L'operazione di richiesta token è controllata dall'istruzione private-state-token-issuance
. Le operazioni token-redemption
e send-redemption-record
sono controllate dall'istruzione private-state-token-redemption
. Per impostazione predefinita, la lista consentita per queste istruzioni è impostata su self. Ciò significa che la funzionalità è disponibile soltanto per la pagina di primo livello (e per gli iframe della stessa origine) e non per gli iframe multiorigine senza delega esplicita da parte della pagina.
Puoi disattivare l'emissione o l'utilizzo del token PST per pagine specifiche del tuo sito includendo private-state-token-issuance=()
e private-state-token-redemption=()
nell'intestazione Permissions-Policy di ogni pagina.
Puoi anche utilizzare l'intestazione Permissions-Policy
per controllare l'accesso di terze parti al PST. Come parametri per l'elenco delle origini dell'intestazione, utilizza self
ed eventuali origini a cui vuoi consentire l'accesso all'API. Ad esempio, per disattivare completamente l'utilizzo di PST in tutti i contesti di navigazione, tranne la tua origine e https://example.com
, imposta le seguenti intestazioni della risposta HTTP:
Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")
Per abilitare l'API per tutte le risorse multiorigine, imposta l'elenco delle origini su *
.
Scopri come controllare le funzionalità di Privacy Sandbox con le norme sulle autorizzazioni o approfondisci la conoscenza delle norme relative alle autorizzazioni.
Risoluzione dei problemi
Puoi esaminare i file PST dalle schede Rete e Applicazione di Chrome DevTools.
Nella scheda Rete:
![Ispezione DevTools per la scheda Rete.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--u49gd5id2.png?authuser=8&hl=it)
Nella scheda Applicazione:
![Ispezione DevTools per la scheda Applicazione.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--bl7phyzjw3o.png?authuser=8&hl=it)
Scopri di più al riguardo Integrazione di DevTools.
Best practice per i clienti
Se le funzioni critiche del tuo sito web dipendono da determinati emittenti di token, assegna loro la priorità. Chiama hasPrivateToken(issuer)
per questi emittenti preferiti prima di caricare altri script. Ciò è fondamentale per evitare potenziali errori di utilizzo.
Il numero di emittenti per primo livello è massimo due e gli script di terze parti potrebbero anche provare a chiamare hasPrivateToken(issuer)
per dare priorità ai propri emittenti preferiti. Assicurati quindi di mettere in sicurezza in anticipo gli emittenti essenziali per assicurarti che il tuo sito funzioni come previsto.
// 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 practice per i server e risoluzione dei problemi
Affinché l'emittente e il server che utilizzi per la prima volta funzionino correttamente, ti consigliamo implementare le best practice riportate di seguito per assicurarti di non riscontrare verifica dell'accesso, della sicurezza, del logging o del traffico per PST.
- Gli endpoint devono applicare una crittografia avanzata utilizzando TLS 1.3 o 1.2.
- La tua infrastruttura deve essere pronta a gestire volumi di traffico variabili (compresi i picchi).
- Assicurati che le tue chiavi siano protette e sicure, in linea con il tuo livello di accesso policy di controllo, strategia di gestione delle chiavi e piani di continuità aziendale.
- Aggiungi metriche di osservabilità al tuo stack per assicurarti di ottenere visibilità per comprendere i problemi di utilizzo, colli di bottiglia e prestazioni per passare alla produzione.
Ulteriori informazioni
- Esamina la documentazione per gli sviluppatori:
- Inizia leggendo le Panoramica per restare al passo con PST e le sue funzionalità.
- Guarda il video introduttivo su PST.
- Prova la demo PST.
- Leggi anche l'API explainer per capire meglio i dettagli.
- Scopri di più sugli del modello dell'API.
- Contribuisci alla conversazione tramite GitHub o W3C per le chiamate.
- Per comprendere meglio la terminologia, esamina il Glossario di Privacy Sandbox.
- Per scoprire di più sui concetti di base di Chrome, ad esempio la "prova dell'origine" o "Segnalazioni di Chrome", guarda i brevi video e gli articoli disponibili su goo.gle/cc.