Report-To vs Reporting-Endpoints, migrer hors du header déprécié
CentralCSP Team ·
Dernière mise à jour:
Il existe deux générations du header HTTP qui indique au navigateur où envoyer les
rapports, et recopier le mauvais depuis un vieux tutoriel est une façon courante
de se retrouver avec des rapports qui n'arrivent jamais, sans le moindre signal.
Report-To est arrivé le premier et il est désormais déprécié. Reporting-Endpoints
l'a remplacé, en plus simple. Pour presque tout, utilisez Reporting-Endpoints ; la
seule exception, le Network Error Logging, a encore besoin de l'ancien header. Voici ce
qui a changé et comment migrer.
C'est l'équivalent, côté header, de report-uri vs report-to, qui porte sur les directives CSP. Couche différente, même direction : la plateforme se consolide autour d'un seul mécanisme de reporting.
Les deux headers côte à côte
Report-To (v0) déclare des groupes d'endpoints en JSON, avec plusieurs URL par
groupe, une durée de cache et des poids de répartition de charge. Il est expressif, et
c'est exactement cette expressivité qui n'a jamais été normalisée.
Report-To: { "group": "csp-endpoint", "max_age": 10886400,
"endpoints": [ { "url": "https://<Endpoint-ID>.report.centralcsp.com" } ] }Reporting-Endpoints (v1) déclare de simples paires nom et URL, une seule URL par nom,
valables uniquement sur la réponse qui les porte. Pas de groupes, pas de cache,
pas de bascule de secours, juste un nom associé à une URL.
Reporting-Endpoints: csp-endpoint="https://<Endpoint-ID>.report.centralcsp.com"Une politique référence le nom de la même façon dans les deux générations : report-to csp-endpoint en CSP, ou un paramètre report-to="csp-endpoint" sur COOP et COEP.
Migrer consiste donc surtout à remplacer le header qui déclare l'endpoint, pas les
politiques qui l'utilisent.
Report-To (v0) | Reporting-Endpoints (v1) | |
|---|---|---|
| Statut | ❌ Déprécié, non standard | ✅ Le standard W3C Reporting API |
| Syntaxe | Objet JSON par groupe | Paires nom / URL en structured fields |
| URL par nom | Plusieurs, avec poids et bascule | Exactement une |
| Portée | Mise en cache pour max_age | La réponse sur laquelle il est servi |
| Support navigateur | Chromium uniquement | Chrome, Edge, Firefox, Safari |
| Porte CSP, COOP, COEP, deprecation, intervention, crash | ✅ Oui | ✅ Oui |
| Porte Network Error Logging (NEL) | ✅ Oui | ❌ Non, NEL exige encore v0 |
| À utiliser pour | NEL, et rien d'autre | Tout le reste |
Ce qui a changé et pourquoi
La spécification Reporting du W3C ne définit que Reporting-Endpoints. Report-To
était un mécanisme de l'ère Chromium qui n'est jamais devenu un standard, ce qui
explique pourquoi MDN le marque à la fois déprécié et non standard, et pourquoi il
n'a jamais existé que dans les navigateurs Chromium. La v1 a abandonné le modèle de
groupes, de cache et de répartition de charge au profit d'un header plus simple, par
réponse, que les autres moteurs de navigateur étaient prêts à adopter. Ce header-là est
déjà multi-navigateurs et fonctionne dans les versions actuelles de
Chrome, Edge, Firefox et Safari. Tout le détail est sur la
référence Report-To vs Reporting-Endpoints.
La confusion report-to à quatre entrées
La difficulté vient surtout du nommage. L'expression « report-to » apparaît à quatre endroits différents, et on finit vite par en câbler deux qui ne vont pas ensemble. Gardez-les bien distincts :
- le header
Reporting-Endpoints(moderne, déclare des endpoints) - le header
Report-To(déprécié, déclare des endpoints) - la directive CSP
report-to(nomme un endpoint depuis l'intérieur d'une politique) - le paramètre
report-to=sur les headers COOP et COEP (nomme un endpoint pour cette politique)
La directive et le paramètre ne font que référencer un nom ; ce nom doit être déclaré par l'un des deux headers sur la même réponse.
Le seul cas où vous avez encore besoin de Report-To
Le Network Error Logging (NEL)
fait exception. Reporting-Endpoints ne le prend pas en charge : le header NEL
nomme un groupe qui doit être défini dans un header Report-To. Tant qu'un remplaçant
n'existe pas, tout site utilisant NEL conserve Report-To à cette seule fin. Tout le
reste, CSP, COOP, COEP, deprecations, interventions, crashs, devrait passer à
Reporting-Endpoints.
Comment migrer
La migration est peu risquée : les deux headers n'entrent pas en conflit,
et comme Reporting-Endpoints est déjà multi-navigateurs, rien ne justifie
d'attendre. Envoyez Reporting-Endpoints partout, et ne conservez Report-To que sur
les réponses qui envoient aussi le header NEL. Par prudence pendant le
basculement, envoyez les deux quelque temps et vérifiez que les rapports arrivent
toujours avant de retirer l'ancien. Voir aussi où vont les rapports du navigateur
et comment les recevoir. CentralCSP accepte les
rapports des deux headers sur un seul endpoint,
vous pouvez donc faire la transition progressivement sans trou dans vos données.
Étapes suivantes
- Câblez le header moderne dans comment configurer la Reporting API.
- Découvrez le flux d'erreurs réseau dans qu'est-ce que NEL.
- Voir le rapport d'erreur réseau.
Comme NEL vous oblige à garder les deux headers pour l'instant, vous vous retrouvez en pratique avec deux déclarations qui pointent vers un seul collecteur. Un site CentralCSP vous donne une unique URL d'endpoint à nommer dans les deux, si bien que les flux v0 et v1 arrivent au même endroit et que vous n'avez pas deux stocks de rapports à réconcilier pendant la migration.
Collectez chaque type de rapport sur un seul endpoint.