Этот стандарт обмена ресурсами между разными доменными зонами может позволить междоменные запросы HTTP для:

• Вызовов XMLHttpRequest или Fetch API, как обсуждалось выше.
• Веб-шрифтов (для использования шрифтов из разных доменных зон в @font-face в CSS), чтобы серверы могли развернуть TrueType шрифты, которые можно загружать только из разных доменных зон и использовать веб-сайтами, которым разрешено это делать.
• WebGL-текстуры.
• Изображения/кадры видео, нарисованные на холсте с помощью drawImage().
• CSS-фигуры из изображений.

Это общая статья об обмене ресурсами между разными доменными зонами и содержит обсуждение необходимых заголовков HTTP.

Стандарт обмена ресурсами между разными доменными зонами работает путем добавления новых заголовков HTTP, которые позволяют серверам описывать, из каких источников разрешено считывать эту информацию браузеру. Кроме того, для методов запроса HTTP, которые могут вызывать побочные эффекты на данные сервера (в частности, методы HTTP, отличные от GET, или POST с определенными типами MIME), спецификация предписывает браузерам «предварительно обрабатывать» запрос, запрашивая поддерживаемые методы у сервера с помощью метода запроса HTTP OPTIONS, а затем, после «утверждения» сервера, отправляя фактический запрос. Серверы также могут сообщать клиентам, нужно ли отправлять «аутентификационные данные» (такие как Cookies и HTTP аутентификация) вместе с запросами.

Ошибки CORS приводят к ошибкам, но по соображениям безопасности подробности об ошибке недоступны для JavaScript. Весь код знает только о возникновении ошибки. Единственный способ определить, что именно пошло не так, — это посмотреть в консоли браузера на подробности.

В последующих разделах рассматриваются сценарии, а также приводится разбиение заголовков HTTP.

Мы представляем три сценария, которые демонстрируют работу обмена ресурсами между разными доменными зонами. Все эти примеры используют XMLHttpRequest, который может выполнять междоменные запросы в любом поддерживающем браузере.

Некоторые запросы не вызывают предварительный запрос CORS префлайт. Их называют простыми запросами по устаревшему спецификации CORS, хотя спецификация Fetch (которая теперь определяет CORS) не использует этот термин.

Это обусловлено тем, что элемент <form> из HTML 4.0 (который предшествует кросс-сайтовым XMLHttpRequest и fetch) может отправлять простые запросы к любому источнику, поэтому любой, кто пишет сервер, должен уже защищаться от подделки межсайтовых запросов (CSRF). При таком предположении серверу не нужно включать (отвечая на предварительный запрос) для получения любого запроса, похожим на отправку формы, поскольку угроза CSRF не хуже, чем при отправке формы. Однако сервер по-прежнему должен включить использование Access-Control-Allow-Origin, чтобы обмен ответом со скриптом.

Простой запрос — это запрос, который удовлетворяет всем следующим условиям:

• Один из разрешённых методов:
  • GET
  • HEAD
  • POST
• Помимо заголовков, автоматически устанавливаемых пользовательским агентом (например, Connection, User-Agent или другие заголовки, определенные в спецификации Fetch как запрещенное имя заголовка), единственными заголовками, которые разрешено вручную устанавливать, являются те, которые спецификация Fetch определяет как заголовок запроса, включенный в CORS, а именно:
  • Accept
  • Accept-Language
  • Content-Language
  • Content-Type (обратите внимание на дополнительные требования ниже)
  • Range (только со простым значением заголовка диапазона; например, bytes=256- или bytes=127-255)

• Единственные сочетания типа/подтипов, разрешенные для типа медиа, указанного в заголовке Content-Type, это:
  • application/x-www-form-urlencoded
  • multipart/form-data
  • text/plain
• Если запрос выполняется с помощью объекта XMLHttpRequest, на объекте, возвращаемом свойством XMLHttpRequest.upload, используемым в запросе, не регистрируются обработчики событий; другими словами, при наличии экземпляра XMLHttpRequest xhr, никакой код не вызвал xhr.upload.addEventListener() для добавления обработчика событий для мониторинга загрузки.
• В запросе не используется объект ReadableStream.

Например, предположим, что веб-контент на https://foo.example хочет вызвать контент на домене https://bar.other. В JavaScript, развернутом на foo.example, может использоваться код такого вида:

const xhr = new XMLHttpRequest();
const url = "https://bar.other/resources/public-data/";

xhr.open("GET", url);
xhr.onreadystatechange = someHandler;
xhr.send();

Эта операция выполняет простой обмен между клиентом и сервером, используя заголовки CORS для обработки привилегий:

