Explicateur d’en-têtes CORS

Le CORS Header Explainer fournit une référence interactive et un validateur de configuration pour les en-têtes Cross-Origin Resource Sharing (CORS), vous aidant à comprendre, déboguer et corriger les erreurs CORS sans cycles de déploiement par essais et erreurs. Saisissez l'origine de votre requête, la méthode et les en-têtes personnalisés, accompagnés des en-têtes de réponse CORS du serveur, et voyez instantanément si le navigateur autoriserait ou bloquerait la requête -- avec une explication claire de la raison.

Comprendre CORS

Si vous avez déjà vu le message "Access to XMLHttpRequest has been blocked by CORS policy" dans la console de votre navigateur, vous avez rencontré l'un des mécanismes de sécurité les plus courants et les plus déroutants du web. CORS signifie Cross-Origin Resource Sharing, et il existe pour protéger les utilisateurs contre les sites web malveillants qui tentent d'effectuer des requêtes vers d'autres sites au nom de l'utilisateur. Sans CORS, n'importe quelle page web que vous visitez pourrait silencieusement envoyer des requêtes à l'API de votre banque en utilisant votre session connectée -- CORS empêche cela en exigeant que le serveur de la banque autorise explicitement la réception de requêtes provenant d'autres origines.

Une origine est définie par la combinaison du schéma, de l'hôte et du port : https://app.example.com et https://api.example.com sont des origines différentes même si elles partagent le même domaine racine. Lorsque votre JavaScript frontend sur https://app.example.com effectue une requête fetch vers https://api.example.com/data, le navigateur vérifie si le serveur API a envoyé les bons en-têtes CORS indiquant qu'il autorise les requêtes depuis https://app.example.com. Si les en-têtes sont manquants ou incorrects, le navigateur bloque la réponse et l'empêche d'atteindre votre JavaScript, même si le serveur a effectivement traité la requête et renvoyé des données.

La confusion autour de CORS vient de sa conception en couches. Les requêtes simples -- GET ou POST basiques avec des en-têtes standard -- passent directement, et le navigateur vérifie les en-têtes CORS sur la réponse. Mais toute requête utilisant des en-têtes personnalisés, des types de contenu non standard ou des méthodes comme PUT ou DELETE déclenche une vérification preflight : le navigateur envoie d'abord une requête OPTIONS pour demander au serveur s'il acceptera la vraie requête. Le serveur doit répondre à ce preflight avec les bons en-têtes Access-Control-Allow-* avant que le navigateur n'envoie la requête réelle. Cet outil simule les deux scénarios pour que vous puissiez valider votre configuration avant le déploiement.

Comment vérifier une configuration CORS

1. Saisissez l'origine de la requête (par exemple, https://app.example.com), la méthode HTTP et les en-têtes personnalisés que votre frontend envoie.
2. Saisissez les en-têtes de réponse CORS du serveur (Access-Control-Allow-Origin, Access-Control-Allow-Methods, etc.).
3. Cliquez sur Vérifier pour simuler la validation CORS du navigateur.
4. Consultez le résultat : l'outil explique si la requête serait autorisée ou bloquée et identifie la raison exacte de tout échec.

Exemples d'en-têtes CORS

Requête simple (autorisée)

Résultat : Autorisée. L'origine correspond exactement.

Requête preflight avec en-têtes personnalisés (autorisée)

Résultat : Autorisée. L'origine, la méthode et les en-têtes correspondent tous. Le preflight est mis en cache pour 24 heures.

Requête avec credentials (bloquée)

Résultat : Bloquée. Lorsque Access-Control-Allow-Credentials est true, l'en-tête Access-Control-Allow-Origin ne peut pas être le joker * -- il doit spécifier l'origine exacte.

Quand utiliser le CORS Header Explainer

• Débogage des erreurs CORS dans la console du navigateur -- Collez les détails de votre requête et les en-têtes du serveur pour découvrir exactement pourquoi le navigateur bloque la requête.
• Configuration CORS d'une API -- Validez vos en-têtes Access-Control-* avant le déploiement en production.
• Configuration des en-têtes CDN ou reverse proxy -- Testez le transfert des en-têtes CORS lors de l'utilisation de CloudFront, Cloudflare ou nginx comme proxy.
• Comprendre les requêtes preflight vs. simples -- Apprenez quelles caractéristiques de requête déclenchent une requête preflight OPTIONS.
• Résolution de problèmes de credentials et cookies -- Diagnostiquez pourquoi les cookies ou les en-têtes Authorization ne sont pas envoyés dans les requêtes cross-origin.
• Formation et documentation -- Utilisez le vérificateur interactif comme outil pédagogique pour les développeurs qui découvrent CORS.

Comment fonctionne CORS

Requêtes simples vs. requêtes preflight

Les navigateurs classifient les requêtes cross-origin en deux catégories :

Les requêtes simples sont envoyées directement sans vérification preflight. Une requête est "simple" lorsqu'elle utilise GET, HEAD ou POST avec uniquement des en-têtes standard (Accept, Accept-Language, Content-Language, Content-Type limité à application/x-www-form-urlencoded, multipart/form-data ou text/plain).

Les requêtes preflight sont déclenchées pour tout ce qui sort des critères de requête simple. Le navigateur envoie d'abord une requête OPTIONS, et le serveur doit répondre avec les en-têtes Access-Control-Allow-* appropriés avant que la requête réelle ne soit envoyée.

Référence des en-têtes CORS

Erreurs CORS courantes

• Définir Access-Control-Allow-Origin: * avec Access-Control-Allow-Credentials: true -- cette combinaison est explicitement interdite par la spécification.
• Oublier d'inclure Content-Type dans Access-Control-Allow-Headers lors de l'envoi de JSON -- application/json n'est pas un type de contenu "simple".
• Ne pas gérer la méthode preflight OPTIONS côté serveur, ce qui entraîne une réponse 405 Method Not Allowed.
• Omettre Access-Control-Expose-Headers et se demander pourquoi JavaScript ne peut pas lire les en-têtes de réponse personnalisés.

Flux de validation CORS

Navigateur                                 Serveur
  |                                          |
  |-- Est-ce une requête simple ? ---------->|
  |   (GET/HEAD/POST, en-têtes standard)     |
  |                                          |
  |   OUI : Envoyer la requête directement   |
  |   NON : Envoyer d'abord un OPTIONS       |
  |                                          |
  |<--- Réponse preflight -------------------|
  |   Access-Control-Allow-Origin: ...       |
  |   Access-Control-Allow-Methods: ...      |
  |   Access-Control-Allow-Headers: ...      |
  |                                          |
  |-- Vérif : L'origine correspond ? ------->|
  |-- Vérif : La méthode est autorisée ? --->|
  |-- Vérif : Les en-têtes sont autorisés ?->|
  |                                          |
  |   TOUT OK : Envoyer la vraie requête     |
  |   ÉCHEC : Bloquer et journaliser erreur  |

Conseils pratiques pour la configuration CORS

L'approche la plus sûre pour la configuration CORS est de commencer avec les paramètres les plus restrictifs et de n'ouvrir que ce dont votre application a besoin. Commencez par spécifier les origines exactes qui doivent avoir accès plutôt que d'utiliser *. Si votre frontend est sur https://app.example.com, définissez Access-Control-Allow-Origin: https://app.example.com explicitement. Cela empêche tout autre site d'effectuer des requêtes cross-origin vers votre API. Si vous devez supporter plusieurs origines, implémentez une vérification dynamique d'origine côté serveur -- lisez l'en-tête de requête Origin, vérifiez-le par rapport à votre liste d'autorisation, et renvoyez-le dans la réponse.

La mise en cache des preflights est une optimisation souvent négligée. Sans Access-Control-Max-Age, le navigateur envoie une requête preflight OPTIONS avant chaque requête cross-origin. Sur une application qui effectue des appels API fréquents, cela double le nombre de requêtes. Définir Access-Control-Max-Age: 3600 (1 heure) indique au navigateur de mettre en cache le résultat du preflight, éliminant les requêtes OPTIONS redondantes. Notez que la plupart des navigateurs plafonnent cette valeur à environ 7 200 secondes (2 heures), et Chrome la plafonne à 2 heures même si vous définissez une valeur plus élevée.

Lorsque votre API doit retourner des en-têtes de réponse personnalisés que JavaScript doit pouvoir lire (comme les informations de pagination dans X-Total-Count ou les identifiants de requête dans X-Request-ID), vous devez les lister dans Access-Control-Expose-Headers. Par défaut, JavaScript ne peut lire qu'un petit ensemble d'en-têtes de réponse "CORS-safelisted" : Cache-Control, Content-Language, Content-Type, Expires, Last-Modified et Pragma. Tout en-tête personnalisé est invisible pour votre code frontend à moins de l'exposer explicitement. C'est une source fréquente de confusion lors du débogage de l'affichage de la pagination ou des limites de débit.

Questions fréquentes

Pourquoi ma requête fonctionne-t-elle dans Postman mais échoue dans le navigateur ?

Postman et les autres clients API n'appliquent pas CORS car CORS est un mécanisme de sécurité propre au navigateur. La politique de même origine est appliquée par le navigateur pour protéger les utilisateurs contre les scripts malveillants. Les requêtes serveur-à-serveur ne sont pas affectées par CORS.

Puis-je utiliser Access-Control-Allow-Origin: * avec des cookies ?

Non. Lorsque la requête inclut des credentials (cookies, authentification HTTP), le serveur doit répondre avec l'origine exacte de la requête, et non *. Définissez Access-Control-Allow-Origin: https://app.example.com et Access-Control-Allow-Credentials: true ensemble.

Qu'est-ce que Access-Control-Max-Age et dois-je le définir ?

Il indique au navigateur combien de temps mettre en cache la réponse preflight. Sans cela, le navigateur envoie une requête OPTIONS avant chaque requête cross-origin. Le définir à 86400 (24 heures) réduit significativement la surcharge des preflights. La plupart des navigateurs le plafonnent à 7 200 secondes (2 heures) quelle que soit la valeur que vous définissez.

Pourquoi ai-je une erreur CORS alors que le serveur renvoie un 200 ?

CORS est appliqué par le navigateur, pas par le serveur. Le serveur traite la requête et envoie une réponse 200, mais si la réponse ne contient pas le bon en-tête Access-Control-Allow-Origin, le navigateur empêche JavaScript d'accéder aux données de la réponse. La requête réussit côté serveur -- vous ne pouvez simplement pas lire le résultat depuis votre frontend.

Comment gérer CORS pour les connexions WebSocket ?

Les connexions WebSocket n'utilisent pas CORS. La poignée de main HTTP initiale qui passe en WebSocket n'est pas soumise au preflight CORS. Cependant, vous devriez tout de même valider l'en-tête Origin côté serveur lors de la poignée de main WebSocket pour empêcher le détournement de WebSocket cross-origin.

Puis-je utiliser CORS pour restreindre quels serveurs peuvent appeler mon API ?

Non. CORS ne restreint que les requêtes basées sur le navigateur. N'importe quel serveur, script ou outil en ligne de commande peut appeler votre API directement sans restrictions CORS. Pour l'authentification serveur-à-serveur, utilisez des clés API, des tokens OAuth ou du TLS mutuel. CORS est spécifiquement une fonctionnalité de sécurité du navigateur, pas un mécanisme de contrôle d'accès général.

Outils associés

• HTTP Header Formatter - Analyser et formater les en-têtes HTTP, y compris les en-têtes CORS
• HTTP Status Code Lookup - Rechercher les codes de statut retournés lors des échecs de preflight
• Cookie Header Parser - Analyser les cookies qui interagissent avec les paramètres de credentials CORS
• curl Command Builder - Construire des commandes curl pour tester les endpoints avec CORS activé
• MIME Type Lookup - Rechercher les valeurs Content-Type qui affectent les décisions CORS simple vs. preflight