Esegui la migrazione all'API di reporting v1

È disponibile una nuova versione dell'API Reporting. È più privato e ha maggiori probabilità di essere supportato su più browser.

Maud Nalpas

L'API Reporting ti informa sugli 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 Reporting. La nuova API è più snella e ha maggiori probabilità di essere supportata su più browser.

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 dettagli e codice di esempio.

Registrazione degli errori di rete

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 la versione 0 e la versione 1

Che cosa cambia

• L'interfaccia API è diversa.

 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

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

• L'ambito del report è diverso.

• 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 rimangono invariati.
• 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 rimane invariato.

• La versione 1 dell'API di reporting non influisce 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

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 l'API Reporting 1.0 come con l'API Reporting 0.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) presenta diversi vantaggi ✅:

• Gli indicatori del browser sono positivi, il che significa che si può prevedere il supporto multibrowser per la versione 1 (a differenza della versione 0, supportata solo in Chrome e Edge).
• L'API è più snella.
• Stiamo sviluppando strumenti per la 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). La registrazione degli errori di rete attualmente non è supportata nella versione 1 dell'API Reporting. Verrà sviluppato un nuovo meccanismo per la registrazione degli errori di rete. finché non sarà disponibile, utilizza la versione 0 dell'API 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 e 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.

1. Passaggio 1 (da eseguire 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 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 di ambito, devi impostare l'intestazione Reporting-Endpoints su 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 finché 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 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. 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, mentre il 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 (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 quelli 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 successive), rimuovi Report-To (v0) e mantieni solo Reporting-Endpoints. Mantieni attivoreport-uri per continuare a ricevere i 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

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

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" }] }

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

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

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

// 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(...)
});

Migrazione dei report CSP

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

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

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

Per approfondire

• Monitora la tua applicazione web con l'API Reports (post principale sull'API Reports)
• Specifiche: API Reports precedente (v0)
• Specifiche: nuova API Reporting (v1)

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