JavaScript свойство XMLHttpRequest.withCredentials

Определение и применение

JavaScript свойство withCredentials объекта XMLHttpRequest соответствует логическому значению, которое определяет, передаются ли учётные данные (cookie, заголовки HTTP-аутентификации и клиентские TLS-сертификаты) при запросе к другому источнику по CORS (англ. Cross-Origin Resource Sharing — «совместное использование ресурсов между разными источниками») и сохраняются ли cookie, установленные таким ответом.

Значение true разрешает отправку учётных данных в межсайтовом запросе, но не обходит CORS и ограничения cookie. Сервер должен разрешить конкретный источник в Access-Control-Allow-Origin и вернуть Access-Control-Allow-Credentials: true; значение * для таких запросов не подходит.

Поддержка браузерами

Спецификация: xhr.spec.whatwg

Поддерживается во всех основных браузерах с 2015 года.

Показать браузеры
Совместимостьapi.XMLHttpRequest.withCredentials
ВозможностьКомпьютерыМобильные
ChromeEdgeFirefoxOperaSafariChrome AndroidFirefox for AndroidOpera AndroidSafari on iOSSamsung BrowserWebView AndroidWebView on iOS
withCredentials✓3✓12✓3.5

Версия 3.5 выпущена в 2009 г.

Примечание MDN (англ.)

Starting with Firefox 11, it's no longer supported to use the withCredentials attribute when performing synchronous requests. Attempting to do so throws an NS_ERROR_DOM_INVALID_ACCESS_ERR exception.

✓12✓4✓18✓4

Версия 4 выпущена в 2011 г.

Примечание MDN (англ.)

Starting with Firefox for Android 14, it's no longer supported to use the withCredentials attribute when performing synchronous requests. Attempting to do so throws an NS_ERROR_DOM_INVALID_ACCESS_ERR exception.

✓12✓3.2✓1.0✓4.4✓3.2

поддерживаетсяс ограниченияминет поддержкинет данных≤31 — не позднее версии 31

JavaScript синтаксис

JavaScript
// чтение
const flag = xhr.withCredentials;

// запись
xhr.withCredentials = booleanValue;

Спецификация

XMLHttpRequest Standard.

Значения параметров

Параметр Описание booleanValue — XMLHttpRequest.withCredentials
Параметр Описание
booleanValue Логическое значение: true — передавать учётные данные в запросе к другому источнику и сохранять cookie из ответа, false — не передавать. Значение по умолчанию false.

Исключения

Исключения XMLHttpRequest.withCredentials
Тип исключения Описание
InvalidStateError Возникает при установке значения, если состояние запроса отличается от UNSENT и OPENED либо метод send() уже вызван.

Пример использования

Пример ниже демонстрирует запрос к другому источнику с передачей cookie. Сервер должен ответить заголовками Access-Control-Allow-Origin с адресом страницы и Access-Control-Allow-Credentials: true:

JavaScript
const xhr = new XMLHttpRequest(); // создаем новый запрос
xhr.open("GET", "https://api.example.com/profile"); // запрос к другому источнику
xhr.withCredentials = true; // передаем cookie и другие учётные данные
xhr.send(); // отправляем запрос на сервер