CORS

  • Artikel

GILT FÜR: Alle API Management-Ebenen

Die cors-Richtlinie fügt Unterstützung für CORS (Cross-Origin Resource Sharing) einer Operation oder einer API hinzu, um domänenübergreifende Aufrufe von browserbasierten Clients aus zu ermöglichen.

Hinweis

Legen Sie die Elemente und untergeordneten Elemente einer Richtlinie in der Reihenfolge fest, die in der Richtlinienanweisung angegeben ist. Das Portal unterstützt Sie bei der Konfiguration dieser Richtlinie durch einen formularbasierten, angeleiteten Editor. Erfahren Sie mehr darüber, wie Sie API Management-Richtlinien festlegen oder bearbeiten.

Richtlinienanweisung

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

Attributes

Name BESCHREIBUNG Erforderlich Standard
allow-credentials Der Header Access-Control-Allow-Credentials in der Preflightantwort wird auf den Wert dieses Attributs festgelegt und wirkt sich auf die Fähigkeit des Clients aus, Anmeldeinformationen in domänenübergreifenden Anforderungen zu senden. Richtlinienausdrücke sind zulässig. Nein false
terminate-unmatched-request Steuert die Verarbeitung von Cross-Origin-Anforderungen, die nicht mit den Richtlinieneinstellungen übereinstimmen. Richtlinienausdrücke sind zulässig.

Wenn die OPTIONS-Anforderung als Preflightanforderung verarbeitet wird und der Origin-Header nicht mit den Richtlinieneinstellungen übereinstimmt:
– Falls das Attribut auf true festgelegt ist, wird die Anforderung sofort mit einer leeren Antwort 200 OK beendet.
– Falls das Attribut auf false festgelegt ist, werden eingehende Daten auf andere im Bereich liegende cors-Richtlinien überprüft, die dem eingehenden Element direkt untergeordnet sind. Anschließend werden diese Richtlinien angewendet. Wenn keine cors Richtlinien gefunden werden, beenden Sie die Anforderung mit einer leeren 200 OK Antwort.

Wenn die GET- oder HEAD-Anforderung den Origin-Header enthält (und daher als einfache ursprungsübergreifende Anforderung verarbeitet wird) und nicht mit den Richtlinieneinstellungen übereinstimmt:
– Falls das Attribut auf true festgelegt ist, wird die Anforderung sofort mit einer leeren Antwort 200 OK beendet.
– Wenn das Attribut auf false festgelegt ist, wird eine normale Fortsetzung der Anforderung zugelassen, und der Antwort werden keine CORS-Header hinzugefügt.		 Nein true

Elemente

Name BESCHREIBUNG Erforderlich Standard
allowed-origins Enthält origin-Elemente, die die zulässigen Ursprünge für domänenübergreifende Anforderungen beschreiben. allowed-origins kann entweder ein einzelnes origin-Element enthalten, das * angibt, um einen beliebigen Ursprung zuzulassen, oder ein oder mehrere origin-Elemente, die einen URI enthalten. Ja –
allowed-methods Dieses Element ist erforderlich, wenn andere Methoden als GET oder POST zulässig sind. Enthält method-Elemente, die die unterstützten HTTP-Verben angeben. Der Wert * dient zum Angeben aller Methoden. Nein Wenn dieser Abschnitt nicht vorhanden ist, werdenGET und POST unterstützt.
allowed-headers Dieses Element enthält header-Elemente, die die Namen der Header angeben, die in der Anforderung enthalten sein können. Ja –
expose-headers Dieses Element enthält header-Elemente, die die Namen der Header angeben, auf die der Client zugreifen kann. Nein –

Achtung

Verwenden Sie den *-Platzhalter in Richtlinieneinstellungen nach sorgfältiger Überlegung. Diese Konfiguration kann übermäßig freizügig sein und eine API anfälliger für bestimmte API-Sicherheitsbedrohungen machen.

allowed-origins-Elemente

Name BESCHREIBUNG Erforderlich Standard
origin Der Wert kann entweder * lauten, um alle Ursprünge zuzulassen, oder ein URI sein, der einen einzelnen Ursprung angibt. Die URI muss Schema, Host und Port enthalten. Geben Sie keine Anführungszeichen ein. Ja Wenn der Port in einem URI ausgelassen wird, wird Port 80 für HTTP bzw. Port 443 für HTTPS verwendet.

allowed-methods-Attribute

Name BESCHREIBUNG Erforderlich Standard
preflight-result-max-age Der Access-Control-Max-Age Header in der Preflight-Antwort wird auf den Wert dieses Attributs gesetzt und wirkt sich auf die Fähigkeit des Benutzeragenten aus, die Preflight-Antwort zwischenzuspeichern. Richtlinienausdrücke sind zulässig. Nein 0

allowed-methods-Elemente

Name BESCHREIBUNG Erforderlich Standard
method Gibt ein HTTP-Verb an. Richtlinienausdrücke sind zulässig. Mindestens ein method-Element ist erforderlich, wenn der Abschnitt allowed-methods vorhanden ist. –

allowed-headers-Elemente

Name BESCHREIBUNG Erforderlich Standard
header Gibt einen Headernamen an. Mindestens ein header-Element ist in allowed-headers erforderlich, wenn der Abschnitt vorhanden ist. –

expose-headers-Elemente

Name BESCHREIBUNG Erforderlich Standard
header Gibt einen Headernamen an. Mindestens ein header-Element ist in expose-headers erforderlich, wenn der Abschnitt vorhanden ist. –

Verwendung

