CORS

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление API

Политика cors добавляет поддержку общего доступа к ресурсам независимо от источника (CORS) для операции или API, чтобы разрешить междоменные вызовы из браузерных клиентов.

Примечание.

Задайте элементы политики и дочерние элементы в порядке, указанном в правиле политики. Чтобы помочь вам настроить эту политику, портал предоставляет интерактивный редактор на основе форм. Узнайте, как устанавливать или изменять политики службы управления API.

Правило политики

<cors allow-credentials="false | true" terminate-unmatched-request="true | false">
    <allowed-origins>
        <origin>origin uri</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="number of seconds">
        <method>HTTP verb</method>
    </allowed-methods>
    <allowed-headers>
        <header>header name</header>
    </allowed-headers>
    <expose-headers>
        <header>header name</header>
    </expose-headers>
</cors>

Атрибуты

Имя. Описание Обязательное поле По умолчанию.
allow-credentials Заголовок Access-Control-Allow-Credentials в ответе на предварительный запрос получит значение, указанное в этом атрибуте. Этот заголовок определяет, может ли клиент передавать в междоменных запросах учетные данные. Допустимы выражения политики. No false
terminate-unmatched-request Управляет обработкой запросов независимо от источника, которые не соответствуют параметрам политики. Допустимы выражения политики.

Если OPTIONS запрос обрабатывается как предварительный запрос и Origin заголовок не соответствует параметрам политики:
— Если атрибут задан true, немедленно завершите запрос пустым 200 OK ответом.
— Если для атрибута задано значение false, проверка входящий трафик для других политик в областьcors, которые являются прямыми дочерними элементами входящего элемента и применяют их. Если политики cors не найдены, запрос завершается с пустым ответом 200 OK.

Если GET или HEAD запрос включают Origin заголовок (и поэтому обрабатывается как простой запрос между источниками) и не соответствует параметрам политики:
— Если атрибут задан true, немедленно завершите запрос пустым 200 OK ответом.
— Если для атрибута задано значение false, разрешите запросу работать нормально и не добавляйте заголовки CORS в ответ.		 No true

Элементы

Имя Описание Обязательное поле По умолчанию.
allowed-origins Содержит элементы origin, описывающие разрешенные источники для междоменных запросов. allowed-origins может содержать один элемент origin со значением *, если нужно разрешить любые источники, либо один или несколько элементов origin, содержащих URI источников. Да Н/П
allowed-methods Этот элемент является обязательным, если разрешены методы, отличные от GET или POST. Содержит элементы method, перечисляющие поддерживаемые HTTP-команды. Значение * указывает все методы. No Если этот раздел отсутствует, поддерживаются методы GET и POST.
allowed-headers Этот элемент содержит элементы header, указывающие имена заголовков, которые могут быть включены в запрос. Да Н/П
expose-headers Этот элемент содержит элементы header, указывающие имена заголовков, которые будут доступны клиенту. No Н/П

Внимание

Используйте подстановочный знак * с осторожностью в параметрах политики. Эта конфигурация может предоставлять слишком много разрешений и повышать уязвимость API к некоторым угрозам безопасности API.

Элементы разрешенных источников

Имя Описание Обязательное поле По умолчанию.
origin В качестве значений допускается *, которое разрешает любые источники, или URI конкретного источника. URI-адрес должен включать схему, узел и порт. Не используйте кавычки. Да Если в URI не указан порт, используется порт 80 для HTTP и порт 443 для HTTPS.

Атрибуты разрешенных методов

Имя Описание Обязательное поле По умолчанию.
preflight-result-max-age Заголовок Access-Control-Max-Age в ответе на предварительный запрос получит значение, указанное в этом атрибуте. Этот заголовок определяет, может ли клиент помещать в кэш ответы на предварительные запросы. Допустимы выражения политики. No 0

Элементы разрешенных методов

Имя Описание Обязательное поле По умолчанию.
метод Задает команду HTTP. Допустимы выражения политики. Если раздел allowed-methods присутствует, в нем обязательно должен быть по крайней мере один элемент method. Н/П

Элементы разрешенных заголовков

Имя Описание Обязательное поле По умолчанию.
авторизации Задает имя заголовка. Если этот раздел присутствует, требуется allowed-headers хотя бы один header элемент. Н/П

Элементы с открытыми заголовками

Имя Описание Обязательное поле По умолчанию.
авторизации Задает имя заголовка. Если этот раздел присутствует, требуется expose-headers хотя бы один header элемент. Н/П

Использование

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

  • Политику cors можно настроить в нескольких областях (например, в области продукта и глобальной области). Убедитесь, что элемент base настроен в области операций, API и продукта для наследования необходимых политик в родительских областях.
  • Только политика cors оценивается по запросу OPTIONS на предварительном этапе. Оставшиеся настроенные политики оцениваются по утвержденному запросу.
  • Эту политику можно использовать только один раз в разделе политики.

Сведения о CORS

CORS — это стандарт на основе заголовков HTTP, который позволяет браузеру и серверу взаимодействовать друг с другом и определять, разрешать конкретные запросы независимо от источника или нет (вызовы XMLHttpRequest, отправляемые из кода JavaScript на веб-странице в другие домены). Это обеспечивает большую гибкость, чем просто разрешение запросов из одного источника, и более высокую защищенность, чем разрешение всех запросов независимо от источника.

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

  • Предварительные запросы — сначала браузер отправляет HTTP-запрос с помощью метода OPTIONS на сервер, чтобы определить, разрешено ли отправлять фактический запрос. Если ответ сервера содержит заголовок Access-Control-Allow-Origin, который разрешает доступ, браузер осуществляет фактический запрос.

  • Простые запросы — эти запросы включают в себя один или несколько дополнительных заголовков Origin, но не запускают предварительный запрос CORS. Разрешены только запросы, использующие методы GET и HEAD и ограниченный набор заголовков запросов.

Сценарии политики cors

Настройте политику cors в службе Управление API для следующих сценариев:

  • Включите интерактивную консоль тестирования на портале разработчика. Подробные сведения приведены в документации по порталу разработчика.

    Примечание.

    При включении CORS для интерактивной консоли служба Управление API по умолчанию настраивает политику cors в глобальной области.

  • Включите службу Управление API, чтобы ответить на предварительные запросы или передать простые запросы CORS, если серверные части не предоставляют собственную поддержку CORS.

    Примечание.

    Если запрос соответствует операции с методом OPTIONS, определенным в API, то логика обработки предварительных запросов, связанная с политикой cors, не будет выполнена. Поэтому такие операции можно использовать для реализации пользовательской логики обработки предварительных запросов, например, чтобы применить политику cors только при определенных условиях.

Распространенные проблемы конфигурации

  • Ключ подписки в заголовке — если вы настраиваете политику cors в области продукта, а API использует проверку подлинности ключа подписки, политика не будет работать при передаче ключа подписки в заголовке. В качестве обходного решения измените запросы, чтобы включить ключ подписки в качестве параметра запроса.
  • API с управлением версиями заголовков — если вы настраиваете политику cors в области API, а API использует схему управления версиями заголовков, политика не будет работать, так как версия передается в заголовке. Может потребоваться настроить альтернативный метод управления версиями, например путь или параметр запроса.
  • Порядок политик — если политика cors не является первой политикой в разделе входящего трафика, это может привести к непредвиденному поведению. Выберите Calculate effective policy (Вычислить эффективную политику) в редакторе политик, чтобы проверить порядок оценки политик в каждой области. Как правило, применяется только первая политика cors.
  • Пустой ответ 200 OK — в некоторых конфигурациях политик отдельные запросы независимо от источника завершаются c пустым ответом 200 OK. Этот ответ ожидается, если для terminate-unmatched-request задано значение по умолчанию true, а входящий запрос имеет заголовок Origin, который не соответствует разрешенному источнику, настроенному в политике cors.

Пример

В этом примере показано, как обеспечить поддержку предварительных запросов, например, с пользовательскими заголовками или методами, отличными от GET и POST. Для поддержки пользовательских заголовков и других команд HTTP используйте разделы allowed-methods и allowed-headers, как показано в следующем примере.

<cors allow-credentials="true">
    <allowed-origins>
        <!-- Localhost useful for development -->
        <origin>http://localhost:8080/</origin>
        <origin>http://example.com/</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="300">
        <method>GET</method>
        <method>POST</method>
        <method>PATCH</method>
        <method>DELETE</method>
    </allowed-methods>
    <allowed-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
        <header>x-zumo-version</header>
        <header>x-zumo-auth</header>
        <header>content-type</header>
        <header>accept</header>
    </allowed-headers>
    <expose-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
    </expose-headers>
</cors>

Связанный контент

Дополнительные сведения о работе с политиками см. в нижеуказанных статьях.