beleid voor meerdere domeinen API Management

Dit artikel bevat een naslaginformatie over API Management beleidsregels die worden gebruikt voor het inschakelen van aanroepen tussen domeinen van verschillende clients.

Meer informatie over beleidsregels:

Beleid voor meerdere domeinen

  • Aanroepen tussen domeinen toestaan : maakt de API toegankelijk vanuit Adobe Flash- en Microsoft Silverlight-browserclients.
  • CORS : hiermee wordt CORS-ondersteuning (Cross-Origin Resource Sharing) toegevoegd aan een bewerking of een API om aanroepen van meerdere domeinen van browserclients toe te staan.
  • JSONP : voegt JSON met opvullingsondersteuning (JSONP) toe aan een bewerking of een API om aanroepen tussen domeinen van JavaScript-browserclients toe te staan.

Oproepen tussen domeinen toestaan

Gebruik het cross-domain beleid om de API toegankelijk te maken vanuit Adobe Flash- en Microsoft Silverlight-browserclients.

Notitie

Stel de elementen en onderliggende elementen van het beleid in de volgorde in die in de beleidsverklaring is opgegeven. Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsverklaring

<cross-domain>
    <!-Policy configuration is in the Adobe cross-domain policy file format,
        see https://www.adobe.com/devnet-docs/acrobatetk/tools/AppSec/CrossDomain_PolicyFile_Specification.pdf-->
</cross-domain>

Voorbeeld

<cross-domain>
    <cross-domain-policy>
        <allow-http-request-headers-from domain='*' headers='*' />
    </cross-domain-policy>
</cross-domain>

Elementen

Naam Beschrijving Vereist
meerdere domeinen Hoofdelement. Onderliggende elementen moeten voldoen aan de specificatie van het beleid voor meerdere domeinen van Adobe. Yes

Waarschuwing

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

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -bereiken.

  • Beleidssecties: inkomend
  • Beleidsbereiken: globaal

CORS

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.

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:

  1. Vooraf uitgevoerde (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 serverantwoord de Access-Control-Allow-Origin header bevat die toegang toestaat, volgt de browser de werkelijke aanvraag.

  2. Eenvoudige aanvragen : deze aanvragen bevatten een of meer extra Origin headers, maar activeren geen CORS-voorbereiding. 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 voor de ontwikkelaarsportal voor meer informatie.

    Notitie

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

  • 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 voorbereidende aanvraagverwerkingslogica die aan het cors beleid is 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 header : 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 ervaren als het cors beleid niet het eerste beleid is in de sectie Binnenkomend verkeer. Selecteer Effectief beleid berekenen in de beleidseditor om de beleidsevaluatievolgorde voor elk bereik te controleren. Over het algemeen wordt alleen het eerste cors beleid toegepast.
  • Leeg 200 OK-antwoord : in sommige beleidsconfiguraties zijn 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.

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>

Voorbeeld

In dit voorbeeld ziet u hoe u voorbereidende 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 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>

Elementen

Naam Beschrijving Vereist Standaard
cors Hoofdelement. Yes N.v.t.
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. Yes N.v.t.
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. 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. 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. Yes N.v.t.
expose-headers Dit element bevat header elementen die namen opgeven van de headers die toegankelijk zijn voor de client. No 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-beveiligingsrisico's.

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 is van invloed op de mogelijkheid van de client om referenties in te dienen in aanvragen tussen domeinen. No onjuist
preflight-result-max-age De Access-Control-Max-Age header in het voorbereidende antwoord wordt ingesteld op de waarde van dit kenmerk en is van invloed op de mogelijkheid van de gebruikersagent om het preflight-antwoord op te cachen. No 0
terminate-unmatched-request Hiermee bepaalt u de verwerking van cross-origin-aanvragen die niet overeenkomen met de beleidsinstellingen. Wanneer OPTIONS de aanvraag wordt verwerkt als een voorbereidende aanvraag en Origin header niet overeenkomt met beleidsinstellingen: als het kenmerk is ingesteld true, beëindigt u de aanvraag onmiddellijk met een leeg 200 OK antwoord; Als het kenmerk is ingesteld falseop, 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 niet overeenkomt met beleidsinstellingen: Als het kenmerk is ingesteld trueop, 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 wordt voortgezet en voegt u geen CORS-headers toe aan het antwoord.
No true

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -bereiken.

  • Beleidssecties: inkomend
  • Beleidsbereiken: alle bereiken

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 bij de bovenliggende bereiken over te nemen.
  • Alleen het cors beleid wordt tijdens de voorbereiding op de OPTIONS aanvraag geëvalueerd. Resterende geconfigureerde beleidsregels worden geëvalueerd op de goedgekeurde aanvraag.

JSONP

Het jsonp beleid voegt JSON met opvullingsondersteuning (JSONP) toe aan een bewerking of een API om aanroepen tussen domeinen van JavaScript-browserclients toe te staan. JSONP is een methode die wordt gebruikt in JavaScript-programma's om gegevens op te vragen van een server in een ander domein. JSONP omzeilt de beperking die door de meeste webbrowsers wordt afgedwongen, waarbij de toegang tot webpagina's zich in hetzelfde domein moet bevinden.

Notitie

Stel de elementen en onderliggende elementen van het beleid in de volgorde in die in de beleidsverklaring is opgegeven. Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsverklaring

<jsonp callback-parameter-name="callback function name" />

Voorbeeld

<jsonp callback-parameter-name="cb" />

Als u de methode aanroept zonder de callback-parameter ?cb=XXX, retourneert deze gewone JSON (zonder een functieaanroep-wrapper).

Als u de callback-parameter ?cb=XXXtoevoegt, retourneert deze een JSONP-resultaat, waardoor de oorspronkelijke JSON-resultaten rond de callback-functie worden verpakt, zoals XYZ('<json result goes here>');

Elementen

Naam Beschrijving Vereist
jsonp Hoofdelement. Yes

Kenmerken

Naam Beschrijving Vereist Standaard
callback-parameter-name De JavaScript-functie voor meerdere domeinen, voorafgegaan door de volledig gekwalificeerde domeinnaam waarin de functie zich bevindt. Yes N.v.t.

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -bereiken.

  • Beleidssecties: uitgaand
  • Beleidsbereiken: alle bereiken

Volgende stappen

Zie voor meer informatie over het werken met beleid: