Guida per gli sviluppatori di token di stato privati

In passato, i cookie di terze parti sono stati utilizzati per memorizzare e trasmettere informazioni sullo stato di un utente, ad esempio il suo stato di accesso, informazioni sul dispositivo che sta utilizzando o se è noto e attendibile. 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 di stato privato offrono un modo per condividere informazioni sul web, ma in modo rispettoso della privacy tramite controlli sulla quantità di dati che possono effettivamente essere condivisi.

I token di stato privati (precedentemente noti come token attendibili) consentono di trasferire l'attendibilità dell'autenticità di un utente da un contesto all'altro, aiutando al contempo i siti a combattere le attività fraudolente e a distinguere i bot dagli utenti reali, senza tracciamento passivo.

Questo documento descrive i dettagli tecnici per l'implementazione dei token di stato privato (PST). Per una panoramica più generale, consulta la panoramica del PST.

Come funzionano i token di stato privato?

La relazione chiave da comprendere in PST è quella tra emittenti e beneficiari. Gli emittenti e i beneficiari possono appartenere alla stessa società.

• Emittenti: queste entità hanno un indicatore relativo a un utente (ad esempio, se l'utente è un bot o meno) e lo incorporano in un token memorizzato sul dispositivo dell'utente (maggiori dettagli nelle sezioni successive).
• Destinatari: queste entità potrebbero non avere un segnale relativo a un utente, ma hanno bisogno di sapere qualcosa su di lui (ad esempio, se è un bot o meno) e chiedono di riscattare un token dall'emittente per comprendere l'affidabilità dell'utente.

Ogni interazione PST richiede che emittenti e beneficiari collaborino per condividere i segnali sul web. Questi indicatori sono valori approssimativi non sufficientemente dettagliati per identificare le persone.

I token di stato privati sono adatti al mio caso?

Le aziende che prendono decisioni di affidabilità e vogliono che queste informazioni siano disponibili in tutti i contesti possono trarre vantaggio dalle PST. Per saperne di più sui potenziali casi d'uso delle PST, consulta la nostra documentazione sui casi d'uso delle PST.

Emettere e riscattare token

L'implementazione del PST avviene in tre fasi:

1. Emissione di token
2. Utilizzo dei token
3. Inoltro dei record di utilizzo

Nella prima fase, i token vengono emessi per un browser (di solito dopo una sorta di convalida). Nella seconda fase, un'altra entità effettuerà una richiesta di utilizzo del token emesso per leggere il valore in quel token. Nella fase finale, la parte che riscatta riceve un record di riscatto (RR) con il valore contenuto nel token. La parte che riscatta può quindi utilizzare questo record come attestazione dell'utente per vari scopi.

Definisci la tua strategia dei token

Per definire la tua strategia dei token, devi comprendere i concetti chiave di 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 di primo livello ed emittente. Inoltre, ogni token ha metadati che indicano la chiave utilizzata dall'emittente per emetterlo. Queste informazioni possono essere utilizzate per decidere se riscattare o meno un token durante la procedura di riscatto. I dati PST vengono archiviati internamente dal browser sul dispositivo dell'utente e possono essere accessibili solo tramite l'API PST.

Quando un token viene riscattato, il record di riscatto viene memorizzato sul dispositivo. Questo spazio di archiviazione funge da cache per i futuri utilizzi. Esiste un limite di due riscatti di token ogni 48 ore, per dispositivo, pagina ed emittente. Le nuove chiamate di riscatto utilizzeranno i RR memorizzati nella cache, se possibile, anziché causare una richiesta all'emittente.

1. Vengono emessi nuovi token (max 500 per emittente, sito e dispositivo).
2. Tutti i token vengono archiviati nello spazio di archiviazione dei token sul dispositivo (simile allo spazio di archiviazione dei cookie).
3. Se non viene trovato alcun RR attivo, è possibile generare nuovi RR dopo l'emissione (massimo 2 ogni 48 ore).
4. I RR sono considerati attivi fino alla scadenza e verranno utilizzati come cache locale.
5. Le nuove chiamate di utilizzo colpiranno la cache locale (non vengono generati nuovi RR).

Dopo aver definito il caso d'uso, devi definire attentamente la durata delle RR, in quanto questo determinerà il numero di volte in cui potrai utilizzarle nel tuo caso.

Prima di definire la tua strategia, assicurati di comprendere i seguenti comportamenti e variabili critici:

Scenari di esempio

Scenario 1: la durata del RR è inferiore a 24 ore (t=t) e il riscatto viene eseguito più volte durante la finestra di 48 ore.

Scenario n. 2: la durata del RR è di 24 ore e il riscatto viene eseguito più volte durante il periodo di 48 ore.

Scenario 3: la durata del RR è di 48 ore e il riscatto viene eseguito più volte durante il periodo di 48 ore.

Esegui la demo

Prima di adottare PST, ti consigliamo di configurare la demo.

Se esegui questa demo, il browser utilizza i server dell'emittente e del beneficiario 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 eseguire Chrome con i flag.
• Se utilizzi un computer Windows, consulta questa guida su come passare i parametri al file binario eseguibile di Chrome.
• Apri Chrome DevTools in Applicazioni > Archiviazione > Token stato privato mentre utilizzi l'applicazione demo per visualizzare i token emessi o riscattati dall'emittente demo.

Configurazione per l'adozione

Questa sezione spiega i requisiti per diventare emittente o beneficiario di un PST.

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 PST come emittente, devi registrarti completando la procedura di registrazione dell'emittente.

Per fare domanda per diventare un emittente, l'operatore del sito web dell'emittente deve aprire un nuovo issue nel repository GitHub utilizzando il modello "New PST Issuer". Segui le indicazioni del repository per compilare il problema. Una volta verificato un endpoint, questo verrà unito a questo repository e l'infrastruttura lato server di Chrome inizierà a recuperare queste chiavi.

Server dell'emittente

Gli emittenti e i beneficiari sono gli attori chiave per PST; i server e i token sono gli strumenti chiave per PST. Sebbene abbiamo già fornito alcuni dettagli sui token e nella documentazione di GitHub, volevamo offrire maggiori 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 emittente token, devi creare un'applicazione lato server che esponga endpoint HTTP.

Il componente emittente è composto da due moduli principali: (1) il server dell'emittente e (2) l'emittente del token.

Come per tutte le applicazioni web, ti consigliamo di aggiungere un ulteriore livello di protezione al server dell'emittente.

1. Server emittente: nella nostra implementazione di esempio, il nostro 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.

2. 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 Boring SSL per gestire i token. Puoi trovare l'esempio di codice emittente e maggiori informazioni sull'installazione su GitHub.

3. 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 degli emittenti

In base al protocollo, devi implementare almeno due endpoint HTTP nel server dell'emittente:

• Impegno della chiave (ad esempio, /.well-known/private-state-token/key-commitment): Questo endpoint è il punto in cui i dettagli della chiave pubblica di crittografia saranno disponibili per i browser per confermare che il tuo server è legittimo.
  • Codice di esempio su GitHub
  • Guarda la demo
• Emissione del 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 endpoint sarà il punto di integrazione per il componente emittente di token.
  • Codice di esempio su GitHub
  • Visualizza la demo.

Come accennato in precedenza, a causa dell'elevato traffico previsto che questo server gestirà potenzialmente, 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 dell'emittente

Implementa una chiamata di recupero del sito web nello stack dell'emittente per emettere nuovi token.

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

Vedi un esempio di codice.

Server di riscatto

Dovrai implementare il servizio di utilizzo dei token creando un'applicazione lato server personalizzata. In questo modo potrai leggere i token inviati da un emittente. I passaggi seguenti descrivono come riscattare i token e come leggere i record di riscatto associati a questi token.

Puoi scegliere di eseguire l'emittente e il destinatario nello stesso server (o gruppo di server).

Requisiti tecnici per i server di utilizzo

In base al protocollo, devi implementare almeno due endpoint HTTP per il server di utilizzo:

• /.well-known/private-state-token/redemption: endpoint in cui verrà gestito il riscatto di tutti i token. Questo endpoint sarà il punto in cui verrà integrato il componente di utilizzo del token
  • Codice di esempio su GitHub
  • Demo

Invia una chiamata al server di utilizzo

Per utilizzare i token, devi implementare una chiamata di recupero del sito web nel tuo stack di utilizzo 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"
      }
    });

Vedi l'esempio di codice.

Dopo aver riscattato un token, puoi inviare il record di riscatto (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>]
      }
    });

Vedi 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 in base alla tua logica. Verifica nel backend che le chiamate siano state effettuate in base alla specifica. Poi, vai alla pagina web in cui viene effettuata la chiamata di utilizzo e verifica che i RR siano creati in base alla tua logica.

Deployment nel mondo reale

Ti consigliamo di scegliere siti web di destinazione che fanno parte del tuo caso d'uso specifico:

• Numero ridotto di visite mensili (circa < 1 milione di visite al mese): devi iniziare a eseguire il deployment dell'API su un piccolo pubblico
• È 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 semplificare i test.
• Non più di due persone che riscattano il premio: devi semplificare la risoluzione dei problemi in caso di problemi.

Criteri relativi alle autorizzazioni

Per funzionare correttamente, l'API PST deve essere disponibile per la pagina di primo livello e per tutte le risorse secondarie che la utilizzano.

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, per gli iframe con stessa origine e per gli iframe multiorigine senza delega esplicita.

Puoi disattivare l'emissione o il riscatto di token PST per pagine specifiche del tuo sito includendo private-state-token-issuance=() e private-state-token-redemption=() nell'intestazione Permissions-Policy per ogni pagina.

Puoi anche utilizzare l'intestazione Permissions-Policy per controllare l'accesso di terze parti al PST. Come parametri dell'elenco delle origini dell'intestazione, utilizza self e tutte le origini a cui vuoi consentire l'accesso all'API. Ad esempio, per disattivare completamente l'utilizzo di 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 multiorigine, imposta l'elenco delle origini su *.

Scopri come controllare le funzionalità di Privacy Sandbox con Permissions Policy o approfondisci la comprensione di Permissions Policy.

Risoluzione dei problemi

Puoi esaminare 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 la priorità a questi ultimi. 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 possono anche provare a chiamare hasPrivateToken(issuer) per dare la priorità ai propri emittenti preferiti. Pertanto, proteggi 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 e risoluzione dei problemi del server

Affinché il server dell'emittente e del beneficiario funzioni in modo efficace, ti consigliamo di implementare le seguenti best practice per evitare problemi di accesso, sicurezza, logging o traffico per PST.

• I tuoi endpoint devono applicare una crittografia efficace utilizzando TLS 1.3 o 1.2.
• La tua infrastruttura deve essere in grado di gestire volumi di traffico variabili (inclusi i picchi).
• Assicurati che le chiavi siano protette e sicure, in linea con la tua policy di controllo dell'accesso, la strategia di gestione delle chiavi e i piani di continuità aziendale.
• Aggiungi metriche di osservabilità al tuo stack per assicurarti di avere visibilità per comprendere l'utilizzo, i colli di bottiglia e i problemi di prestazioni dopo il passaggio alla produzione.

Ulteriori informazioni

1. Consulta la documentazione per gli sviluppatori:
   1. Inizia leggendo la panoramica per acquisire familiarità con PST e le sue funzionalità.
   2. Guarda il video introduttivo del PST.
   3. Prova la demo del PST.
   4. Leggi anche la spiegazione dell'API per comprenderne meglio i dettagli.
   5. Scopri di più sulle specifiche attuali dell'API.
2. Partecipa alla conversazione utilizzando i problemi di GitHub o le chiamate W3C.
3. Per comprendere meglio la terminologia, consulta il glossario di Privacy Sandbox.
4. Per scoprire di più sui concetti di Chrome, come "prova dell'origine" o "flag di Chrome", guarda i brevi video e leggi gli articoli disponibili su goo.gle/cc.