Access-Control-Allow-Credentials

Uso

Las solicitudes entre orígenes excluyen por defecto las credenciales, como las cookies, las cabeceras Authorization y los certificados de cliente TLS. Cuando un cliente establece el modo de credenciales en include, el servidor debe devolver Access-Control-Allow-Credentials con el valor true para que el navegador exponga el cuerpo y las cabeceras de la respuesta al script que realiza la llamada.

Durante un intercambio de verificación previa (preflight), esta cabecera indica si la solicitud real tiene permiso para transportar credenciales. Si la respuesta de la verificación previa omite la cabecera o establece un valor distinto de true, el navegador bloquea por completo la solicitud con credenciales.

En las solicitudes CORS simples (aquellas sin paso de verificación previa, como un GET básico), el navegador sigue comprobando la cabecera tras recibir la respuesta. Si la cabecera falta, la respuesta se descarta de forma silenciosa y nunca llega al código que realizó la llamada.

Nota

Cuando se incluyen credenciales, la cabecera Access-Control-Allow-Origin debe especificar un origen explícito. El comodín * no está permitido junto con solicitudes que llevan credenciales.

true

El único valor válido. Incluir la cabecera con true indica al navegador que exponga la respuesta cuando hay credenciales presentes.

Access-Control-Allow-Credentials: true

Omitir la cabecera o enviar cualquier otro valor tiene el mismo efecto: el navegador trata la respuesta como si no llevara credenciales y oculta el cuerpo a JavaScript.

Ejemplo

Una aplicación de front-end envía un fetch entre orígenes con credenciales incluidas. El servidor responde con la cabecera de credenciales, un origen explícito y una directiva Vary para que las cachés distingan entre orígenes.

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

Durante la verificación previa de una solicitud POST con credenciales, el servidor confirma tanto el método permitido como la compatibilidad con credenciales.

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

Diagnóstico

Las solicitudes entre orígenes con credenciales fallan de forma silenciosa cuando alguna parte de la cadena CORS está mal configurada.

Las cookies no se envían entre orígenes a pesar de que el servidor devuelve Access-Control-Allow-Credentials: true. El código del lado del cliente debe optar explícitamente por enviar credenciales. En la Fetch API, pase credentials: ‘include’ en las opciones de la solicitud. En XMLHttpRequest, establezca withCredentials = true antes de llamar a send(). Sin esta marca, el navegador elimina las cookies y las cabeceras Authorization de las solicitudes entre orígenes, independientemente de la respuesta del servidor.

La consola muestra “Cannot use wildcard in Access-Control-Allow-Origin when credentials flag is true.”. Cuando Access-Control-Allow-Credentials es true, la cabecera Access-Control-Allow-Origin debe contener un origen explícito. Lea la cabecera Origin entrante, valide el valor contra una lista de permitidos, devuelva el origen coincidente y añada Vary: Origin a la respuesta. La misma regla se aplica a Access-Control-Allow-Headers y Access-Control-Allow-Methods: en las solicitudes con credenciales, los comodines de esas cabeceras se tratan como cadenas literales.

La llamada a fetch() no incluye credentials: ‘include’. La Fetch API usa por defecto credentials: ‘same-origin’, lo que excluye las credenciales en las solicitudes entre orígenes. Pase { credentials: ‘include’ } de forma explícita. Revise la pestaña Network de DevTools e inspeccione las cabeceras de la solicitud. Si la cabecera Cookie no está presente en la solicitud saliente, el cliente no optó por incluirla.

XMLHttpRequest sin withCredentials = true. Al igual que la Fetch API, XMLHttpRequest no envía cookies entre orígenes a menos que withCredentials se establezca en true. Esta propiedad debe fijarse antes de llamar a xhr.open() o xhr.send(). Librerías como Axios lo exponen como { withCredentials: true } en la configuración de la solicitud.

El atributo de cookie SameSite bloquea la entrega entre orígenes. Los navegadores modernos usan por defecto SameSite=Lax cuando no se establece ningún atributo SameSite. Las cookies Lax no se envían en solicitudes POST ni de subrecursos entre orígenes. Establezca SameSite=None y Secure en las cookies que deban viajar entre orígenes. Verifique el atributo en DevTools, en Application

Cookies. Sin Secure, los navegadores rechazan por completo las cookies con SameSite=None.

La eliminación progresiva de las cookies de terceros bloquea las credenciales. Chrome y otros navegadores están restringiendo las cookies de terceros. Las solicitudes entre orígenes que dependen de cookies establecidas por un dominio distinto sufren fallos cada vez más frecuentes. Siempre que sea posible, migre a la autenticación basada en tokens usando la cabecera Authorization, o adopte la Storage Access API para solicitar acceso a las cookies de forma explícita. Pruebe en Chrome con la marca “Third-party cookie phaseout” activada para detectar problemas antes del despliegue.