Migreren naar Reporting API v1

Er is een nieuwe versie van de Reporting API beschikbaar. Het is meer privé en wordt waarschijnlijker ondersteund in alle browsers.

Maud Nalpas

De Reporting API informeert u over fouten die op uw site optreden wanneer bezoekers deze gebruiken. Het geeft u inzicht in browserinterventies, browsercrashes, schendingen van het Content-Security-beleid, COOP/COEP-schendingen, beëindigingswaarschuwingen en meer.

Er is een nieuwe versie van de Reporting API beschikbaar. De nieuwe API is slanker en zal waarschijnlijk in alle browsers worden ondersteund.

Samenvatting

Site-ontwikkelaars

Als u al over rapportagefunctionaliteit voor uw site beschikt : migreer naar v1 met behulp van de nieuwe header ( Reporting-Endpoints ), maar behoud de oude header nog een tijdje ( Report-To ). Zie Migratie: voorbeeldcode .

Als u zojuist rapportagefunctionaliteit aan uw site toevoegt : gebruik alleen de nieuwe header ( Reporting-Endpoints ).

⚠️ Zorg er in beide gevallen voor dat u de header Reporting-Endpoints instelt voor alle reacties die mogelijk rapporten genereren.

Ontwikkelaars van rapportageservices

Als u een eindpuntservice onderhoudt of uw eigen service exploiteert, kunt u meer verkeer verwachten als u of externe ontwikkelaars migreren naar de Reporting API v1 ( Reporting-Endpoints header).

Blijf lezen voor details en voorbeeldcode!

Netwerkfoutregistratie

Er zal een nieuw mechanisme voor netwerkfoutregistratie worden ontwikkeld. Zodra dat beschikbaar komt, schakelt u over van Reporting API v0 naar dat nieuwe mechanisme.

Demo en code

• Demosite: nieuwe rapportage-API (v1)
• Code voor de demosite

Verschillen tussen v0 en v1

Wat verandert er

• Het API-oppervlak is anders.

 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

• De reikwijdte van het rapport is anders.

• Beide API's ondersteunen dezelfde rapporttypen, met één uitzondering: v1 ondersteunt geen netwerkfoutrapporten . Lees meer in de migratiestappen .
• v0 wordt niet ondersteund in browsers en zal dit ook niet worden ondersteund. Het is waarschijnlijker dat v1 in de toekomst door meerdere browsers wordt ondersteund.

Wat onveranderd blijft

• Het formaat en de structuur van de rapporten zijn ongewijzigd.
• Het verzoek dat door de browser naar het eindpunt wordt verzonden, blijft een POST verzoek van Content-type application/reports+json .
• Het toewijzen van bepaalde eindpunten aan bepaalde rapporttypen wordt ondersteund in zowel v0 als v1.
• De rol van het default blijft ongewijzigd.

• De Reporting API v1 heeft geen invloed op de ReportingObserver . ReportingObserver blijft toegang krijgen tot alle waarneembare rapporten, en hun formaat is identiek.

Alle verschillen tussen v0 en v1

Eindpuntontwikkelaars: verwacht meer verkeer

Als u uw eigen server als rapportage-eindpunt hebt ingesteld, of als u een rapportverzamelaar als service ontwikkelt of onderhoudt, kunt u meer verkeer naar dat eindpunt verwachten.

Dit komt omdat rapporten niet in batches worden verwerkt met de Reporting API v1, zoals wel het geval is met de Reporting API v0. Naarmate applicatieontwikkelaars beginnen te migreren naar de Reporting API v1, zal het aantal rapporten dus vergelijkbaar blijven, maar zal het aantal verzoeken aan de eindpuntserver toenemen.

Applicatieontwikkelaars: migreren naar Reporting-Endpoints (v1)

Wat moet je doen?

Het gebruik van de nieuwe Reporting API (v1) heeft verschillende voordelen ✅:

• Browsersignalen zijn positief , wat betekent dat ondersteuning voor meerdere browsers kan worden verwacht voor v1 (in tegenstelling tot v0 die alleen wordt ondersteund in Chrome en Edge).
• De API is slanker.
• Er wordt tooling ontwikkeld rond de nieuwe Reporting API (v1).

Met dit in gedachten:

• Als uw site al gebruikmaakt van de Reporting API v0 met de Report-To header, migreer dan naar de Reporting API v1 (zie de migratiestappen ). Als uw site al rapportagefunctionaliteit gebruikt voor schendingen van het inhoudsbeveiligingsbeleid, controleer dan de specifieke migratiestappen voor CSP-rapportage .
• Als uw site de Reporting API nog niet gebruikt en u nu rapportagefunctionaliteit toevoegt: gebruik de nieuwe Reporting API (v1) (de Reporting-Endpoints header). Hierop bestaat één uitzondering : als u Network Error Logging wilt gebruiken, gebruik dan Report-To (v0). Netwerkfoutregistratie wordt momenteel niet ondersteund in de Reporting API v1. Er zal een nieuw mechanisme voor netwerkfoutregistratie worden ontwikkeld⏤totdat dit beschikbaar is, kunt u de Reporting API v0 gebruiken. Als u netwerkfoutregistratie nodig heeft naast andere rapporttypen, gebruikt u zowel Report-To (v0) als Reporting-Endpoints (v1). v0 biedt u netwerkfoutregistratie en v1 geeft u rapporten van alle andere typen.

Migratie stappen

Uw doel bij deze migratie is om geen rapporten kwijt te raken die u voorheen met v0 kreeg.

