Access-Control-Allow-Headers

Применение

Когда браузер выполняет предварительный запрос OPTIONS, заголовок Access-Control-Request-Headers перечисляет заголовки вне безопасного списка, которые клиент намерен отправить. Сервер отвечает заголовком Access-Control-Allow-Headers, подтверждая, какие из них принимаются.

Заголовки из безопасного списка CORS разрешены всегда, и их не нужно указывать в этом списке. В безопасный список входят Accept, Accept-Language, Content-Language, Content-Type (с ограничениями на медиатип и длину значения) и Range (с ограничениями на формат). Явное указание заголовка из безопасного списка снимает дополнительные ограничения на его значение.

Несколько имён заголовков указываются списком через запятую.

Список имён заголовков

Разделённый запятыми набор имён заголовков, которые сервер принимает в фактическом запросе.

Access-Control-Allow-Headers: Content-Type, Authorization

* (подстановочный знак)

Звёздочка выступает подстановочным знаком для запросов без учётных данных, разрешая любое имя заголовка.

Access-Control-Allow-Headers: *

Примечание

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

Пример

Предварительный запрос выясняет, разрешены ли Content-Type и пользовательский заголовок X-Request-ID. Сервер подтверждает оба.

Запрос

OPTIONS /api/data HTTP/1.1
Origin: https://example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type, X-Request-ID

Ответ

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: 86400

Сервер, использующий подстановочный знак для запросов без учётных данных, отвечает одним символом.

Access-Control-Allow-Headers: *

Диагностика

Сбои предварительных запросов, связанные с заголовками запроса, приводят к ошибкам в консоли и блокируют фактический запрос.

В консоли отображается «Request header field X is not allowed by Access-Control-Allow-Headers in preflight response.» Сервер не указал имя заголовка в значении Access-Control-Allow-Headers. Добавьте отсутствующий заголовок в ответ на предварительный запрос. В nginx: add_header Access-Control-Allow-Headers “Content-Type, Authorization, X-Request-ID”; В Apache: Header set Access-Control-Allow-Headers “Content-Type, Authorization, X-Request-ID”

В ответе на предварительный запрос заголовок отсутствует полностью. Сервер обрабатывает запрос OPTIONS, но не включает Access-Control-Allow-Headers в ответ. Многие фреймворки требуют явной настройки CORS для маршрутов предварительных запросов. Проверьте, что обработчик OPTIONS или промежуточное ПО устанавливает этот заголовок наряду с Access-Control-Allow-Methods и Access-Control-Allow-Origin.

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

В некоторых серверах имена заголовков оказываются чувствительны к регистру. По протоколу имена HTTP-заголовков регистронезависимы, но некоторые серверные фреймворки выполняют сравнение строк с учётом регистра при проверке списка разрешённых. Запрос, отправляющий content-type, может завершиться неудачей, если сервер указывает только Content-Type. Приведите регистр в соответствие с тем, что отправляет клиент, либо нормализуйте обе стороны к нижнему регистру в конфигурации CORS.

Отправка Content-Type: application/json вызывает неожиданный предварительный запрос. Заголовок Content-Type входит в безопасный список только для значений application/x-www-form-urlencoded, multipart/form-data и text/plain. Значение application/json выходит за пределы безопасного списка и принудительно вызывает предварительный запрос. Добавьте Content-Type в список Access-Control-Allow-Headers. Чтобы убедиться, что предварительный запрос срабатывает, откройте вкладку Network в DevTools и отфильтруйте по методу, чтобы заметить запрос OPTIONS, предшествующий фактическому запросу.