Delen via

CORS

  • Artikel

VAN TOEPASSING OP: Alle API Management-lagen

Het cors beleid voegt CORS-ondersteuning (Cross-Origin Resource Sharing) toe aan een bewerking of API om aanroepen tussen domeinen van browserclients toe te staan.

Notitie

Stel de elementen en onderliggende elementen van het beleid in de volgorde in die in de beleidsverklaring is opgegeven. Om u te helpen dit beleid te configureren, biedt de portal een begeleide editor op basis van formulieren. Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Kenmerken

Meetcriterium Beschrijving Vereist Standaardinstelling
allow-credentials De Access-Control-Allow-Credentials header in het voorbereidende antwoord wordt ingesteld op de waarde van dit kenmerk en heeft invloed op de mogelijkheid van de client om referenties in aanvragen tussen domeinen in te dienen. Beleidsexpressies zijn toegestaan. Nee false
beëindiging van niet-overeenkomende aanvraag Hiermee bepaalt u de verwerking van cross-origin-aanvragen die niet overeenkomen met de beleidsinstellingen. Beleidsexpressies zijn toegestaan.

Wanneer OPTIONS de aanvraag wordt verwerkt als een voorbereidende aanvraag en Origin de header niet overeenkomt met beleidsinstellingen:
- Als het kenmerk is ingesteld op true, beëindigt u de aanvraag onmiddellijk met een leeg 200 OK antwoord
- Als het kenmerk is ingesteld op false, controleert u inkomend op andere beleidsregels binnen het bereik cors die directe onderliggende elementen van het binnenkomende element zijn en past u deze toe. Als er geen cors beleid wordt gevonden, beëindigt u de aanvraag met een leeg 200 OK antwoord.

Wanneer GET of HEAD aanvraag de Origin header bevat (en daarom wordt verwerkt als een eenvoudige cross-origin-aanvraag), en komt deze niet overeen met beleidsinstellingen:
- Als het kenmerk is ingesteld op true, beëindigt u de aanvraag onmiddellijk met een leeg 200 OK antwoord.
- Als het kenmerk is ingesteld falseop, staat u toe dat de aanvraag normaal doorgaat en voegt u geen CORS-headers toe aan het antwoord.		 Nee true

Elementen

Name Beschrijving Vereist Standaardinstelling
toegestane oorsprongen Bevat origin elementen die de toegestane oorsprongen beschrijven voor aanvragen tussen domeinen. allowed-origins kan één origin element bevatten dat aangeeft * dat een oorsprong is toegestaan, of een of meer origin elementen die een URI bevatten. Ja N.v.t.
toegestane methoden Dit element is vereist als andere methoden dan GET of POST zijn toegestaan. Bevat method elementen die de ondersteunde HTTP-woorden opgeven. De waarde * geeft alle methoden aan. Nee Als deze sectie niet aanwezig GET is en POST wordt ondersteund.
toegestane headers Dit element bevat header elementen die namen opgeven van de headers die in de aanvraag kunnen worden opgenomen. Ja N.v.t.
expose-headers Dit element bevat header elementen die namen opgeven van de headers die toegankelijk zijn voor de client. Nee N.v.t.

Let op

Gebruik het * jokerteken met zorg in beleidsinstellingen. Deze configuratie is mogelijk te slecht en kan een API kwetsbaarder maken voor bepaalde API-beveiligingsrisico's.

elementen van toegestane oorsprong

Name Beschrijving Vereist Standaardinstelling
origin De waarde kan zijn * om alle oorsprongen toe te staan of een URI die één oorsprong aangeeft. De URI moet een schema, host en poort bevatten. Voer geen aanhalingstekens in. Ja Als de poort wordt weggelaten in een URI, wordt poort 80 gebruikt voor HTTP en poort 443 voor HTTPS.

kenmerken van toegestane methoden

Name Beschrijving Vereist Standaardinstelling
preflight-result-max-age De Access-Control-Max-Age header in het voorbereidende antwoord wordt ingesteld op de waarde van dit kenmerk en heeft invloed op de mogelijkheid van de gebruikersagent om het preflight-antwoord in de cache op te cachen. Beleidsexpressies zijn toegestaan. Nee 0

elementen met toegestane methoden

Name Beschrijving Vereist Standaardinstelling
methode Hiermee geeft u een HTTP-woord. Beleidsexpressies zijn toegestaan. Er is ten minste één method element vereist als de allowed-methods sectie aanwezig is. N.v.t.

elementen voor toegestane headers

Name Beschrijving Vereist Default
koptekst Hiermee geeft u een headernaam. Er is ten minste één header element vereist als allowed-headers deze sectie aanwezig is. N.v.t.

elementen van expose-headers

Name Beschrijving Vereist Default
koptekst Hiermee geeft u een headernaam. Er is ten minste één header element vereist als expose-headers deze sectie aanwezig is. N.v.t.

Gebruik

