Access-Control-Allow-Credentials

Utilisation

Par défaut, les requêtes multi-origines excluent les identifiants tels que les cookies, les en-têtes Authorization et les certificats client TLS. Lorsqu’un client règle le mode d’identifiants sur include, le serveur doit renvoyer Access-Control-Allow-Credentials avec la valeur true pour que le navigateur expose le corps et les en-têtes de la réponse au script appelant.

Lors d’un échange de préflight, cet en-tête indique si la requête réelle est autorisée à transporter des identifiants. Si la réponse de préflight omet l’en-tête ou lui donne une valeur autre que true, le navigateur bloque entièrement la requête avec identifiants.

Pour les requêtes CORS simples (celles qui ne comportent pas d’étape de préflight, comme un GET basique), le navigateur vérifie malgré tout l’en-tête après réception de la réponse. Si l’en-tête est absent, la réponse est silencieusement rejetée et n’atteint jamais le code appelant.

Remarque

Lorsque des identifiants sont inclus, l’en-tête Access-Control-Allow-Origin doit indiquer une origine explicite. Le joker * n’est pas autorisé avec les requêtes porteuses d’identifiants.

true

La seule valeur valide. Inclure l’en-tête avec true indique au navigateur d’exposer la réponse lorsque des identifiants sont présents.

Access-Control-Allow-Credentials: true

Omettre l’en-tête ou envoyer toute autre valeur produit le même effet : le navigateur traite la réponse comme dépourvue d’identifiants et en retient le corps vis-à-vis de JavaScript.

Exemple

Une application front-end émet une requête fetch multi-origine avec identifiants. Le serveur répond avec l’en-tête d’identifiants, une origine explicite et une directive Vary afin que les caches distinguent les origines.

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Credentials: true
Vary: Origin

Lors du préflight d’une requête POST avec identifiants, le serveur confirme à la fois la méthode autorisée et la prise en charge des identifiants.

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 3600
Vary: Origin

Dépannage

Les requêtes multi-origines avec identifiants échouent silencieusement dès qu’un maillon de la chaîne CORS est mal configuré.

Les cookies ne sont pas envoyés en multi-origine alors que le serveur renvoie Access-Control-Allow-Credentials: true. Le code côté client doit explicitement demander l’envoi des identifiants. Dans l’API Fetch, passez credentials: ‘include’ dans les options de la requête. Dans XMLHttpRequest, définissez withCredentials = true avant d’appeler send(). Sans cet indicateur, le navigateur retire les cookies et les en-têtes Authorization des requêtes multi-origines, quelle que soit la réponse du serveur.

La console affiche « Cannot use wildcard in Access-Control-Allow-Origin when credentials flag is true. » Lorsque Access-Control-Allow-Credentials vaut true, l’en-tête Access-Control-Allow-Origin doit contenir une origine explicite. Lisez l’en-tête Origin entrant, validez la valeur par rapport à une liste d’autorisation, renvoyez l’origine correspondante et ajoutez Vary: Origin à la réponse. La même règle s’applique à Access-Control-Allow-Headers et Access-Control-Allow-Methods : dans les requêtes avec identifiants, les jokers y sont traités comme des chaînes littérales.

L’appel fetch() n’inclut pas credentials: ‘include’. L’API Fetch utilise par défaut credentials: ‘same-origin’, ce qui exclut les identifiants sur les requêtes multi-origines. Passez explicitement { credentials: ‘include’ }. Consultez l’onglet Network des DevTools et inspectez les en-têtes de requête. Si l’en-tête Cookie est absent de la requête sortante, le client n’a pas activé l’option.

withCredentials = true manquant sur XMLHttpRequest. Comme pour l’API Fetch, XMLHttpRequest n’envoie pas de cookies en multi-origine tant que withCredentials n’est pas défini à true. Cette propriété doit être définie avant l’appel à xhr.open() ou xhr.send(). Des bibliothèques comme Axios l’exposent sous la forme { withCredentials: true } dans la configuration de la requête.

L’attribut de cookie SameSite bloque la transmission multi-origine. Les navigateurs modernes appliquent par défaut SameSite=Lax lorsqu’aucun attribut SameSite n’est défini. Les cookies Lax ne sont pas envoyés lors de requêtes POST ou de sous-ressources multi-origines. Définissez SameSite=None et Secure sur les cookies qui doivent circuler entre origines. Vérifiez l’attribut dans les DevTools, sous Application

Cookies. Sans Secure, les navigateurs rejettent purement et simplement les cookies SameSite=None.

La suppression progressive des cookies tiers bloque les identifiants. Chrome et d’autres navigateurs restreignent les cookies tiers. Les requêtes multi-origines qui reposent sur des cookies déposés par un autre domaine se cassent de plus en plus souvent. Lorsque c’est possible, passez à une authentification par jeton utilisant l’en-tête Authorization, ou adoptez la Storage Access API pour demander explicitement l’accès aux cookies. Testez dans Chrome avec l’indicateur « Third-party cookie phaseout » activé afin de révéler les problèmes avant le déploiement.