Посмотрим, что в этом случае отправит браузер серверу:

GET /resources/public-data/ HTTP/1.1
Host: bar.other
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:71.0) Gecko/20100101 Firefox/71.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Connection: keep-alive
Origin: https://foo.example

Обратите внимание на заголовок запроса Origin, который показывает, что вызов исходит из https://foo.example.

Теперь посмотрим, как сервер отвечает:

HTTP/1.1 200 OK
Date: Mon, 01 Dec 2008 00:23:53 GMT
Server: Apache/2
Access-Control-Allow-Origin: *
Keep-Alive: timeout=2, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: application/xml

[…XML Data…]

В ответ сервер возвращает заголовок Access-Control-Allow-Origin со значением Access-Control-Allow-Origin: *, что означает, что к ресурсу может получить доступ любой источник.

Access-Control-Allow-Origin: *

Эта схема заголовков Origin и Access-Control-Allow-Origin — это простейшее использование протокола контроля доступа. Если владельцы ресурсов на https://bar.other хотели ограничить доступ к ресурсу только запросами только из https://foo.example (т. е., никакой другой домен, кроме https://foo.example , не может получить доступ к ресурсу через разные источники), они бы отправили:

Access-Control-Allow-Origin: https://foo.example

В отличие от простых запросов, для «предварительно запрошенных» запросов браузер сначала отправляет HTTP-запрос с помощью метода OPTIONS на ресурс на другом источнике, чтобы определить, безопасен ли фактический запрос для отправки. Такие запросы между разными источниками предварительно запрашиваются, поскольку они могут иметь последствия для пользовательских данных.

Ниже приведен пример запроса, который будет предварительно запрошен:

const xhr = new XMLHttpRequest();
xhr.open("POST", "https://bar.other/doc");
xhr.setRequestHeader("X-PINGOTHER", "pingpong");
xhr.setRequestHeader("Content-Type", "text/xml");
xhr.onreadystatechange = handler;
xhr.send("<person><name>Arun</name></person>");

В приведенном выше примере создается XML-тело для отправки с запросом POST. Также устанавливается нестандартный HTTP-заголовок запроса X-PINGOTHER. Такие заголовки не являются частью HTTP/1.1, но обычно полезны для веб-приложений. Поскольку запрос использует метод Content-Type text/xml, и поскольку установлен пользовательский заголовок, этот запрос предварительно запрашивается.

Давайте рассмотрим полный обмен между клиентом и сервером. Первый обмен — это запрос/ответ предварительного запроса:

OPTIONS /doc HTTP/1.1
Host: bar.other
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:71.0) Gecko/20100101 Firefox/71.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Connection: keep-alive
Origin: https://foo.example
Access-Control-Request-Method: POST
Access-Control-Request-Headers: X-PINGOTHER, Content-Type

HTTP/1.1 204 No Content
Date: Mon, 01 Dec 2008 01:15:39 GMT
Server: Apache/2
Access-Control-Allow-Origin: https://foo.example
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: X-PINGOTHER, Content-Type
Access-Control-Max-Age: 86400
Vary: Accept-Encoding, Origin
Keep-Alive: timeout=2, max=100
Connection: Keep-Alive

Строки 1-10 выше представляют запрос предварительного запроса с методом OPTIONS. Браузер определяет, что ему нужно отправить это, исходя из параметров запроса, используемых фрагментом JavaScript-кода выше, чтобы сервер мог ответить, можно ли отправить запрос с фактическими параметрами запроса. OPTIONS — это HTTP/1.1 метод, используемый для получения дополнительной информации от серверов, и является безопасным методом, означающим, что он не может использоваться для изменения ресурса. Обратите внимание, что вместе с запросом OPTIONS отправляются два других заголовка запроса (строки 9 и 10 соответственно):

Access-Control-Request-Method: POST
Access-Control-Request-Headers: X-PINGOTHER, Content-Type

Заголовок Access-Control-Request-Method уведомляет сервер, что при отправке фактического запроса будет использоваться метод запроса POST. Заголовок Access-Control-Request-Headers уведомляет сервер, что при отправке фактического запроса будут использоваться пользовательские заголовки X-PINGOTHER и Content-Type. Теперь сервер имеет возможность определить, может ли он принять запрос при этих условиях.

Строки 12-21 выше — это ответ, который возвращает сервер, указывающий, что метод запроса (POST) и заголовки запроса (X-PINGOTHER) допустимы. Давайте более подробно рассмотрим строки 15-18:

Access-Control-Allow-Origin: https://foo.example
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: X-PINGOTHER, Content-Type
Access-Control-Max-Age: 86400

Сервер отвечает Access-Control-Allow-Origin: https://foo.example, ограничивая доступ только доменному источнику-запросу. Он также отвечает Access-Control-Allow-Methods, что POST и GET являются допустимыми методами для запроса рассматриваемого ресурса (этот заголовок аналогичен ответному заголовку Allow, но используется строго в контексте управления доступом).

Сервер также отправляет Access-Control-Allow-Headers со значением "X-PINGOTHER, Content-Type", подтверждая, что эти заголовки разрешено использовать с фактическим запросом. Как и Access-Control-Allow-Methods, Access-Control-Allow-Headers — это список допустимых заголовков, разделенных запятыми.

Наконец, Access-Control-Max-Age задает значение в секундах, в течение которого ответ на запрос предварительного запроса может кэшироваться без отправки другого запроса предварительного запроса. Значение по умолчанию — 5 секунд. В данном случае максимальный срок хранения составляет 86400 секунд (= 24 часа). Обратите внимание, что у каждого браузера есть максимальное внутреннее значение, которое имеет приоритет, когда значение Access-Control-Max-Age превышает его.

После завершения запроса предварительного запроса отправляется реальный запрос:

POST /doc HTTP/1.1
Host: bar.other
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:71.0) Gecko/20100101 Firefox/71.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Connection: keep-alive
X-PINGOTHER: pingpong
Content-Type: text/xml; charset=UTF-8
Referer: https://foo.example/examples/preflightInvocation.html
Content-Length: 55
Origin: https://foo.example
Pragma: no-cache
Cache-Control: no-cache

<person><name>Arun</name></person>

HTTP/1.1 200 OK
Date: Mon, 01 Dec 2008 01:15:40 GMT
Server: Apache/2
Access-Control-Allow-Origin: https://foo.example
Vary: Accept-Encoding, Origin
Content-Encoding: gzip
Content-Length: 235
Keep-Alive: timeout=2, max=99
Connection: Keep-Alive
Content-Type: text/plain

[Some XML payload]

Предварительно запрошенные запросы и перенаправления

Не все браузеры в настоящее время поддерживают следование перенаправлениям после предварительно запрошенного запроса. Если происходит перенаправление после такого запроса, некоторые браузеры в настоящее время будут отображать сообщение об ошибке, подобное следующему:

Запрос был перенаправлен на 'https://example.com/foo', что запрещено для запросов между разными источниками, требующих предварительного запроса. Запрос требует предварительного запроса, который запрещено следовать перенаправлениям между разными источниками.

Протокол CORS изначально требовал такого поведения, но позже был изменен, чтобы больше не требовать его. Однако не все браузеры реализовали изменения и по-прежнему демонстрируют первоначально необходимое поведение.

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

• Измените поведение на стороне сервера, чтобы избежать предварительного запроса и/или перенаправления
• Измените запрос таким образом, чтобы он был простым запросом, не вызывающим предварительного запроса

Если это невозможно, другой способ:

1. Сделайте простой запрос (используя Response.url для API Fetch или XMLHttpRequest.responseURL) чтобы определить URL, на который приведет реальный предварительно запрошенный запрос.
2. Сделайте еще один запрос (фактический запрос) с использованием URL, полученного из Response.url или XMLHttpRequest.responseURL на первом шаге.

Однако, если запрос вызывает предварительный запрос из-за наличия заголовка Authorization в запросе, вы не сможете обойти это ограничение, используя описанные выше шаги. И вы не сможете обойти это вообще, если у вас нет контроля над сервером, к которому отправляется запрос.

Самой интересной возможностью, предоставляемой как XMLHttpRequest, так и Fetch и CORS, является возможность отправки «запросов с учётными данными», учитывающих файлы cookie HTTP и данные аутентификации HTTP. По умолчанию в запросах к другому домену с использованием XMLHttpRequest или Fetch браузеры не отправляют учётные данные. Для отправки учётных данных необходимо установить определённый флаг в объекте XMLHttpRequest или в конструкторе Request при его вызове.

В этом примере контент, первоначально загруженный из https://foo.example, отправляет простой запрос GET к ресурсу на https://bar.other, который устанавливает файлы cookie. Контент на foo.example может содержать JavaScript, подобный этому:

const invocation = new XMLHttpRequest();
const url = "https://bar.other/resources/credentialed-content/";

function callOtherDomain() {
  if (invocation) {
    invocation.open("GET", url, true);
    invocation.withCredentials = true;
    invocation.onreadystatechange = handler;
    invocation.send();
  }
}

Строка 7 показывает флаг в XMLHttpRequest, который необходимо установить для отправки запроса с файлами cookie, а именно булево значение withCredentials. По умолчанию запрос выполняется без файлов cookie. Поскольку это простой запрос GET, он не предварительно проверяется, но браузер отклонит любой ответ, у которого нет заголовка Access-Control-Allow-Credentials: true, и не сделает ответ доступным для вызываемого веб-контента.

Вот пример обмена между клиентом и сервером:

GET /resources/credentialed-content/ HTTP/1.1
Host: bar.other
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:71.0) Gecko/20100101 Firefox/71.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Connection: keep-alive
Referer: https://foo.example/examples/credential.html
Origin: https://foo.example
Cookie: pageAccess=2

HTTP/1.1 200 OK
Date: Mon, 01 Dec 2008 01:34:52 GMT
Server: Apache/2
Access-Control-Allow-Origin: https://foo.example
Access-Control-Allow-Credentials: true
Cache-Control: no-cache
Pragma: no-cache
Set-Cookie: pageAccess=3; expires=Wed, 31-Dec-2008 01:34:53 GMT
Vary: Accept-Encoding, Origin
Content-Encoding: gzip
Content-Length: 106
Keep-Alive: timeout=2, max=100
Connection: Keep-Alive
Content-Type: text/plain

[text/plain payload]

Хотя строка 10 содержит файл cookie, предназначенный для содержимого на https://bar.other, если bar.other не ответил с заголовком Access-Control-Allow-Credentials: true (строка 16), ответ будет проигнорирован и не будет доступен веб-контенту.

Предварительные запросы и учётные данные

Предварительные запросы CORS никогда не должны включать учётные данные. Ответ на предварительный запрос должен указывать Access-Control-Allow-Credentials: true, чтобы указать, что фактический запрос может быть выполнен с учётными данными.

Запросы с учётными данными и подстановочные знаки

При ответе на запрос с учётными данными:

• Сервер не должен указывать подстановочный знак «*» для значения заголовка ответа Access-Control-Allow-Origin, а должен указать явное значение; например: Access-Control-Allow-Origin: https://example.com
• Сервер не должен указывать подстановочный знак «*» для значения заголовка ответа Access-Control-Allow-Headers, а должен указать явный список имён заголовков; например, Access-Control-Allow-Headers: X-PINGOTHER, Content-Type
• Сервер не должен указывать подстановочный знак «*» для значения заголовка ответа Access-Control-Allow-Methods, а должен указать явный список имён методов; например, Access-Control-Allow-Methods: POST, GET

Если запрос содержит учётные данные (чаще всего заголовок Cookie) и ответ содержит заголовок Access-Control-Allow-Origin: * (т.е. с подстановочным знаком), браузер заблокирует доступ к ответу и сообщит об ошибке CORS в консоли devtools.

Но если запрос содержит учётные данные (например, заголовок Cookie) и ответ содержит фактическое значение origin вместо подстановочного знака (например, Access-Control-Allow-Origin: https://example.com), браузер разрешит доступ к ответу из указанного origin.

Обратите также внимание, что любой заголовок ответа Set-Cookie в ответе не установит файл cookie, если значение Access-Control-Allow-Origin в этом ответе является подстановочным знаком «*» вместо фактического origin.

Файлы cookie третьих сторон

Обратите внимание, что файлы cookie, установленные в ответах CORS, подчиняются стандартным правилам файлов cookie третьих сторон. В примере выше страница загружается с foo.example, но файл cookie в строке 19 отправляется bar.other, и, следовательно, он не будет сохранён, если в браузере пользователя отключены все файлы cookie третьих сторон.

Файлы cookie в запросе (строка 10) также могут быть подавлены стандартными правилами файлов cookie третьих сторон. Поэтому политика файлов cookie может аннулировать описанную в этой главе возможность, фактически не позволяя вам выполнять запросы с учётными данными.

Будет применяться политика файлов cookie, связанная с атрибутом SameSite.

В этом разделе перечислены заголовки HTTP ответа, которые серверы возвращают для запросов контроля доступа, как определено спецификацией Cross-Origin Resource Sharing. Предыдущий раздел даёт общий обзор их работы.

Возвращаемый ресурс может иметь один заголовок Access-Control-Allow-Origin со следующим синтаксисом:

Access-Control-Allow-Origin: <origin> | *

Access-Control-Allow-Origin указывает либо единственный origin, который сообщает браузерам разрешить доступу к ресурсу из этого origin; либо — для запросов без учётных данных — подстановочный знак «*» сообщает браузерам разрешить доступ к ресурсу из любого origin.

Например, чтобы разрешить коду из origin https://mozilla.org доступ к ресурсу, можно указать:

Access-Control-Allow-Origin: https://mozilla.org
Vary: Origin

Если сервер указывает единственный origin (который может динамически меняться в зависимости от запрашиваемого origin как часть белого списка) вместо подстановочного знака «*», сервер также должен включать Origin в заголовке ответа Vary, чтобы указать клиентам, что ответы сервера будут отличаться в зависимости от значения заголовка запроса Origin.

Заголовок Access-Control-Expose-Headers добавляет указанные заголовки в список разрешённых для доступа JavaScript (например, getResponseHeader()) в браузерах.

Access-Control-Expose-Headers: <header-name>[, <header-name>]*

Например, следующее:

Access-Control-Expose-Headers: X-My-Custom-Header, X-Another-Custom-Header

…разрешит доступ браузера к заголовкам X-My-Custom-Header и X-Another-Custom-Header.

Заголовок Access-Control-Max-Age указывает, как долго результаты предварительного запроса могут кэшироваться. Пример предварительного запроса см. в примерах выше.

Access-Control-Max-Age: <delta-seconds>

Параметр delta-seconds указывает количество секунд, в течение которых результаты могут кэшироваться.

Заголовок Access-Control-Allow-Credentials указывает, может ли ответ на запрос быть показан, когда флаг credentials имеет значение true. При использовании в качестве ответа на предварительный запрос это указывает, может ли фактический запрос выполняться с учётными данными. Обратите внимание, что простые GET запросы не предварительно проверяются. Поэтому, если запрос выполняется для ресурса с учётными данными, и этот заголовок не возвращается с ресурсом, браузер игнорирует ответ и не возвращает его веб-контенту.

Access-Control-Allow-Credentials: true

Запросы с учётными данными обсуждаются выше.

Заголовок Access-Control-Allow-Methods определяет метод или методы, разрешённые при доступе к ресурсу. Используется в ответ на предварительный запрос. Условия, при которых запрос предварительно проверяется, описаны выше.

Access-Control-Allow-Methods: <method>[, <method>]*

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

Заголовок Access-Control-Allow-Headers используется в ответ на предварительный запрос для указания HTTP-заголовков, которые могут быть использованы при выполнении фактического запроса. Этот заголовок является ответом со стороны сервера на заголовок браузера Access-Control-Request-Headers.

Access-Control-Allow-Headers: <header-name>[, <header-name>]*

В этом разделе перечислены заголовки, которые клиенты могут использовать при отправке HTTP-запросов, чтобы использовать функцию обмена между доменами. Обратите внимание, что эти заголовки устанавливаются для вас при обращении к серверам. Разработчики, использующие возможность кросс-доменного XMLHttpRequest, не должны программно устанавливать заголовки запросов кросс-доменного обмена.

Заголовок Origin указывает на происхождение запроса доступа между доменами или запроса предварительного запроса.

Origin: <origin>

Происхождение — это URL, указывающий на сервер, с которого инициируется запрос. Он не включает никакой информации о пути, только имя сервера.

Обратите внимание, что в любом запросе управления доступом заголовок Origin всегда отправляется.

Заголовок Access-Control-Request-Method используется при отправке запроса предварительного запроса, чтобы сообщить серверу, какой HTTP-метод будет использован при фактическом запросе.

Access-Control-Request-Method: <method>

Примеры такого использования можно найти выше.

Заголовок Access-Control-Request-Headers используется при отправке запроса предварительного запроса, чтобы сообщить серверу, какие HTTP-заголовки будут использованы при фактическом запросе (например, с setRequestHeader()). Этот заголовок на стороне браузера будет отвечен соответствующим заголовком на стороне сервера Access-Control-Allow-Headers.

Access-Control-Request-Headers: <field-name>[, <field-name>]*

Примеры такого использования можно найти выше.

• Ошибки CORS
• Включить CORS: я хочу добавить поддержку CORS на свой сервер
• XMLHttpRequest
• API Fetch
• Сработает ли CORS? - интерактивный объяснител и генератор CORS
• Как запустить Chrome без CORS
• Использование CORS со всеми (современными) браузерами
• Ответ на Stack Overflow с информацией о том, как действовать при решении распространённых проблем:
  • Как избежать предварительного запроса CORS
  • Как использовать прокси CORS, чтобы обойти "Нет заголовка Access-Control-Allow-Origin"
  • Как исправить "Заголовок Access-Control-Allow-Origin не должен быть универсальным"