Esegui la migrazione all'API di reporting v1

È disponibile una nuova versione dell'API di reporting. È più privato e più probabile che sia supportato da tutti i browser.

Maud Nalpas

Attenzione: questo post spiega come eseguire la migrazione alla nuova versione dell'API Reporting (v1). Se non hai mai utilizzato l'API di reporting o hai bisogno di esempi di utilizzo dettagliati, consulta il post principale sull'API di reporting.

L'API di reporting ti informa degli errori che si verificano sul tuo sito quando i visitatori lo utilizzano. Ti offre visibilità su interventi del browser, arresti anomali del browser, violazioni dei criteri di sicurezza del contenuto, violazioni di COOP/COEP, avvisi di ritiro e altro ancora.

È disponibile una nuova versione dell'API di reporting. La nuova API è più snella e ha maggiori probabilità di essere supportata su tutti i browser.

Nota:l'API di reporting precedente è denominata API di reporting v0. La nuova API di reporting si chiama API di reporting v1.

Riepilogo

Sviluppatori di siti

Se disponi già della funzionalità di generazione di report per il tuo sito: esegui la migrazione alla v1 utilizzando la nuova intestazione (Reporting-Endpoints), ma mantieni l'intestazione precedente per un po' di tempo (Report-To). Consulta Migrazione: codice di esempio.

Se stai aggiungendo ora la funzionalità di generazione di report al tuo sito: utilizza solo la nuova intestazione (Reporting-Endpoints).

⚠️ In entrambi i casi, assicurati di impostare l'intestazione Reporting-Endpoints su tutte le risposte che potrebbero generare report.

Sviluppatori del servizio di reporting

Se gestisci un servizio endpoint o ne gestisci uno tuo, prevedi più traffico man mano che tu o gli sviluppatori esterni eseguite la migrazione all'API di reporting v1 (intestazione Reporting-Endpoints).

Continua a leggere per dettagli ed esempi di codice.

Registrazione degli errori di rete

Attenzione:se utilizzi Network Error Logging, continua a utilizzare Report-To (v0) perché Network Error Logging non è supportato nell'API di reporting v1.

Verrà sviluppato un nuovo meccanismo per la registrazione degli errori di rete. Una volta disponibile, passa dall'API di reporting v0 a questo nuovo meccanismo.

Demo e codice

• Sito demo: nuova API di reporting (v1)
• Codice per il sito demo

Differenze tra la versione 0 e la versione 1

Che cosa cambia

• La superficie API è diversa.

v0 (legacy)

 Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }
 Document-Policy: ...; report-to main-endpoint

{0 utilizza l'intestazione Report-To per configurare i gruppi di endpoint denominati e la direttiva report-to in altre intestazioni per fare riferimento a questi gruppi di endpoint.

v1 (nuovo)

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

La versione 1 utilizza l'intestazione Reporting-Endpoints per configurare gli endpoint denominati. Come la versione 0, utilizza la direttiva report-to in altre intestazioni per fare riferimento a questi gruppi di endpoint.

• L'ambito del report è diverso.

v0 (legacy)

Con la versione 0, puoi impostare gli endpoint di reporting solo su alcune risposte. Gli altri documenti (pagine) di questa origine utilizzeranno automaticamente questi endpoint ambientali.

v1 (nuovo)

Con la v1, devi impostare l'intestazione Reporting-Endpoints su tutte le risposte che potrebbero generare report.

• Entrambe le API supportano gli stessi tipi di report, con un'unica eccezione: la v1 non supporta i report sugli errori di rete. Scopri di più nei passaggi della migrazione.
• v0 non è e non sarà supportata su tutti i browser. È più probabile che v1 venga supportata su più browser in futuro.

Che cosa rimane invariato

• Il formato e la struttura dei report rimangono invariati.
• La richiesta inviata dal browser all'endpoint rimane una richiesta POST di Content-type application/reports+json.
• Il mapping di determinati endpoint a determinati tipi di report è supportato sia nella versione 0 che nella versione 1.
• Il ruolo dell'endpoint default è invariato.

• L'API di reporting v1 non ha alcun impatto su ReportingObserver. ReportingObserver continua ad avere accesso a tutti i report osservabili e il loro formato è identico.

Tutte le differenze tra la versione 0 e la versione 1

	API di reporting legacy (v0) Intestazione Report-To	Nuova API di reporting (v1) Reporting-Endpoints header
Supporto browser	Chrome 69+ ed Edge 69+.	Chrome 96+ ed Edge 96+. Firefox è supportato. Safari non si oppone. Consulta indicatori del browser.
Endpoint	Invia i report a uno qualsiasi dei più raccoglitori di report (più URL definiti per gruppo di endpoint).	Invia i report a raccoglitori di report specifici (solo un URL definito per endpoint).
Piattaforma API	Utilizza l'intestazione `Report-To` per configurare i gruppi di endpoint denominati.	Utilizza l'intestazione `Reporting-Endpoints` per configurare gli endpoint denominati.
Tipi di report che possono essere generati tramite questa API	Ritiro Intervento Arresto anomalo COOP/COEP Content-Security-Policy Level 3 (CSP Level 3) Registrazione degli errori di rete (NEL) Scopri di più sui tipi di report nel post sull'API Reporting.	Invariato, ad eccezione di Network Error Logging (NEL): non è supportato nella nuova API di reporting (v1).
Ambito del report	origine. L'intestazione di un documento Report-To influisce su altri documenti (pagine) della stessa origine. Il campo url di un report varia ancora in base al documento.	Documento. L'intestazione Reporting-Endpoints di un documento influisce solo su quel documento. Il campo url di un report varia ancora in base al documento.
Isolamento dei report (batching)	Documenti (pagine) o siti/origini diversi che generano un report nello stesso periodo di tempo e che hanno lo stesso endpoint di reporting verranno raggruppati: verranno inviati nello stesso messaggio all'endpoint di reporting.	I report di documenti (pagine) diversi non vengono mai inviati insieme. Anche se due documenti (pagine) della stessa origine generano un report contemporaneamente per lo stesso endpoint, questi non verranno raggruppati. Si tratta di un meccanismo per mitigare gli attacchi alla privacy. Le segnalazioni provenienti dallo stesso documento (pagina) possono essere inviate insieme.
Supporto per il bilanciamento del carico / le priorità	Sì	No

Sviluppatori di endpoint: aspettatevi più traffico

Se hai configurato il tuo server come endpoint di reporting o se stai sviluppando o gestendo un agente di raccolta di report come servizio, prevedi un aumento del traffico verso questo endpoint.

Questo perché i report non vengono raggruppati in batch con l'API di reporting v1 come avviene con l'API di reporting v0. Pertanto, man mano che gli sviluppatori di applicazioni iniziano la migrazione all'API di reporting v1, il numero di report rimarrà simile, ma il volume di richieste al server endpoint aumenterà.

Sviluppatori di applicazioni: esegui la migrazione a Reporting-Endpoints (v1)

Cosa dovresti fare?

L'utilizzo della nuova API di reporting (v1) offre diversi vantaggi ✅:

• I segnali del browser sono positivi, il che significa che è possibile prevedere il supporto cross-browser per la versione 1 (a differenza della versione 0, supportata solo in Chrome e Edge).
• L'API è più snella.
• Gli strumenti vengono sviluppati intorno alla nuova API di reporting (v1).

Tenendo presente questo:

• Se il tuo sito utilizza già l'API di reporting v0 con l'intestazione Report-To, esegui la migrazione all'API di reporting v1 (consulta i passaggi per la migrazione). Se il tuo sito utilizza già la funzionalità di generazione di report per le violazioni dei Criteri di sicurezza del contenuto, consulta i passaggi di migrazione specifici per la generazione di report CSP.
• Se il tuo sito non utilizza già l'API di reporting e ora stai aggiungendo la funzionalità di reporting: utilizza la nuova API di reporting (v1) (l'intestazione Reporting-Endpoints). Esiste un'eccezione a questa regola: se devi utilizzare la registrazione degli errori di rete, utilizza Report-To (v0). La registrazione degli errori di rete non è attualmente supportata nell'API di reporting v1. Verrà sviluppato un nuovo meccanismo per la registrazione degli errori di rete. Fino a quando non sarà disponibile, utilizza l'API di reporting v0. Se hai bisogno di Network Error Logging insieme ad altri tipi di report, utilizza entrambi Report-To (v0) e Reporting-Endpoints (v1). v0 fornisce Network Error Logging e v1 fornisce report di tutti gli altri tipi.

Passi per la migrazione

L'obiettivo di questa migrazione è non perdere i report che ricevevi con la versione 0.

Nota: poiché solo Chrome ed Edge supportano l'API di reporting v0, non devi concentrarti su altri browser durante la migrazione alla versione 1. Tuttavia, tieni presente che potrebbe essere disponibile un supporto più ampio dei browser. Al momento non sono presenti bug di monitoraggio per questi browser, ma la situazione potrebbe cambiare.

1. Passaggio 1 (da eseguire ora): utilizza entrambe le intestazioni: Report-To (v0) e Reporting-Endpoints (v1).

   In questo modo, avrai:

   • Report dei client Chrome ed Edge più recenti grazie a Reporting-Endpoints (v1).
   • Report di client Chrome ed Edge meno recenti grazie a Report-To (v0).

   Le istanze del browser che supportano Reporting-Endpoints utilizzeranno Reporting-Endpoints, mentre quelle che non lo supportano utilizzeranno Report-To. Il formato della richiesta e del report è lo stesso per v0 e v1.

2. Passaggio 2 (da eseguire ora): assicurati che l'intestazione Reporting-Endpoints sia impostata su tutte le risposte che potrebbero generare report.

   Con la versione 0, potevi scegliere di impostare gli endpoint di reporting solo su alcune risposte e altri documenti (pagine) su quell'origine avrebbero utilizzato questo endpoint "ambientale". Con la v1, a causa della differenza di ambito, devi impostare l'intestazione Reporting-Endpoints su tutte le risposte che potrebbero generare report.

3. Passaggio 3 (da iniziare in un secondo momento): una volta che tutti o la maggior parte degli utenti avranno eseguito l'aggiornamento alle versioni successive di Chrome o Edge (96 e successive), rimuovi Report-To (v0) e mantieni solo Reporting-Endpoints.

   Un'eccezione: se hai bisogno di report Network Error Logging, mantieni Report-To finché non sarà disponibile un nuovo meccanismo per Network Error Logging.

Vedi esempi di codice nel manuale di migrazione.

Passaggi per la migrazione per i report CSP

Esistono due modi per configurare i report sulle violazioni di Content-Security-Policy:

• Solo con l'intestazione CSP tramite l'istruzione report-uri. È supportato da un'ampia gamma di browser, tra cui Chrome, Firefox, Safari ed Edge. I report vengono inviati con il tipo di contenuti application/csp-report e hanno un formato specifico per CSP. Questi report sono chiamati "Report CSP di livello 2" e non si basano sull'API di reporting.
• Con l'API di reporting, tramite l'intestazione Report-To (legacy) o la più recente Reporting-Endpoints (v1). Questa funzionalità è supportata solo in Chrome e Edge. Le richieste di report hanno lo stesso formato delle altre richieste dell'API di reporting e lo stesso tipo di contenuti application/reports+json.

L'utilizzo del primo approccio (solo report-uri) non è più consigliato e l'utilizzo del secondo approccio presenta alcuni vantaggi. In particolare, ti consente di utilizzare un unico modo per configurare i report per tutti i tipi di report, nonché di impostare un endpoint generico (perché tutte le richieste di report generate tramite l'API Reporting⏤CSP e altre⏤hanno lo stesso formato application/reports+json.

Tuttavia, solo alcuni browser supportano report-to. Pertanto, ti consigliamo di mantenere report-uri insieme all'approccio dell'API di reporting (Report-To o versioni successive, Reporting-Endpoints) per ricevere report sulle violazioni di CSP da più browser. In un browser che riconosce report-uri e report-to, report-uri verrà ignorato se è presente report-to. In un browser che riconosce solo report-uri, verrà preso in considerazione solo report-uri.

1. Passaggio 1 (da eseguire ora): se non l'hai ancora fatto, aggiungi report-to insieme a report-uri. I browser che supportano solo report-uri (Firefox) utilizzeranno report-uri, mentre i browser che supportano anche report-to(Chrome, Edge) utilizzeranno report-to. Per specificare gli endpoint denominati che utilizzerai in report-to, utilizza le intestazioni Report-To e Reporting-Endpoints. In questo modo, riceverai report sia dai client Chrome ed Edge meno recenti sia da quelli più recenti.

2. Passaggio 3 (da iniziare in un secondo momento): una volta che tutti o la maggior parte degli utenti avranno eseguito l'aggiornamento alle versioni successive di Chrome o Edge (96 e successive), rimuovi Report-To (v0) e mantieni solo Reporting-Endpoints. Mantieni report-uri in modo da continuare a ricevere report per i browser che lo supportano.

Vedi esempi di codice per questi passaggi in Migrazione dei report CSP.

Migrazione: esempio di codice

Panoramica

Se utilizzi l'API di reporting legacy (v0) per ottenere report sulle violazioni per un'intestazione COOP (Cross-Origin-Opener-Policy), una COEP (Cross-Origin-Embedder-Policy) o una policy del documento (intestazione Document-Policy): non devi modificare queste intestazioni delle policy durante la migrazione all'API di reporting v1. Quello che devi fare è eseguire la migrazione dall'intestazione legacy Report-To alla nuova intestazione Reporting-Endpoints.

Se utilizzi l'API di reporting legacy (v0) per ottenere report sulle violazioni per un CSP (intestazione Content-Security-Policy), potresti dover modificare il tuo Content-Security-Policy nell'ambito della migrazione alla nuova API di reporting (v1).

Migrazione di base

Codice legacy (con v0)

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

Nuovo codice (codice di transizione con la versione 0 insieme alla versione 1)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }

Se nel tuo sito è già presente la funzionalità di generazione di report, mantieni Report-To solo temporaneamente (finché la maggior parte dei client Chrome ed Edge non sarà stata aggiornata) per evitare di perdere i report.

Se hai bisogno della registrazione degli errori di rete, mantieni Report-To fino a quando non sarà disponibile la sostituzione della registrazione degli errori di rete.

Nuovo codice (solo con la v1)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Ecco come potrebbe apparire il tuo codice in futuro, una volta che la maggior parte dei client Chrome ed Edge sarà stata aggiornata e supporterà l'API v1.

Tieni presente che con la v1 puoi comunque inviare tipi di report specifici a endpoint specifici. ma puoi avere un solo URL per endpoint.

Osservazione di tutte le pagine

Codice legacy (con v0), ad esempio con Express

app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

Con la versione 0, puoi impostare gli endpoint di reporting solo su alcune risposte. Altri documenti (pagine) sull'origine utilizzano automaticamente questi endpoint ambientali. In questo caso, gli endpoint impostati per "/" vengono utilizzati per tutte le risposte, ad esempio per page1.

Nuovo codice (con v1), ad esempio con Express

// Use a middleware to set the reporting endpoint(s) for *all* requests.
app.use(function(request, response, next) {
  response.set("Reporting-Endpoints", …);
  next();
});

app.get("/", (request, response) => {
  response.render(...)
});

app.get("/page1", (request, response) => {
  response.render(...)
});

Con la v1, devi impostare l'intestazione Reporting-Endpoints su tutte le risposte che potrebbero generare report.

Migrazione dei report CSP

Codice legacy, solo con report-uri

Content-Security-Policy: ...; report-uri https://reports.example/main

L'utilizzo solo di report-uri non è più consigliato. Se il codice è simile a quello sopra, esegui la migrazione. Vedi i nuovi esempi di codice riportati di seguito (in verde).

Codice legacy migliore, con report-uri e l'istruzione report-to con l'intestazione Report-To (v0)

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

Questo è meglio: questo codice utilizza report-to, il nuovo sostituto di report-uri. Mantiene comunque report-uri per la compatibilità con le versioni precedenti. Diversi browser non supportano report-to, ma supportano report-uri.

Tuttavia, questo codice potrebbe essere migliorato: utilizza l'API di reporting v0 (intestazione Report-To). Esegui la migrazione alla versione 1: vedi gli esempi di "Nuovo codice" riportati di seguito (in verde).

Nuovo codice, con report-uri e l'istruzione report-to con l'intestazione Reporting-Endpoints (v1)

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

Mantieni l'istruzione report-uri insieme all'istruzione report-to finché quest'ultima non sarà supportata da tutti i browser.report-to Consulta la tabella di compatibilità dei browser.

Tieni Report-To accanto a Reporting-Endpoints temporaneamente. Una volta che la maggior parte dei visitatori di Chrome ed Edge ha eseguito l'upgrade alle versioni del browser 96 e successive, rimuovi Report-To.

Per approfondire

• Monitora la tua applicazione web con l'API di reporting (post principale sull'API di reporting)
• Specifica: API di reporting legacy (v0)
• Specifica: nuova API di reporting (v1)

Un ringraziamento speciale a Ian Clelland, Eiji Kitamura e Milica Mihajlija per le loro recensioni e i loro suggerimenti su questo articolo.