1. Stap 1 (nu doen) : Gebruik beide headers: Report-To (v0) en Reporting-Endpoints (v1).

   Hiermee krijg je:

   • Rapporten van nieuwere Chrome- en Edge-clients dankzij Reporting-Endpoints (v1).
   • Rapporten van oudere Chrome- en Edge-clients dankzij Report-To (v0).

   Browserinstanties die Reporting-Endpoints ondersteunen, zullen Reporting-Endpoints gebruiken, en instanties die dat niet doen, zullen terugvallen op Report-To . Het aanvraag- en rapportformaat is hetzelfde voor v0 en v1.

2. Stap 2 (nu doen): Zorg ervoor dat de header Reporting-Endpoints is ingesteld op alle reacties die mogelijk rapporten genereren.

   Met v0 kunt u ervoor kiezen om rapportage-eindpunten alleen voor bepaalde reacties in te stellen, en andere documenten (pagina's) op die oorsprong zouden dit 'omgevings'-eindpunt gebruiken. Met v1 moet u vanwege het verschil in bereik de header Reporting-Endpoints instellen voor alle reacties die mogelijk rapporten genereren.

3. Stap 3 (begin later): Zodra alle of de meeste van uw gebruikers zijn bijgewerkt naar latere Chrome- of Edge-installaties (96 en hoger), verwijdert u Report-To (v0) en behoudt u alleen Reporting-Endpoints .

   Eén uitzondering: als u rapporten over het loggen van netwerkfouten nodig heeft, kunt u Report-To gebruiken totdat er een nieuw mechanisme voor het loggen van netwerkfouten beschikbaar is.

Zie codevoorbeelden in het migratiekookboek .

Migratiestappen voor CSP-rapportage

Er zijn twee manieren waarop rapporten over schendingen van het Content-Security-beleid kunnen worden geconfigureerd:

• Met alleen de CSP-header via de report-uri richtlijn. Dit heeft brede browserondersteuning, in Chrome, Firefox, Safari en Edge. Rapporten worden verzonden met het inhoudstype application/csp-report en hebben een indeling die specifiek is voor CSP. Deze rapporten worden 'CSP Level 2-rapporten' genoemd en zijn niet afhankelijk van de Reporting API.
• Met de Reporting API is dat via Report-To header (legacy) of de nieuwere Reporting-Endpoints (v1). Dit wordt alleen ondersteund in Chrome en Edge. Rapportaanvragen hebben dezelfde indeling als andere Reporting API-aanvragen en hetzelfde inhoudstype application/reports+json .

Het gebruik van de eerste benadering (alleen report-uri ) wordt niet langer aanbevolen en het gebruik van de tweede benadering heeft enkele voordelen. Het stelt u met name in staat om op één manier rapportage in te stellen voor alle rapporttypen en om een ​​generiek eindpunt in te stellen (omdat alle rapportverzoeken die via de Reporting API⏤CSP en andere⏤worden gegenereerd dezelfde indeling application/reports+json .

Slechts enkele browsers ondersteunen echter report-to . Het wordt daarom aanbevolen om report-uri te gebruiken naast de Reporting API-aanpak ( Report-To of beter, Reporting-Endpoints ) om CSP-schendingsrapporten van meerdere browsers te ontvangen. In een browser die report-uri en report-to herkent, wordt report-uri genegeerd als report-to aanwezig is. In een browser die alleen report-uri herkent, wordt alleen report-uri in aanmerking genomen.

1. Stap 1 (nu doen) : Als u het nog niet heeft toegevoegd, voegt u report-to naast report-uri . Browsers die alleen report-uri ondersteunen (Firefox) zullen report-uri gebruiken, en browsers die ook report-to ondersteunen (Chrome, Edge) zullen report-to gebruiken. Als u de benoemde eindpunten wilt opgeven die u in report-to gaat gebruiken, gebruikt u de headers Report-To en Reporting-Endpoints . Dit zorgt ervoor dat u rapporten ontvangt van zowel oudere als nieuwere Chrome- en Edge-clients.

2. Stap 3 (begin later): Zodra alle of de meeste van uw gebruikers zijn bijgewerkt naar latere Chrome- of Edge-installaties (96 en hoger), verwijdert u Report-To (v0) en behoudt u alleen Reporting-Endpoints . Bewaar report-uri zodat u nog steeds rapporten ontvangt voor browsers die dit alleen ondersteunen.

Zie codevoorbeelden voor deze stappen bij de migratie van CSP-rapportage .

Migratie: voorbeeldcode

Overzicht

Als u de verouderde Reporting API (v0) gebruikt om overtredingsrapporten te ontvangen voor een COOP ( Cross-Origin-Opener-Policy header), een COEP ( Cross-Origin-Embedder-Policy ) of een documentbeleid ( Document-Policy header ): u hoeft deze beleidsheaders zelf niet te wijzigen wanneer u migreert naar Reporting API v1. Wat u wel nodig heeft, is migreren van de oude Report-To header naar de nieuwe Reporting-Endpoints header.

Als u de oude Reporting API (v0) gebruikt om schendingsrapporten te ontvangen voor een CSP ( Content-Security-Policy header), moet u mogelijk uw Content-Security-Policy aanpassen als onderdeel van uw migratie naar de nieuwe Reporting API ( v1).

Basismigratie

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"

Houd er rekening mee dat u met v1 nog steeds specifieke rapporttypen naar specifieke eindpunten kunt verzenden. Maar u kunt slechts één URL per eindpunt hebben.

Alle pagina's observeren

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

Migratie van CSP-rapportage

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: ...

Verder lezen

• Monitor uw webapplicatie met de Reporting API (hoofdpost over de Reporting API)
• Specificatie: verouderde Reporting API (v0)
• Specificatie: nieuwe Reporting API (v1)

Hero-afbeelding door Nine Koepfer / @enka80 op Unsplash , bewerkt. Met veel dank aan Ian Clelland, Eiji Kitamura en Milica Mihajlija voor hun recensies en suggesties voor dit artikel.