Access-Control-Allow-Credentials

Применение

Кросс-доменные запросы по умолчанию исключают учётные данные — cookie, заголовки Authorization и клиентские сертификаты TLS. Когда клиент устанавливает режим передачи учётных данных в include, сервер обязан вернуть Access-Control-Allow-Credentials со значением true, чтобы браузер открыл вызывающему скрипту тело и заголовки ответа.

Во время предварительного обмена этот заголовок сообщает, разрешено ли фактическому запросу нести учётные данные. Если ответ на предварительный запрос не содержит этого заголовка или задаёт значение, отличное от true, браузер полностью блокирует запрос с учётными данными.

Для простых CORS-запросов (тех, что обходятся без предварительного шага, например базового GET) браузер всё равно проверяет заголовок после получения ответа. Если заголовок отсутствует, ответ молча отбрасывается и никогда не доходит до вызывающего кода.

Примечание

Когда передаются учётные данные, заголовок Access-Control-Allow-Origin обязан указывать явный источник. Подстановочный знак * недопустим вместе с запросами, передающими учётные данные.

true

Единственное допустимое значение. Заголовок со значением true указывает браузеру открыть ответ при наличии учётных данных.

Access-Control-Allow-Credentials: true

Отсутствие заголовка или отправка любого другого значения даёт одинаковый эффект: браузер считает ответ не содержащим учётных данных и не передаёт тело в JavaScript.

Пример

Клиентское приложение отправляет кросс-доменный fetch с включёнными учётными данными. Сервер отвечает заголовком учётных данных, явным источником и директивой Vary, чтобы кэши различали источники.

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

При предварительном запросе для POST с учётными данными сервер подтверждает и разрешённый метод, и поддержку учётных данных.

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

Диагностика

Кросс-доменные запросы с учётными данными завершаются неудачей без видимых сообщений, когда любое звено цепочки CORS настроено неверно.

Cookie не отправляются между источниками, несмотря на то что сервер возвращает Access-Control-Allow-Credentials: true. Клиентский код должен явно включить отправку учётных данных. В Fetch API передайте credentials: ‘include’ в параметрах запроса. В XMLHttpRequest установите withCredentials = true перед вызовом send(). Без этого флага браузер удаляет cookie и заголовки Authorization из кросс-доменных запросов независимо от ответа сервера.

В консоли выводится “Cannot use wildcard in Access-Control-Allow-Origin when credentials flag is true.”. Когда Access-Control-Allow-Credentials равен true, заголовок Access-Control-Allow-Origin обязан содержать явный источник. Прочитайте входящий заголовок Origin, проверьте значение по списку разрешённых, верните совпавший источник обратно и добавьте в ответ Vary: Origin. То же правило действует для Access-Control-Allow-Headers и Access-Control-Allow-Methods: в запросах с учётными данными подстановочные знаки в этих заголовках трактуются как литеральные строки.

В вызове fetch() отсутствует credentials: ‘include’. Fetch API по умолчанию использует credentials: ‘same-origin’, что исключает учётные данные в кросс-доменных запросах. Передавайте { credentials: ‘include’ } явно. Откройте вкладку Network в DevTools и изучите заголовки запроса. Если в исходящем запросе нет заголовка Cookie, клиент не включил их отправку.

В XMLHttpRequest отсутствует withCredentials = true. Как и Fetch API, XMLHttpRequest не отправляет cookie между источниками, пока withCredentials не установлен в true. Это свойство нужно задать до вызова xhr.open() или xhr.send(). Библиотеки вроде Axios предоставляют его как { withCredentials: true } в конфигурации запроса.

Атрибут cookie SameSite блокирует кросс-доменную доставку. Современные браузеры по умолчанию используют SameSite=Lax, если атрибут SameSite не задан. Cookie с Lax не отправляются в кросс-доменных POST-запросах и запросах подресурсов. Установите SameSite=None и Secure для cookie, которые обязаны передаваться между источниками. Проверьте атрибут в DevTools в разделе Application

Cookies. Без Secure браузеры полностью отклоняют cookie с SameSite=None.

Отказ от сторонних cookie блокирует передачу учётных данных. Chrome и другие браузеры ограничивают сторонние cookie. Кросс-доменные запросы, полагающиеся на cookie, установленные другим доменом, всё чаще перестают работать. Там, где это возможно, переходите на аутентификацию по токенам с заголовком Authorization или применяйте Storage Access API, чтобы явно запрашивать доступ к cookie. Тестируйте в Chrome с включённым флагом “Third-party cookie phaseout”, чтобы выявить проблемы до выката.