Gebruiksnotities

  • U kunt het cors beleid configureren op meer dan één bereik (bijvoorbeeld bij het productbereik en het globale bereik). Zorg ervoor dat het base element is geconfigureerd bij de bewerking, API en productbereiken om de benodigde beleidsregels over te nemen in de bovenliggende bereiken.
  • Alleen het cors beleid wordt geëvalueerd op de OPTIONS aanvraag tijdens de voorbereidende vlucht. Resterende geconfigureerde beleidsregels worden geëvalueerd op de goedgekeurde aanvraag.
  • Dit beleid kan slechts eenmaal worden gebruikt in een beleidssectie.

Over CORS

CORS is een op HTTP-header gebaseerde standaard waarmee een browser en een server kunnen communiceren en bepalen of specifieke cross-origin-aanvragen (XMLHttpRequest aanroepen van JavaScript op een webpagina naar andere domeinen al dan niet mogen worden toegestaan). Dit biedt meer flexibiliteit dan alleen aanvragen van dezelfde oorsprong toestaan, maar is veiliger dan het toestaan van alle cross-origin-aanvragen.

CORS specificeert twee soorten cross-origin-aanvragen:

  • Vooraf uitgevoerde (of 'preflight'-aanvragen : de browser verzendt eerst een HTTP-aanvraag met behulp van de OPTIONS methode naar de server om te bepalen of de werkelijke aanvraag mag worden verzonden. Als het serverantwoord de Access-Control-Allow-Origin header bevat die toegang toestaat, volgt de browser de werkelijke aanvraag.

  • Eenvoudige aanvragen : deze aanvragen bevatten een of meer extra Origin headers, maar activeren geen CORS-voorbereidende bewerking. Alleen aanvragen die gebruikmaken van de GET en methoden en HEAD een beperkte set aanvraagheaders zijn toegestaan.

cors beleidsscenario's

Configureer het cors beleid in API Management voor de volgende scenario's:

  • Schakel de interactieve testconsole in de ontwikkelaarsportal in. Raadpleeg de documentatie over de ontwikkelaarsportal voor meer informatie.

    Notitie

    Wanneer u CORS inschakelt voor de interactieve console, configureert API Management standaard het cors beleid op het globale bereik.

  • Schakel API Management in om voorbereidende aanvragen te beantwoorden of eenvoudige CORS-aanvragen door te geven wanneer de back-ends geen eigen CORS-ondersteuning bieden.

    Notitie

    Als een aanvraag overeenkomt met een bewerking met een OPTIONS methode die is gedefinieerd in de API, wordt de verwerkingslogica voor voorbereidende aanvragen die aan het cors beleid zijn gekoppeld, niet uitgevoerd. Dergelijke bewerkingen kunnen daarom worden gebruikt om aangepaste preflightverwerkingslogica te implementeren, bijvoorbeeld om het cors beleid alleen onder bepaalde voorwaarden toe te passen.

Veelvoorkomende configuratieproblemen

  • Abonnementssleutel in koptekst : als u het cors beleid configureert op het productbereik en uw API gebruikmaakt van verificatie van abonnementssleutels, werkt het beleid niet wanneer de abonnementssleutel wordt doorgegeven in een header. Als tijdelijke oplossing kunt u aanvragen wijzigen om een abonnementssleutel op te nemen als queryparameter.
  • API met headerversiebeheer : als u het cors beleid configureert op het API-bereik en uw API gebruikmaakt van een schema voor headerversiebeheer, werkt het beleid niet omdat de versie wordt doorgegeven in een header. Mogelijk moet u een alternatieve versiebeheermethode configureren, zoals een pad- of queryparameter.
  • Beleidsvolgorde : u kunt onverwacht gedrag ondervinden als het cors beleid niet het eerste beleid is in de sectie Inkomend verkeer. Selecteer Effectief beleid berekenen in de beleidseditor om de volgorde van beleidsevaluatie voor elk bereik te controleren. Over het algemeen wordt alleen het eerste cors beleid toegepast.
  • Leeg 200 OK-antwoord : in sommige beleidsconfiguraties worden bepaalde aanvragen voor cross-origin voltooid met een leeg 200 OK antwoord. Dit antwoord wordt verwacht wanneer terminate-unmatched-request deze is ingesteld op de standaardwaarde van true en een binnenkomende aanvraag een Origin header heeft die niet overeenkomt met een toegestane oorsprong die is geconfigureerd in het cors beleid.

Opmerking

In dit voorbeeld ziet u hoe u voorbereidende aanvragen ondersteunt , zoals aanvragen met aangepaste headers of andere methoden dan GET en POST. Als u aangepaste headers en andere HTTP-woorden wilt ondersteunen, gebruikt u de allowed-methods en allowed-headers secties, zoals wordt weergegeven in het volgende voorbeeld.

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

Gerelateerde inhoud

Zie voor meer informatie over het werken met beleid: