Access-Control-Allow-Headers
Utilisation
Lorsqu’un navigateur émet une requête préliminaire OPTIONS, l’en-tête Access-Control-Request-Headers énumère les en-têtes hors liste blanche que le client a l’intention d’envoyer. Le serveur répond avec Access-Control-Allow-Headers pour confirmer lesquels de ces en-têtes sont acceptés.
Les en-têtes de la liste blanche CORS sont toujours autorisés et n’ont pas besoin de figurer dans cette liste. L’ensemble de la liste blanche comprend Accept, Accept-Language, Content-Language, Content-Type (avec des restrictions sur le type de média et la longueur de la valeur) et Range (avec des restrictions sur le format). Mentionner explicitement un en-tête de la liste blanche supprime les restrictions supplémentaires portant sur sa valeur.
Plusieurs noms d’en-têtes se présentent sous forme de liste séparée par des virgules.
Liste de noms d’en-têtes
Un ensemble de noms d’en-têtes séparés par des virgules que le serveur accepte dans la requête réelle.
Access-Control-Allow-Headers: Content-Type, Authorization* (caractère générique)
L’astérisque fait office de caractère générique pour les requêtes sans identifiants, autorisant n’importe quel nom d’en-tête.
Access-Control-Allow-Headers: *Remarque
Pour les requêtes avec identifiants, le caractère générique * est traité comme une chaîne littérale et non comme un joker. Chaque en-tête autorisé doit être énuméré explicitement en présence d’identifiants. L’en-tête Authorization n’est jamais couvert par le caractère générique et doit toujours être nommé explicitement.
Exemple
Une requête préliminaire demande si Content-Type et un en-tête personnalisé X-Request-ID sont autorisés. Le serveur confirme les deux.
Requête
OPTIONS /api/data HTTP/1.1
Origin: https://example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type, X-Request-IDRéponse
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type, X-Request-ID
Access-Control-Max-Age: 86400Un serveur qui utilise le caractère générique pour les requêtes sans identifiants répond avec un seul caractère.
Access-Control-Allow-Headers: *Dépannage
Les échecs de requête préliminaire liés aux en-têtes de requête produisent des erreurs dans la console et bloquent la requête réelle.
La console affiche « Request header field X is not allowed by Access-Control-Allow-Headers in preflight response. ». Le serveur n’a pas mentionné le nom de cet en-tête dans la valeur d’Access-Control-Allow-Headers. Ajoutez l’en-tête manquant à la réponse préliminaire. Dans nginx : add_header Access-Control-Allow-Headers “Content-Type, Authorization, X-Request-ID”; Dans Apache : Header set Access-Control-Allow-Headers “Content-Type, Authorization, X-Request-ID”
L’en-tête est totalement absent de la réponse préliminaire. Le serveur traite la requête OPTIONS mais n’inclut pas Access-Control-Allow-Headers dans la réponse. De nombreux frameworks exigent une configuration CORS explicite pour les routes préliminaires. Vérifiez que le gestionnaire OPTIONS ou l’intergiciel définit cet en-tête en même temps qu’Access-Control-Allow-Methods et Access-Control-Allow-Origin.
Le caractère générique * ne fonctionne pas avec les requêtes avec identifiants. Lorsque Access-Control-Allow-Credentials vaut true, le caractère générique est traité comme la chaîne littérale * et ne correspond à rien. Énumérez explicitement chaque en-tête autorisé. L’en-tête Authorization n’est jamais couvert par le caractère générique, même pour les requêtes sans identifiants, et doit toujours être nommé.
Les noms d’en-têtes semblent sensibles à la casse sur certains serveurs. Selon le protocole, les noms d’en-têtes HTTP ne sont pas sensibles à la casse, mais certains frameworks serveur effectuent une comparaison de chaînes sensible à la casse lors de la vérification de la liste d’autorisation. Une requête envoyant content-type peut échouer si le serveur ne mentionne que Content-Type. Alignez-vous sur la casse envoyée par le client, ou normalisez les deux côtés en minuscules dans la configuration CORS.
L’envoi de Content-Type: application/json déclenche une requête préliminaire inattendue. L’en-tête Content-Type n’est sur la liste blanche que pour les valeurs application/x-www-form-urlencoded, multipart/form-data et text/plain. La valeur application/json sort de la liste blanche et force une requête préliminaire. Ajoutez Content-Type à la liste Access-Control-Allow-Headers. Pour confirmer le déclenchement de la requête préliminaire, ouvrez l’onglet Network des DevTools et filtrez par méthode afin de repérer la requête OPTIONS précédant la requête réelle.