Hinweise zur Verwendung

  • Sie können die cors Richtlinie in mehr als einem Bereich konfigurieren (z. B. im Produktbereich und im globalen Bereich). Stellen Sie sicher, dass das base Element für den Vorgang, die API und den Produktbereich konfiguriert ist, um erforderliche Richtlinien in den übergeordneten Bereichen zu erben.
  • Nur die cors-Richtlinie wird bei der OPTIONS-Anforderung während des Preflights ausgewertet. Die verbleibenden konfigurierten Richtlinien werden für die genehmigte Anforderung ausgewertet.
  • Diese Richtlinie kann nur einmal in einem Richtlinienabschnitt verwendet werden.

Über CORS

CORS ist ein HTTP-Header-basierter Standard, der es einem Browser und einem Server ermöglicht, zu interagieren und zu bestimmen, ob bestimmte Cross-Origin-Anforderung(XMLHttpRequest Aufrufe von JavaScript auf einer Webseite an andere Domänen) zugelassen werden sollen oder nicht. Dies bietet mehr Flexibilität als wenn nur Anfragen gleichen Ursprungs erlaubt sind, und ist gleichzeitig sicherer als wenn alle ursprungsübergreifenden Anfragen erlaubt sind.

CORS spezifiziert zwei Arten von Cross-Origin-Anforderungen:

  • Vorababfragen (oder „Preflight“) - Der Browser sendet zuerst eine HTTP-Anforderung mit der OPTIONS-Methode an den Server, um festzustellen, ob die eigentliche Anforderung zum Senden berechtigt ist. Wenn die Serverantwort den Access-Control-Allow-Origin-Header enthält, der den Zugriff erlaubt, folgt der Browser mit der eigentlichen Anforderung.

  • Einfache Anforderungen – Diese Anforderungen enthalten einen oder mehrere zusätzliche Origin-Header, lösen jedoch keinen CORS-Preflight aus. Es sind nur zulässig, die die GET- und HEAD-Methoden und eine begrenzte Anzahl von Anforderungsheadern verwenden.

cors Richtlinien-Szenarien

Konfiguriert die cors-Richtlinie in API Management für die folgenden Szenarien:

  • Aktiviert die interaktive Testkonsole im Entwicklerportal. Ausführliche Informationen finden Sie in der Dokumentation zum Entwicklerportal.

    Hinweis

    Wenn Sie CORS für die interaktive Konsole aktivieren, konfiguriert API Management die cors-Richtlinie standardmäßig im globalen Bereich.

  • Aktivieren Sie API Management, um auf Preflight-Anforderungen zu antworten oder einfache CORS-Anforderungen weiterzuleiten, wenn die Back-Ends keine eigene CORS-Unterstützung bereitstellen.

    Hinweis

    Wenn eine Anforderung mit einer Operation mit einer in der API definierten OPTIONS-Methode übereinstimmt, wird die mit der cors-Richtlinie verknüpfte Preflight-Anforderungsverarbeitungslogik nicht ausgeführt. Daher können solche Operationen verwendet werden, um eine benutzerdefinierte Preflight-Verarbeitungslogik zu implementieren – beispielsweise um die cors-Richtlinie nur unter bestimmten Bedingungen anzuwenden.

Allgemeine Konfigurationsprobleme

  • Abonnementschlüssel im Header – Wenn Sie die cors-Richtlinie im Bereich Produkt konfigurieren und Ihre API die Abonnementschlüsselauthentifizierung verwendet, funktioniert die Richtlinie nicht, wenn der Abonnementschlüssel in einem Header übergeben wird. Um das Problem zu umgehen, ändern Sie Anforderungen so, dass sie einen Abonnementschlüssel als Abfrageparameter enthalten.
  • API mit Header-Versionsverwaltung – Wenn Sie die cors-Richtlinie im Bereich API konfigurieren und Ihre API ein Header-Versionierungsschema verwendet, funktioniert die Richtlinie nicht, da die Version in einem Header übergeben wird. Möglicherweise müssen Sie eine alternative Versionsverwaltungsmethode konfigurieren, z. B. einen Pfad oder einen Abfrageparameter.
  • Richtlinienreihenfolge – Es kann zu unerwartetem Verhalten kommen, wenn die cors-Richtlinie nicht die erste Richtlinie im eingehenden Abschnitt ist. Wählen Sie im Richtlinieneditor Effektive Richtlinie berechnen, um die Richtlinienauswertungsreihenfolge für jeden Bereich zu überprüfen. Im Allgemeinen wird nur die erste cors-Richtlinie angewendet.
  • Leere 200 OK-Antwort – In einigen Richtlinienkonfigurationen werden bestimmte ursprungsübergreifende Anforderungen mit einer leeren 200 OK Antwort abgeschlossen. Diese Antwort wird erwartet, wenn terminate-unmatched-request auf den Standardwert true gesetzt ist und eine eingehende Anforderung einen Origin-Header hat, der nicht mit einem zulässigen Ursprung übereinstimmt, der in der cors-Richtlinie konfiguriert ist.

Beispiel

Dieses Beispiel zeigt, wie Preflight-Anforderungen unterstützt werden, z. B. solche mit benutzerdefinierten Headern oder anderen Methoden als GET und POST. Um benutzerdefinierte Header und andere HTTP-Verben zu unterstützen, verwenden Sie die allowed-methods und allowed-headers Abschnitte wie im folgenden Beispiel gezeigt.

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

Zugehöriger Inhalt

Weitere Informationen zum Arbeiten mit Richtlinien finden Sie hier: