In passato, i cookie di terze parti sono stati utilizzati per memorizzare e trasmettere informazioni sullo stato di un utente, ad esempio lo stato di accesso, informazioni sul dispositivo in uso o se sono noti e attendibili. Ad esempio, se l'utente ha eseguito l'accesso con il Single Sign-On, se ha un determinato tipo di dispositivo compatibile o se è un utente noto e attendibile. Con il ritiro del supporto dei cookie di terze parti, molti di questi casi d'uso dovranno essere supportati con altri mezzi.
I token stato privato offrono un modo per condividere informazioni sul web, ma in modo da proteggere la privacy tramite controlli sulla quantità di dati che possono effettivamente essere condivisi.
I token di stato privati (in precedenza noti come token attendibili) consentono di trasmettere la fiducia nell'autenticità di un utente da un contesto all'altro, aiutando al contempo i siti a contrastare le attività fraudolente e a distinguere i bot dalle persone reali, il tutto senza monitoraggio passivo.
Questo documento illustra i dettagli tecnici per l'implementazione dei token di stato privato (PST). Per una panoramica più generale, consulta la panoramica dei file PST.
Come funzionano i token di stato privato?
La relazione chiave da comprendere in PST è quella tra emittenti e utilizzatori. Gli emittenti e gli utenti che utilizzano i coupon possono appartenere alla stessa azienda.
- Emittenti: queste entità hanno un indicatore su un utente (ad esempio se è un bot o meno) e lo inseriscono in un token archiviato sul dispositivo dell'utente (maggiori dettagli nelle sezioni successive).
- Utenti che utilizzano i token: queste entità potrebbero non avere un indicatore su un utente, ma devono sapere qualcosa su di lui (ad esempio se è un bot o meno) e chiedere di utilizzare un token emesso dall'emittente per capire la sua attendibilità.
Ogni interazione con i token PST richiede la collaborazione di emittenti e utenti per condividere gli indicatori sul web. Questi indicatori sono valori approssimativi non sufficientemente dettagliati per identificare le persone.
I token di stato privati sono adatti a me?
Le aziende che prendono decisioni in materia di affidabilità e vogliono che queste informazioni siano disponibili in più contesti possono trarre vantaggio dai PST. Per saperne di più sui potenziali casi d'uso delle PST, consulta la nostra documentazione sui casi d'uso delle PST.
Emettere e utilizzare i token
L'implementazione del PST avviene in tre fasi:
- Emissione di token
- Utilizzo dei token
- Inoltro dei record di utilizzo
Nella prima fase, i token vengono emessi per un browser (di solito dopo un qualche tipo di convalida). Nella seconda fase, un'altra entità invia una richiesta di utilizzo del token che è stato emesso per leggere il valore al suo interno. Nella fase finale, la parte che utilizza il coupon riceve un record di utilizzo (RR) con il valore contenuto nel token. La parte che utilizza il coupon può quindi utilizzare il record come attestazione dell'utente per vari scopi.
Definire la strategia per i token
Per definire la tua strategia di token, devi comprendere i concetti chiave dei token PST (token e record di utilizzo), le variabili, i comportamenti e le limitazioni per poter pensare al loro potenziale utilizzo per il tuo caso d'uso.
Token e record di utilizzo: qual è la relazione tra loro?
Ogni dispositivo può memorizzare fino a 500 token per sito web e emittente di primo livello. Inoltre, ogni token contiene metadati che indicano la chiave utilizzata dall'emittente per emetterlo. Queste informazioni possono essere utilizzate per decidere se utilizzare o meno un token durante la procedura di utilizzo. I dati PST vengono archiviati internamente dal browser sul dispositivo dell'utente e si può accedere solo tramite l'API PST.
Quando un token viene utilizzato, il record di utilizzo (RR) viene memorizzato sul dispositivo. Questo spazio di archiviazione funge da cache per i futuri utilizzi. Esiste un limite di due utilizzi di token ogni 48 ore, per dispositivo, pagina ed emittente. Le nuove chiamate di redemption utilizzeranno RR memorizzati nella cache, se possibile, anziché inviare una richiesta all'emittente.
- Vengono emessi nuovi token (massimo 500 per emittente, sito e dispositivo).
- Tutti i token vengono memorizzati nell'apposito archivio sul dispositivo (simile all'archivio dei cookie).
- Se non viene trovato alcun RR attivo, è possibile generare nuovi RR dopo l'emissione (massimo 2 ogni 48 ore).
- I record RR sono considerati attivi fino alla scadenza e verranno utilizzati come cache locale.
- Le nuove chiamate di utilizzo verranno memorizzate nella cache locale (non vengono generati nuovi RR).
Dopo aver definito il caso d'uso, devi definire attentamente la durata del report RR, poiché questo determinerà quante volte potrai utilizzarlo nel tuo caso.
Prima di definire la tua strategia, assicurati di comprendere i seguenti comportamenti e variabili fondamentali:
| Variabile / comportamento | Descrizione | Utilizzo potenziale |
|---|---|---|
| Metadati della chiave del token | Ogni token può essere emesso utilizzando una sola chiave crittografica e in PST è prevista una limitazione di sei chiavi per emittente. | Un potenziale modo per utilizzare questa variabile è definire un intervallo di attendibilità per i token in base alle chiavi crittografiche (ad esempio, chiave 1 = attendibilità elevata, mentre 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 chiavi non valide sono considerati non validi. |
| Limite di frequenza di utilizzo dei token | Esiste un limite di due utilizzi di token per dispositivo ed emittente ogni 48 ore. | Dipende dal numero stimato di utilizzi richiesti dal tuo caso d'uso ogni 48 ore. |
| Numero massimo di emittenti per origine di primo livello | Attualmente, 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, 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 pagina web quando provi a emettere i token. |
| Rotazione degli impegni relativi alle chiavi | È obbligatorio che ogni emittente di token PST esponga un endpoint con impegni relativi alle chiavi che possono essere modificati ogni 60 giorni e qualsiasi rotazione più rapida verrà ignorata. | Se le tue chiavi scadranno tra meno di 60 giorni, è obbligatorio aggiornare gli impegni relativi alle chiavi prima di questa data per evitare interruzioni (vedi dettagli). |
| Durata del record di utilizzo | La durata del report RR può essere definita per determinare una data di scadenza. Poiché le RR vengono memorizzate nella cache per evitare nuove chiamate di riscatto non necessarie all'emittente, è importante assicurarsi di avere indicatori di riscatto sufficientemente aggiornati. | Poiché esiste un limite di frequenza di utilizzo di due token ogni 48 ore, è importante definire la durata del tuo RR per poter eseguire chiamate di utilizzo correttamente per almeno questo periodo di tempo (la durata del RR deve essere impostata di conseguenza). Ti consigliamo di impostare questo periodo di tempo nell'ordine delle settimane. |
Scenari di esempio
Scenario 1: la durata del codice RR è inferiore a 24 ore (t=t) e lo sconto viene eseguito più volte durante il periodo di 48 ore.
Scenario 2: la durata del codice promozionale è di 24 ore e il riscatto viene eseguito più volte durante il periodo di 48 ore.
Scenario 3: la durata del codice promozionale è di 48 ore e il riscatto viene eseguito più volte durante la finestra di 48 ore.
Esegui la demo
Prima di adottare PST, ti consigliamo di eseguire la configurazione della demo. Per provare la demo PST , devi eseguire Chrome con i flag per attivare gli impegni chiave dell'emittente della demo (segui le istruzioni disponibili nella pagina della demo).
Se esegui questa demo, il browser utilizza i server di emittente e utilizzatore della demo per fornire e utilizzare i token.
Considerazioni tecniche
La demo funzionerà al meglio se implementi i seguenti passaggi:
- Assicurati di arrestare tutte le istanze di Chrome prima di eseguirlo con i flag.
- Se utilizzi un computer Windows, consulta questa guida su come passare parametri al file eseguibile binario di Chrome.
- Apri Chrome DevTools in Applicazioni > Spazio di archiviazione > Token stato privato mentre utilizzi l'applicazione di dimostrazione per visualizzare i token emessi/riscattati dall'emittente della demo.
Configurazione per l'adozione
Diventa un emittente
Gli emittenti svolgono un ruolo chiave nel PST. Assegnano valori ai token per determinare se un utente è un bot o meno. Se vuoi iniziare a utilizzare il PST come emittente, devi registrarti completando la procedura di registrazione degli emittenti.
Per richiedere di diventare un emittente, l'operatore del sito web dell'emittente deve aprire un nuovo issue nel repository GitHub utilizzando il modello "Nuovo emittente PST". Segui le indicazioni nel repository per compilare il problema. Una volta verificato, un endpoint verrà unito a questo repository e l'infrastruttura lato server di Chrome inizierà a recuperare le chiavi.
Server emittenti
Gli emittenti e gli utenti che utilizzano i coupon sono gli attori principali del PST; i server e i token sono gli strumenti principali per il PST. Abbiamo già fornito alcuni dettagli sui token e nella documentazione di GitHub, ma volevamo offrire ulteriori dettagli sui server PST. Per configurarti come emittente di PST, devi prima configurare un server di emissione.
Esegui il deployment dell'ambiente: server emittenti
Per implementare il server di emittenti di token, devi creare la tua applicazione lato server che esponga endpoint HTTP.
Il componente emittente è composto da due moduli principali: (1) il server emittente e (2) l'emittente di token.
Come per tutte le applicazioni rivolte al web, ti consigliamo di applicare un ulteriore livello di protezione al server del tuo emittente.
Server emittente: nell'implementazione di esempio, il server emittente è un server Node.js che utilizza il framework Express per ospitare gli endpoint HTTP dell'emittente. Puoi consultare il codice di esempio su GitHub.
Emittente di token: il componente crittografico dell'emittente non richiede un linguaggio specifico, ma a causa dei requisiti di prestazioni di questo componente, forniamo un'implementazione in C come esempio, che utilizza la libreria BoringSSL per gestire i token. Puoi trovare l'esempio di codice emittente e ulteriori informazioni sull'installazione su GitHub
Chiavi: il componente Emittente token utilizza chiavi EC personalizzate per criptare i token. Queste chiavi devono essere protette e archiviate in un archivio sicuro.
Requisiti tecnici per i server dei emittenti
In base al protocollo, dovrai implementare almeno due endpoint HTTP nel tuo server emittente:
- Impegno della chiave (ad es.
/.well-known/private-state-token/key-commitment): in questo endpoint i dettagli della chiave pubblica di crittografia saranno disponibili per i browser per confermare che il tuo server è legittimo. - Emissione di token (ad es.
/.well-known/private-state-token/issuance): l'endpoint di emissione dei token in cui verranno gestite tutte le richieste di token. Questo endpoint sarà il punto di integrazione per il componente emittente di token.
Come accennato in precedenza, a causa dell'elevato traffico previsto che questo server potrebbe gestire, ti consigliamo di eseguirne il deployment utilizzando un'infrastruttura scalabile (ad esempio in un ambiente cloud) per poter regolare il backend in base a una domanda variabile.
Invia una chiamata al server del emittente
Implementa una chiamata di recupero del sito web nel tuo stack di emittenti per emettere nuovi token.
// issuer request
await fetch("/.well-known/private-state-token/issuance", {
method: "POST",
privateToken: {
version: 1,
operation: "token-request"
}
});
Server di redemption
Dovrai implementare il servizio di utilizzo dei token creando la tua applicazione lato server. In questo modo potrai leggere i token inviati da un emittente. I passaggi riportati di seguito descrivono come riscattare i token e come leggere i record di riscatto associati a questi token.
Puoi scegliere di eseguire l'emittente e l'utilizzatore nello stesso server (o gruppo di server).
Requisiti tecnici per i server di redemption
In base al protocollo, dovrai implementare almeno due endpoint HTTP per il tuo server di riscossione:
/.well-known/private-state-token/redemption: endpoint in cui verrà gestito tutto lo sconto dei token. In questo endpoint verrà integrato il componente per il riscatto dei token.
Invia una chiamata al server del riscattatore
Per utilizzare i token, devi implementare una chiamata di recupero del sito web nel tuo stack di utenti autorizzati per utilizzare i token emessi in precedenza.
// redemption request
await fetch("/.well-known/private-state-token/redemption", {
method: "POST",
privateToken: {
version: 1,
operation: "token-redemption",
refreshPolicy: "none"
}
});
Consulta l'esempio di codice.
Dopo aver utilizzato un token, puoi inviare il record di utilizzo (RR) effettuando 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>]
}
});
Consulta l'esempio di codice.
Esegui il deployment dell'implementazione
Per testare l'implementazione, vai prima alla pagina web in cui viene effettuata la chiamata di emissione e verifica che i token vengano creati seguendo la tua logica. Verifica nel backend che le chiamate siano state effettuate in base alle specifiche. Poi, vai alla pagina web in cui viene effettuata la chiamata di utilizzo e verifica che gli RR siano stati creati seguendo la tua logica.
Deployment reale
Ti consigliamo di scegliere come target i siti web che fanno parte del tuo caso d'uso specifico:
- Numero ridotto di visite mensili (~ < 1 milione di visite/mese): devi iniziare a eseguire il deployment dell'API per un pubblico ristretto
- È di tua proprietà e sotto il tuo controllo: se necessario, puoi disattivare rapidamente l'implementazione senza approvazioni complesse
- Non più di un emittente: per limitare la quantità di token al fine di simplificare i test.
- Non più di due utenti che possono utilizzare il coupon: è necessario semplificare la risoluzione dei problemi in caso di difficoltà.
Norme relative alle autorizzazioni
Per funzionare correttamente, l'API PST deve essere disponibile per la pagina di primo livello e per eventuali risorse secondarie che utilizzano l'API.
L'operazione di richiesta del token è controllata dalla direttiva private-state-token-issuance. Le operazioni token-redemption e send-redemption-record sono controllate dalla direttiva private-state-token-redemption. In Chrome 132 e versioni successive, la lista consentita per queste direttive è impostata su * (tutte le origini) per impostazione predefinita. Ciò significa che la funzionalità è disponibile per la pagina di primo livello, gli iframe dello stesso dominio e gli iframe cross-origin senza delega esplicita.
Puoi disattivare l'emissione o il rimborso di 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 e le origini a cui vuoi consentire l'accesso all'API. Ad esempio, per disattivare completamente l'utilizzo del PST in tutti i contesti di navigazione, ad eccezione della tua origine e di https://example.com, imposta le seguenti intestazioni di risposta HTTP:
Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")
Per attivare l'API per tutte le risorse cross-origin, imposta l'elenco di origini su *.
Scopri come controllare le funzionalità di Privacy Sandbox con le Norme relative alle autorizzazioni o approfondisci la conoscenza delle Norme relative alle autorizzazioni.
Risoluzione dei problemi
Puoi ispezionare i PST dalle schede Rete e Applicazione di Chrome DevTools.
Nella scheda Rete:
Nella scheda Applicazione:
Scopri di più su questa integrazione di DevTools.
Best practice per i client
Se le funzioni critiche del tuo sito web dipendono da determinati emittenti di token, dai loro la priorità. Chiama hasPrivateToken(issuer) per questi emittenti preferiti prima di caricare altri script. Questo è fondamentale per evitare potenziali errori di utilizzo.
Il numero di emittenti per livello superiore è limitato a due e gli script di terze parti potrebbero anche provare a chiamare hasPrivateToken(issuer) per dare la priorità ai propri emittenti preferiti. Pertanto, assicurati in anticipo di proteggere gli emittenti essenziali per garantire il funzionamento del tuo sito 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 e risoluzione dei problemi per i server
Affinché i server di emittente e di utilizzo funzionino in modo efficace, ti consigliamo di implementare le seguenti best practice per assicurarti di non riscontrare problemi di accesso, sicurezza, registrazione o traffico per i token PST.
- Gli endpoint devono applicare una crittografia avanzata utilizzando TLS 1.3 o 1.2.
- L'infrastruttura deve essere pronta a gestire volumi di traffico variabili (inclusi i picchi).
- Assicurati che le chiavi siano protette e sicure, in linea con i tuoi criteri di controllo dell'accesso, la tua strategia di gestione delle chiavi e i tuoi piani di continuità aziendale.
- Aggiungi le metriche di osservabilità al tuo stack per assicurarti di avere la visibilità necessaria per comprendere l'utilizzo, i colli di bottiglia e i problemi di prestazioni dopo il passaggio alla produzione.
Ulteriori informazioni
- Esamina la documentazione per gli sviluppatori:
- Per iniziare, consulta la panoramica per acquisire familiarità con PST e le sue funzionalità.
- Guarda il video introduttivo del PST.
- Prova la demo PST.
- Leggi anche la spiegazione dell'API per saperne di più.
- Scopri di più sulla specifica corrente dell'API.
- Contribuisci alla conversazione tramite i problemi GitHub o le chiamate W3C.
- Per comprendere meglio la terminologia, consulta il glossario di Privacy Sandbox.
- Per scoprire di più sui concetti di Chrome, come "prova dell'origine" o "flag di Chrome", guarda i brevi video e gli articoli disponibili all'indirizzo goo.gle/cc.