Esegui la migrazione all'API di reporting v1

È disponibile una nuova versione dell'API di reporting. È più privato e ha maggiori probabilità di essere supportato su più 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 Reporting o hai bisogno di esempi dettagliati di utilizzo, consulta il post principale sull'API Reporting.

L'API Reporting ti informa sugli errori che si verificano sul tuo sito quando i visitatori lo utilizzano. Offre visibilità su interventi e arresti anomali del browser, violazioni dei criteri di sicurezza dei contenuti, 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 più browser.

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

Riepilogo

Sviluppatori di siti

Se hai già la funzionalità di generazione di report per il tuo sito: esegui la migrazione alla versione 1 utilizzando il nuovo intestazione (Reporting-Endpoints), ma mantieni l'intestazione precedente per un po' di tempo (Report-To). consulta Migrazione: codice di esempio.

Se stai aggiungendo 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 di servizi di reporting

Se gestisci un servizio endpoint o ne gestisci uno tuo, tieni presente che durante la migrazione all'API Reporting 1.0 (intestazione Reporting-Endpoints) da parte tua o di sviluppatori esterni, il traffico aumenterà.

Continua a leggere per ulteriori dettagli e per conoscere il codice di esempio.

Logging degli errori di rete

Attenzione: se utilizzi Network Error Logging, continua a utilizzareReport-To (v0) perché Network Error Logging non è supportato nella versione 1 dell'API Reporting.

Verrà sviluppato un nuovo meccanismo per la registrazione degli errori di rete. Quando sarà disponibile, passa dalla versione 0 dell'API di reporting a questo nuovo meccanismo.

Demo e codice

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

Differenze tra v0 e v1

Che cosa cambia

• L'interfaccia 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 gruppi di endpoint denominati e la direttiva report-to in altre intestazioni per fare riferimento a questi gruppi di endpoint.

v1 (nuova)

 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 nominativi. Come la versione v0, utilizza l'istruzione report-to in altre intestazioni per fare riferimento a questi gruppi di endpoint.

• L'ambito del report è diverso.

v0 (precedente)

Con la versione 0, puoi impostare gli endpoint di generazione di report solo su alcune risposte. Gli altri documenti (pagine) di quell'origine utilizzeranno automaticamente questi endpoint ambient.

v1 (nuova)

Con la versione 1, 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'eccezione: la versione 1 non supporta i report sugli errori di rete. Scopri di più nella sezione Passaggi della migrazione.
• La versione 0 non è e non sarà supportata su tutti i browser. È più probabile che la versione 1 sia supportata su più browser in futuro.

Che cosa rimane invariato

• Il formato e la struttura dei report non subiranno modifiche.
• La richiesta inviata dal browser all'endpoint rimane una richiesta POST di Content-type application/reports+json.
• La mappatura di determinati endpoint a determinati tipi di report è supportata sia nella versione 0 che nella versione 1.
• Il ruolo dell'endpoint default non è stato modificato.

• La versione 1 dell'API di reporting non ha alcun impatto su ReportingObserver. ReportingObserver continua ad avere accesso a tutti i report osservabili e il suo formato è identico.

Tutte le differenze tra v0 e v1

	Header dell'API Reports legacy (v0) Report-To	Intestazione della nuova API di reporting (v1) Reporting-Endpoints
Supporto browser	Chrome 69 e versioni successive ed Edge 69 e versioni successive.	Chrome 96+ ed Edge 96+. Firefox è supportato. Safari non obietta. Consulta gli indicatori del browser.
Endpoint	Invia i report a uno dei diversi collector di report (più URL definiti per gruppo di endpoint).	Invia i report a collezionisti di report specifici (un solo URL definito per endpoint).
API surface	Utilizza l'intestazione `Report-To` per configurare gruppi di endpoint denominati.	Utilizza l'intestazione `Reporting-Endpoints` per configurare endpoint denominati.
Tipi di report che possono essere generati tramite questa API	Ritiro Intervento Arresto anomalo COOP/COEP Livello 3 dei criteri di sicurezza del contenuto (CSP) Network Error Logging (NEL) Scopri di più sui tipi di report nel post sull'API Reporting.	Invariato, ad eccezione del Network Error Logging (NEL): non è supportato nella nuova API Reporting (v1).
Ambito dei report	origine.L'intestazione di un documento influisce su altri documenti (pagine) di quell'origine. Il campo url di un report continua a variare in base al documento.	Documento. L'intestazione Reporting-Endpoints di un documento interessa solo 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 all'incirca nello stesso momento e che hanno lo stesso endpoint di generazione di report verranno raggruppati: verranno inviati nello stesso messaggio all'endpoint di generazione di report.	I report di documenti (pagine) diversi non vengono mai inviati insieme. Anche se due documenti (pagine) della stessa origine generano contemporaneamente un report per lo stesso endpoint, questi non verranno raggruppati. Si tratta di un meccanismo per mitigare gli attacchi alla privacy. I report dello stesso documento (pagina) possono essere inviati insieme.
Supporto per il bilanciamento del carico/le priorità	Sì	No

Sviluppatori di endpoint: aspettati un aumento del traffico

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

Questo perché i report non vengono raggruppati con la versione 1 dell'API di reporting, come avviene con la versione 0. Pertanto, quando gli sviluppatori di applicazioni inizieranno a eseguire la migrazione alla versione 1 dell'API di reporting, il numero di report rimarrà simile, ma il volume di richieste al server endpoint aumenterà.

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

Cosa dovresti fare?

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

• Gli indicatori del browser sono positivi, il che significa che è previsto il supporto tra browser per la versione 1 (a differenza della versione v0, supportata solo in Chrome ed Edge).
• L'API è più fluida.
• È in corso lo sviluppo di strumenti relativi alla nuova API di reporting (v1).

Tenendo presente quanto segue:

• Se il tuo sito utilizza già la versione 0 dell'API Reports con l'intestazione Report-To, esegui la migrazione alla versione 1 dell'API Reports (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 specifici per la migrazione per i report CSP.
• Se il tuo sito non utilizza già l'API Reporting e ora stai aggiungendo la funzionalità di generazione di report: utilizza la nuova API Reporting (v1) (l'intestazione Reporting-Endpoints). Esiste un'eccezione a questo: se devi utilizzare il logging degli errori di rete, utilizza Report-To (v0). Network Error Logging al momento non è supportato nella versione 1 dell'API di reporting. Verrà sviluppato un nuovo meccanismo per il logging degli errori di rete, fino a quando non sarà disponibile, utilizza la versione 0 dell'API di reporting. Se hai bisogno della registrazione degli errori di rete insieme ad altri tipi di report, utilizza entrambi Report-To (v0) e Reporting-Endpoints (v1). La versione v0 offre la registrazione degli errori di rete, mentre la versione v1 offre report di tutti gli altri tipi.

Passi per la migrazione

Lo scopo di questa migrazione è non perdere i report che ricevevi con la versione 0.

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

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

   In questo modo, hai a disposizione:

   • Report dei client Chrome ed Edge più recenti grazie a Reporting-Endpoints (v1).
   • Report provenienti da 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 le versioni v0 e v1.

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

   Con la versione 0, puoi scegliere di impostare gli endpoint di generazione di report solo su alcune risposte e altri documenti (pagine) dell'origine utilizzeranno questo endpoint "ambientale". Con la versione 1, a causa della differenza nell'ambito, devi impostare l'intestazione Reporting-Endpoints in tutte le risposte che potrebbero generare report.

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

   Un'eccezione: se hai bisogno di report sulla registrazione degli errori di rete, mantieni Report-To fino a quando non verrà implementato un nuovo meccanismo per la registrazione degli errori di rete.

Consulta gli esempi di codice nel cookbook per la migrazione.

Passaggi per la migrazione dei 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. Ha un'ampia compatibilità con i browser, tra cui Chrome, Firefox, Safari ed Edge. I report vengono inviati con il tipo di contenuto 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 Reporting.
• Con l'API di reporting, tramite l'intestazione Report-To (legacy) o la nuova Reporting-Endpoints (v1). Questa opzione è supportata solo in Chrome ed Edge. Le richieste di report hanno lo stesso formato delle altre richieste dell'API Reporting e lo stesso tipo di contenuto application/reports+json.

L'utilizzo del primo approccio (solo report-uri) non è più consigliato e il secondo approccio offre 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 (poiché tutte le richieste di report generate tramite l'API di 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 Reporting (Report-To o meglio, Reporting-Endpoints) per ricevere report sulle violazioni del 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à considerato solo report-uri.

1. Passaggio 1 (da eseguire ora): se non l'hai ancora aggiunto, 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 con nome che utilizzerai in report-to, utilizza entrambe le intestazioni Report-To e Reporting-Endpoints. In questo modo, riceverai report sia dai client Chrome e Edge meno recenti che da quelli più recenti.

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

Consulta gli esempi di codice per questi passaggi nella migrazione dei report CSP.

Migrazione: codice di esempio

Panoramica

Se utilizzi l'API di reporting precedente (v0) per ricevere report sulle violazioni per un COOP (intestazione Cross-Origin-Opener-Policy), un COEP (Cross-Origin-Embedder-Policy) o un criterio relativo ai documenti (intestazione Document-Policy), non devi modificare queste intestazioni dei criteri durante la migrazione all'API di reporting v1. Devi eseguire la migrazione dall'intestazione Report-To precedente all'intestazione Reporting-Endpoints nuova.

Se utilizzi l'API di reporting precedente (v0) per ricevere 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 precedente (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 v0 e v1)

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 (fino a quando la maggior parte dei client Chrome ed Edge non sarà stata aggiornata) per evitare di perdere i report.

Se hai bisogno di 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 v1)

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

Questo è l'aspetto che avrà 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 versione 1 puoi comunque inviare tipi di report specifici a endpoint specifici. Tuttavia, puoi avere un solo URL per endpoint.

Osservazione di tutte le pagine

Codice precedente (con la versione 0), 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 generazione di report solo su alcune risposte. Gli altri documenti (pagine) di quell'origine utilizzano automaticamente questi endpoint ambient. Qui, gli endpoint impostati per "/" vengono utilizzati per tutte le risposte, ad esempio per page1.

Nuovo codice (con la versione 1), 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 versione 1, 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

Utilizzare solo report-uri è non più consigliato. Se il tuo codice è simile a quello riportato sopra, esegui la migrazione. Consulta gli esempi di nuovo codice riportati di seguito (in verde).

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

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

Meglio: questo codice utilizza report-to, la sostituzione più recente 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, potrebbe essere migliore: questi codici utilizzano la versione 0 dell'API di reporting (intestazione Report-To). Esegui la migrazione alla versione 1: consulta 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 la direttiva report-uri insieme alla direttiva report-to finché la direttiva report-to non sarà supportata in tutti i browser. Consulta la tabella di compatibilità del browser.

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

Per approfondire

• Monitorare l'applicazione web con l'API di reporting (post principale sull'API di reporting)
• Specifica: API di reporting precedente (v0)
• Specifiche: nuova API Reports (v1)

Grazie mille a Ian Clelland, Eiji Kitamura e Milica Mihajlija per le loro recensioni e suggerimenti su questo articolo.