CORS

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

Notitie

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

Beleidsverklaring

<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

Naam Beschrijving Vereist Standaard
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 te verzenden in aanvragen voor meerdere domeinen. No false
terminate-unmatched-request Hiermee bepaalt u de verwerking van aanvragen voor meerdere oorsprongen die niet overeenkomen met de beleidsinstellingen.

Wanneer OPTIONS de aanvraag wordt verwerkt als een voorbereidende aanvraag en Origin de header niet overeenkomt met de 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 aanvraag voor meerdere origins) en 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, staat u toe dat de aanvraag normaal wordt uitgevoerd en voegt u geen CORS-headers toe aan het antwoord.
No true

Elementen

Naam Beschrijving Vereist Standaard
toegestane oorsprongen Bevat origin elementen die de toegestane origins voor aanvragen tussen domeinen beschrijven. allowed-origins kan één origin element bevatten dat aangeeft * dat een origin is toegestaan, of een of meer origin elementen die een URI bevatten. Ja N.v.t.
origin De waarde kan zijn om * alle origins toe te staan of een URI die één oorsprong aangeeft. De URI moet een schema, host en poort bevatten. Yes Als de poort wordt weggelaten in een URI, wordt poort 80 gebruikt voor HTTP en poort 443 voor HTTPS.
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. No Als deze sectie niet aanwezig GET is en POST wordt ondersteund.
method Hiermee geeft u een HTTP-werkwoord op. Er is ten minste één method element vereist als de allowed-methods sectie aanwezig is. N.v.t.
toegestane headers Dit element bevat header elementen die namen opgeven van de headers die kunnen worden opgenomen in de aanvraag. 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.
koptekst Hiermee geeft u een headernaam. Er is ten minste één header element vereist in allowed-headers of in expose-headers als die sectie aanwezig is. N.v.t.

Waarschuwing

Gebruik het * jokerteken met zorg in beleidsinstellingen. Deze configuratie is mogelijk te ruim en kan een API kwetsbaarder maken voor bepaalde API-beveiligingsbedreigingen.

kenmerken van toegestane methoden

Naam Beschrijving Vereist Standaard
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 voorbereidende antwoord in de cache op te cachen. No 0

Gebruik

Gebruiksopmerkingen

  • U kunt het cors beleid configureren voor meer dan één bereik (bijvoorbeeld bij het productbereik en het globale bereik). Zorg ervoor dat het base element is geconfigureerd bij de bewerkings-, API- en productbereiken om de benodigde beleidsregels op de bovenliggende bereiken over te nemen.
  • Alleen het cors beleid wordt geëvalueerd op de aanvraag tijdens de OPTIONS voorbereidende fase. Resterende geconfigureerde beleidsregels worden geëvalueerd op de goedgekeurde aanvraag.

Over CORS

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

CORS geeft twee typen aanvragen voor meerdere oorsprongen op:

  • Vooraf uitgevoerde aanvragen (of 'voorbereidende' 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 antwoord van de server de Access-Control-Allow-Origin header bevat die toegang toestaat, volgt de browser met de werkelijke aanvraag.

  • Eenvoudige aanvragen : deze aanvragen bevatten een of meer extra Origin headers, maar activeren geen CORS-preflight. Alleen aanvragen met de GET 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 van de ontwikkelaarsportal voor meer informatie.

    Notitie

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

  • Schakel API Management in om te reageren op voorbereidende aanvragen of om 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 de voorbereidende aanvraag die aan het cors beleid is gekoppeld, niet uitgevoerd. Daarom kunnen dergelijke bewerkingen worden gebruikt om aangepaste voorbereidende verwerkingslogica te implementeren, bijvoorbeeld om het cors beleid alleen onder bepaalde voorwaarden toe te passen.

Veelvoorkomende configuratieproblemen

  • Abonnementssleutel in header : als u het cors beleid configureert in 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 een queryparameter.
  • API met headerversiebeheer : als u het cors beleid configureert in het API-bereik en uw API gebruikmaakt van een header-versiebeheerschema, werkt het beleid niet omdat de versie wordt doorgegeven in een header. Mogelijk moet u een alternatieve versieringsmethode configureren, zoals een pad of queryparameter.
  • Beleidsvolgorde : u kunt onverwacht gedrag ondervinden als het cors beleid niet het eerste beleid in de binnenkomende sectie is. Selecteer Effectief beleid berekenen in de beleidseditor om de volgorde van de 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 cross-origin-aanvragen voltooid met een leeg 200 OK antwoord. Dit antwoord wordt verwacht wanneer terminate-unmatched-request 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.

Voorbeeld

In dit voorbeeld ziet u hoe u preflight-aanvragen kunt ondersteunen, 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 secties en allowed-headers , 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>

Volgende stappen

Zie voor meer informatie over het werken met beleid: