Udostępnij za pośrednictwem

CORS

  • Artykuł

DOTYCZY: Wszystkie warstwy usługi API Management

Zasady cors dodają obsługę współużytkowania zasobów między źródłami (CORS) do operacji lub interfejsu API, aby zezwolić na wywołania między domenami od klientów opartych na przeglądarce.

Uwaga

Ustaw elementy zasad i elementy podrzędne w kolejności podanej w instrukcji zasad. Aby ułatwić konfigurowanie tych zasad, portal udostępnia edytor oparty na formularzach z przewodnikiem. Dowiedz się więcej na temat ustawiania lub edytowania zasad usługi API Management.

Instrukcja zasad

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

Atrybuty

Imię i nazwisko/nazwa opis Wymagani Wartość domyślna
allow-credentials Nagłówek Access-Control-Allow-Credentials w odpowiedzi wstępnej zostanie ustawiony na wartość tego atrybutu i wpłynie na możliwość przesyłania poświadczeń przez klienta w żądaniach między domenami. Wyrażenia zasad są dozwolone. Nie. false
terminate-unmatched-request Kontroluje przetwarzanie żądań między źródłami, które nie są zgodne z ustawieniami zasad. Wyrażenia zasad są dozwolone.

Gdy OPTIONS żądanie jest przetwarzane jako żądanie wstępne i Origin nagłówek nie są zgodne z ustawieniami zasad:
- Jeśli atrybut jest ustawiony na true, natychmiast zakończ żądanie z pustą 200 OK odpowiedzią
- Jeśli atrybut jest ustawiony na false, sprawdź przychodzące dla innych zasad w zakresie cors , które są bezpośrednimi elementami podrzędnych elementu przychodzącego i zastosuj je. Jeśli nie cors znaleziono żadnych zasad, zakończ żądanie z pustą 200 OK odpowiedzią.

Gdy GET żądanie lub HEAD zawiera Origin nagłówek (i dlatego jest przetwarzane jako proste żądanie między źródłami) i nie jest zgodne z ustawieniami zasad:
- Jeśli atrybut jest ustawiony na true, natychmiast zakończ żądanie z pustą 200 OK odpowiedzią.
- Jeśli atrybut jest ustawiony na falsewartość , zezwól na normalne kontynuowanie żądania i nie dodawaj nagłówków CORS do odpowiedzi.		 Nie. true

Elementy

Nazwa/nazwisko opis Wymagani Wartość domyślna
dozwolone źródła Zawiera origin elementy opisujące dozwolone źródła żądań między domenami. allowed-origins może zawierać jeden origin element, który określa * , aby zezwolić na dowolne źródło lub co najmniej jeden origin element, który zawiera identyfikator URI. Tak Nie dotyczy
dozwolone metody Ten element jest wymagany, jeśli metody inne niż GET lub POST są dozwolone. Zawiera method elementy określające obsługiwane czasowniki HTTP. Wartość * wskazuje wszystkie metody. Nie. Jeśli ta sekcja nie jest obecna i GET POST są obsługiwane.
dozwolone nagłówki Ten element zawiera header elementy określające nazwy nagłówków, które można uwzględnić w żądaniu. Tak Nie dotyczy
expose-headers Ten element zawiera header elementy określające nazwy nagłówków, które będą dostępne dla klienta. Nie. Nie dotyczy

Uwaga

Użyj symbolu wieloznakowego * z troską w ustawieniach zasad. Ta konfiguracja może być nadmiernie permisywna i może sprawić, że interfejs API będzie bardziej podatny na niektóre zagrożenia bezpieczeństwa interfejsu API.

dozwolone elementy źródła

Nazwa/nazwisko opis Wymagani Wartość domyślna
połączenie pierwotne Wartość może być dozwolona * dla wszystkich źródeł lub identyfikator URI, który określa jedno źródło. Identyfikator URI musi zawierać schemat, host i port. Nie należy stosować znaków cudzysłowu. Tak Jeśli port zostanie pominięty w identyfikatorze URI, port 80 jest używany dla protokołu HTTP, a port 443 jest używany dla protokołu HTTPS.

dozwolone metody atrybutów

Nazwa/nazwisko opis Wymagani Wartość domyślna
preflight-result-max-age Nagłówek Access-Control-Max-Age w odpowiedzi wstępnej zostanie ustawiony na wartość tego atrybutu i wpłynie na zdolność agenta użytkownika do buforowania odpowiedzi wstępnej. Wyrażenia zasad są dozwolone. Nie. 0

dozwolone elementy metod

Nazwa/nazwisko opis Wymagani Wartość domyślna
metoda Określa czasownik HTTP. Wyrażenia zasad są dozwolone. Co najmniej jeden method element jest wymagany, jeśli allowed-methods sekcja jest obecna. Nie dotyczy

dozwolone elementy nagłówków

Nazwa/nazwisko opis Wymagani Wartość domyślna
nagłówek Określa nazwę nagłówka. Jeśli ta sekcja jest obecna, allowed-headers wymagana jest co najmniej jeden header element. Nie dotyczy

uwidaczniaj elementy nagłówków

Nazwa/nazwisko opis Wymagani Wartość domyślna
nagłówek Określa nazwę nagłówka. Jeśli ta sekcja jest obecna, expose-headers wymagana jest co najmniej jeden header element. Nie dotyczy

Użycie

  • Sekcje zasad: ruch przychodzący
  • Zakresy zasad: globalny, obszar roboczy, produkt, interfejs API, operacja
  • Bramy: klasyczne, v2, zużycie, self-hosted, obszar roboczy

Uwagi dotyczące użycia

  • Zasady można skonfigurować cors w więcej niż jednym zakresie (na przykład w zakresie produktu i zakresie globalnym). Upewnij się, że base element jest skonfigurowany w zakresie operacji, interfejsu API i produktu w celu dziedziczenia wymaganych zasad w zakresach nadrzędnych.
  • cors Tylko zasady są oceniane na OPTIONS żądanie podczas wstępnejlotu. Pozostałe skonfigurowane zasady są oceniane na podstawie zatwierdzonego żądania.
  • Te zasady można użyć tylko raz w sekcji zasad.

Informacje o mechanizmie CORS

MECHANIZM CORS to standard oparty na nagłówku HTTP, który umożliwia przeglądarce i serwerowi interakcję i określenie, czy zezwalać na określone żądania między źródłami (XMLHttpRequest wywołania wykonywane z języka JavaScript na stronie internetowej do innych domen). Pozwala to na większą elastyczność niż tylko zezwalanie na żądania o tym samym pochodzeniu, ale jest bezpieczniejsze niż zezwalanie na wszystkie żądania między źródłami.

Mechanizm CORS określa dwa typy żądań między źródłami:

  • Żądania wstępne (lub "wstępne") — przeglądarka najpierw wysyła żądanie HTTP przy użyciu OPTIONS metody do serwera, aby określić, czy rzeczywiste żądanie jest dozwolone do wysłania. Jeśli odpowiedź serwera zawiera Access-Control-Allow-Origin nagłówek, który zezwala na dostęp, przeglądarka jest zgodna z rzeczywistym żądaniem.

  • Proste żądania — te żądania obejmują co najmniej jeden dodatkowy Origin nagłówek, ale nie wyzwalają wstępnegolotu MECHANIZMU CORS. Dozwolone są tylko żądania używające GET metod i HEAD oraz ograniczony zestaw nagłówków żądań.

cors scenariusze zasad

Skonfiguruj zasady w usłudze cors API Management w następujących scenariuszach:

  • Włącz interaktywną konsolę testową w portalu deweloperów. Aby uzyskać szczegółowe informacje, zapoznaj się z dokumentacją portalu deweloperów .

    Uwaga

    Po włączeniu mechanizmu CORS dla konsoli interaktywnej usługa API Management domyślnie konfiguruje cors zasady w zakresie globalnym.

  • Włącz usługę API Management, aby odpowiadać na żądania wstępnego sprawdzania lub przekazywać proste żądania funkcji CORS, gdy zaplecza nie zapewniają własnej obsługi funkcji CORS.

    Uwaga

    Jeśli żądanie pasuje do operacji z metodą zdefiniowaną OPTIONS w interfejsie API, logika przetwarzania żądań wstępnych skojarzonych z zasadami cors nie zostanie wykonana. W związku z tym takie operacje mogą służyć do implementowania niestandardowej logiki przetwarzania wstępnego — na przykład w celu zastosowania cors zasad tylko w określonych warunkach.

Typowe problemy z konfiguracją

  • Klucz subskrypcji w nagłówku — jeśli skonfigurujesz cors zasady w zakresie produktu , a interfejs API używa uwierzytelniania klucza subskrypcji, zasady nie będą działać, gdy klucz subskrypcji zostanie przekazany w nagłówku. Aby obejść ten problem, zmodyfikuj żądania, tak aby zawierały klucz subskrypcji jako parametr zapytania.
  • Interfejs API z przechowywaniem wersji nagłówka — jeśli skonfigurujesz cors zasady w zakresie interfejsu API, a interfejs API używa schematu przechowywania wersji nagłówka, zasady nie będą działać, ponieważ wersja jest przekazywana w nagłówku. Może być konieczne skonfigurowanie alternatywnej metody przechowywania wersji, takiej jak ścieżka lub parametr zapytania.
  • Kolejność zasad — może wystąpić nieoczekiwane zachowanie, jeśli cors zasady nie są pierwszymi zasadami w sekcji przychodzącej. Wybierz pozycję Oblicz obowiązujące zasady w edytorze zasad, aby sprawdzić kolejność oceny zasad w każdym zakresie. Ogólnie rzecz biorąc, stosowane są tylko pierwsze cors zasady.
  • Pusta odpowiedź 200 OK — w niektórych konfiguracjach zasad niektóre żądania między źródłami kończą się pustą 200 OK odpowiedzią. Ta odpowiedź jest oczekiwana, gdy terminate-unmatched-request jest ustawiona na jej wartość true domyślną, a żądanie przychodzące ma Origin nagłówek, który nie jest zgodny z dozwolonym źródłem skonfigurowanym cors w zasadach.

Przykład

W tym przykładzie pokazano, jak obsługiwać żądania wstępne, takie jak te z niestandardowymi nagłówkami lub metodami innymi niż GET i POST. Aby obsługiwać nagłówki niestandardowe i inne czasowniki HTTP, użyj allowed-methods sekcji i allowed-headers , jak pokazano w poniższym przykładzie.

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

Powiązana zawartość

Aby uzyskać więcej informacji na temat pracy z zasadami, zobacz: