API Management access restriction policies (Beleid voor toegangsbeperking API Management)

  • Artikel
  • 20 minuten om te lezen

In dit onderwerp vindt u een naslag voor de volgende API Management beleidsregels. Zie Beleidsregels in API Management voor meer informatie over het toevoegen en configureren API Management.

Toegangsbeperkingsbeleid

Tip

U kunt voor verschillende doeleinden toegangsbeperkingsbeleid gebruiken in verschillende bereiken. U kunt bijvoorbeeld de hele API beveiligen met AAD-verificatie door het beleid toe te passen op API-niveau of u kunt het toepassen op het API-bewerkingsniveau en gebruiken voor validate-jwt claims gedetailleerdere controle.

HTTP-header controleren

Gebruik het check-header beleid om af te dwingen dat een aanvraag een opgegeven HTTP-header heeft. U kunt eventueel controleren of de header een specifieke waarde heeft of op een bereik van toegestane waarden controleren. Als de controle mislukt, beëindigt het beleid de verwerking van aanvragen en retourneert het de HTTP-statuscode en het foutbericht dat is opgegeven door het beleid.

Beleidsverklaring

<check-header name="header name" failed-check-httpcode="code" failed-check-error-message="message" ignore-case="true">
    <value>Value1</value>
    <value>Value2</value>
</check-header>

Voorbeeld

<check-header name="Authorization" failed-check-httpcode="401" failed-check-error-message="Not authorized" ignore-case="false">
    <value>f6dc69a089844cf6b2019bae6d36fac8</value>
</check-header>

Elementen

Naam Beschrijving Vereist
check-header Hoofdelement. Yes
waarde Toegestane http-headerwaarde. Wanneer meerdere waarde-elementen zijn opgegeven, wordt de controle beschouwd als geslaagd als een van de waarden een overeenkomst is. No

Kenmerken

Naam Beschrijving Vereist Standaard
failed-check-error-message Foutbericht dat wordt weergegeven in de hoofdtekst van het HTTP-antwoord als de header niet bestaat of een ongeldige waarde heeft. Dit bericht moet speciale tekens bevatten met de juiste escape-tekens. Yes N.v.t.
failed-check-httpcode HTTP-statuscode die moet worden retourneert als de header niet bestaat of een ongeldige waarde heeft. Yes N.v.t.
header-name De naam van de te controleren HTTP-header. Yes N.v.t.
ignore-case Kan worden ingesteld op Waar of Onwaar. Als de waarde is ingesteld op True wordt genegeerd wanneer de headerwaarde wordt vergeleken met de set acceptabele waarden. Yes N.v.t.

Gebruik

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

  • Beleidssecties: inkomende, uitgaande

  • Beleidsbereiken: alle scopes

Aanroepfrequentie per abonnement beperken

Het beleid voorkomt pieken in HET API-gebruik per abonnement door de aanroepfrequentie te beperken tot een opgegeven aantal rate-limit per opgegeven periode. Wanneer de aanroepfrequentie wordt overschreden, ontvangt de aanroeper een 429 Too Many Requests antwoordstatuscode.

Belangrijk

Dit beleid kan slechts één keer per beleidsdocument worden gebruikt.

Beleidsexpressie kan niet worden gebruikt in een van de beleidskenmerken voor dit beleid.

Waarschuwing

Vanwege de gedistribueerde aard van de beperkingsarchitectuur is snelheidsbeperking nooit volledig nauwkeurig. Het verschil tussen geconfigureerde aanvragen en het werkelijke aantal toegestane aanvragen varieert op basis van aanvraagvolume en -frequentie, back-endlatentie en andere factoren.

Notitie

Zie Snelheidslimieten en quota voor meer inzicht in het verschil tussen snelheidslimieten en quota.

Beleidsverklaring

<rate-limit calls="number" renewal-period="seconds">
    <api name="API name" id="API id" calls="number" renewal-period="seconds">
        <operation name="operation name" id="operation id" calls="number" renewal-period="seconds" 
        retry-after-header-name="header name" 
        retry-after-variable-name="policy expression variable name"
        remaining-calls-header-name="header name"  
        remaining-calls-variable-name="policy expression variable name"
        total-calls-header-name="header name"/>
    </api>
</rate-limit>

Voorbeeld

In het volgende voorbeeld is de limiet per abonnement 20 aanroepen per 90 seconden. Na elke beleidsuitvoering worden de resterende aanroepen die zijn toegestaan in de periode opgeslagen in de variabele remainingCallsPerSubscription .

<policies>
    <inbound>
        <base />
        <rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/>
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Elementen

Naam Beschrijving Vereist
snelheidslimiet Hoofdelement. Yes
api Voeg een of meer van deze elementen toe om een aanroepfrequentielimiet op te leggen voor API's binnen het product. Product- en API-aanroepfrequentielimieten worden onafhankelijk toegepast. Er kan naar de API worden verwezen via name of id . Als beide kenmerken zijn opgegeven, id worden gebruikt en worden name genegeerd. No
bewerking Voeg een of meer van deze elementen toe om een aanroepfrequentielimiet op te leggen voor bewerkingen binnen een API. Limieten voor de aanroepfrequentie van producten, API's en bewerking worden onafhankelijk toegepast. Er kan naar de bewerking worden verwezen via name of id . Als beide kenmerken zijn opgegeven, id worden gebruikt en worden name genegeerd. No

Kenmerken

Naam Beschrijving Vereist Standaard
naam De naam van de API waarop de snelheidslimiet moet worden toegepast. Yes N.v.t.
Oproepen Het maximale totale aantal aanroepen dat is toegestaan tijdens het tijdsinterval dat is opgegeven in renewal-period . Yes N.v.t.
verlengingsperiode De lengte in seconden van de sliding window gedurende welke het aantal toegestane aanvragen niet groter mag zijn dan de waarde die is opgegeven in calls . Maximaal toegestane waarde: 300 seconden. Yes N.v.t.
retry-after-header-name De naam van een antwoordheader waarvan de waarde het aanbevolen interval voor opnieuw proberen is in seconden nadat de opgegeven aanroepfrequentie is overschreden. No N.v.t.
retry-after-variable-name De naam van een beleidsexpressievariabele waarin het aanbevolen interval voor opnieuw proberen wordt opgeslagen in seconden nadat de opgegeven aanroepfrequentie is overschreden. No N.v.t.
remaining-calls-header-name De naam van een antwoordheader waarvan de waarde na elke beleidsuitvoering het aantal resterende aanroepen is dat is toegestaan voor het tijdsinterval dat is opgegeven in renewal-period de . No N.v.t.
remaining-calls-variable-name De naam van een beleidsexpressievariabele die na elke beleidsuitvoering het aantal resterende aanroepen opgeslagen dat is toegestaan voor het tijdsinterval dat is opgegeven in renewal-period de . No N.v.t.
total-calls-header-name De naam van een antwoordheader waarvan de waarde de waarde is die is opgegeven in calls . No N.v.t.

Gebruik

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

  • Beleidssecties: inkomende

  • Beleidsbereiken: product, API, bewerking

Aanroepfrequentie per sleutel beperken

Belangrijk

Deze functie is niet beschikbaar in de verbruikslaag van API Management.

Het beleid voorkomt pieken in API-gebruik per sleutel door de aanroepfrequentie te beperken tot een opgegeven getal rate-limit-by-key per opgegeven periode. De sleutel kan een willekeurige tekenreekswaarde hebben en wordt doorgaans opgegeven met behulp van een beleidsexpressie. Er kan een optionele voorwaarde voor verhoging worden toegevoegd om op te geven welke aanvragen moeten worden meegetelde voor de limiet. Wanneer deze aanroepfrequentie wordt overschreden, ontvangt de aanroeper een 429 Too Many Requests antwoordstatuscode.

Zie Geavanceerde aanvraagbeperking met Azure API Management voor meer informatie en voorbeelden van dit API Management.

Waarschuwing

Vanwege de gedistribueerde aard van de beperkingsarchitectuur is snelheidsbeperking nooit volledig nauwkeurig. Het verschil tussen geconfigureerde aanvragen en het werkelijke aantal toegestane aanvragen varieert op basis van aanvraagvolume en -frequentie, back-endlatentie en andere factoren.

Notitie

Zie Snelheidslimieten en quota voor meer inzicht in het verschil tussen snelheidslimieten en quota.

Beleidsverklaring

<rate-limit-by-key calls="number"
                   renewal-period="seconds"
                   increment-condition="condition"
                   counter-key="key value" 
                   retry-after-header-name="header name" retry-after-variable-name="policy expression variable name"
                   remaining-calls-header-name="header name"  remaining-calls-variable-name="policy expression variable name"
                   total-calls-header-name="header name"/>

Voorbeeld

In het volgende voorbeeld wordt de snelheidslimiet van 10 aanroepen per 60 seconden door het IP-adres van de aanroeper versleuteld. Na elke beleidsuitvoering worden de resterende aanroepen die zijn toegestaan in de periode opgeslagen in de variabele remainingCallsPerIP .

<policies>
    <inbound>
        <base />
        <rate-limit-by-key  calls="10"
              renewal-period="60"
              increment-condition="@(context.Response.StatusCode == 200)"
              counter-key="@(context.Request.IpAddress)"
              remaining-calls-variable-name="remainingCallsPerIP"/>
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Elementen

Naam Beschrijving Vereist
rate-limit-by-key Hoofdelement. Yes

Kenmerken

Naam Beschrijving Vereist Standaard
Oproepen Het maximumaantal aanroepen dat is toegestaan tijdens het tijdsinterval dat is opgegeven in de renewal-period . Beleidsexpressie is toegestaan. Yes N.v.t.
tellersleutel De sleutel die moet worden gebruikt voor het beleid voor de snelheidslimiet. Yes N.v.t.
increment-condition De Booleaanse expressie die opgeeft of de aanvraag moet worden geteld voor de snelheid ( true ). No N.v.t.
verlengingsperiode De lengte in seconden van de sliding window gedurende welke het aantal toegestane aanvragen niet groter mag zijn dan de waarde die is opgegeven in calls . Beleidsexpressie is toegestaan. Maximaal toegestane waarde: 300 seconden. Yes N.v.t.
retry-after-header-name De naam van een antwoordheader waarvan de waarde het aanbevolen interval voor opnieuw proberen is in seconden nadat de opgegeven aanroepfrequentie is overschreden. No N.v.t.
retry-after-variable-name De naam van een beleidsexpressievariabele waarin het aanbevolen interval voor opnieuw proberen wordt opgeslagen in seconden nadat de opgegeven aanroepfrequentie is overschreden. No N.v.t.
remaining-calls-header-name De naam van een antwoordheader waarvan de waarde na elke beleidsuitvoering het aantal resterende aanroepen is dat is toegestaan voor het tijdsinterval dat is opgegeven in renewal-period de . No N.v.t.
remaining-calls-variable-name De naam van een beleidsexpressievariabele die na elke beleidsuitvoering het aantal resterende aanroepen opgeslagen dat is toegestaan voor het tijdsinterval dat is opgegeven in renewal-period de . No N.v.t.
total-calls-header-name De naam van een antwoordheader waarvan de waarde de waarde is die is opgegeven in calls . No N.v.t.

Gebruik

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

  • Beleidssecties: inkomende

  • Beleidsbereiken: alle scopes

IP's van aanroepers beperken

Met de beleidsfilters worden aanroepen van specifieke IP-adressen en/of adresbereiken gefilterd ip-filter (wordt/wordt dit niet mogelijk gemaakt).

Beleidsverklaring

<ip-filter action="allow | forbid">
    <address>address</address>
    <address-range from="address" to="address" />
</ip-filter>

Voorbeeld

In het volgende voorbeeld staat het beleid alleen aanvragen toe die afkomstig zijn van één IP-adres of bereik van opgegeven IP-adressen

<ip-filter action="allow">
    <address>13.66.201.169</address>
    <address-range from="13.66.140.128" to="13.66.140.143" />
</ip-filter>

Elementen

Naam Beschrijving Vereist
ip-filter Hoofdelement. Yes
adres Hiermee geeft u één IP-adres op waarop moet worden gefilterd. Er is ten address minste één element of address-range vereist.
address-range from="address" to="address" Hiermee geeft u een bereik van IP-adres waarop moet worden gefilterd. Er is ten address minste één element of address-range vereist.

Kenmerken

Naam Beschrijving Vereist Standaard
address-range from="address" to="address" Een bereik van IP-adressen voor het toestaan of weigeren van toegang. Vereist wanneer het address-range element wordt gebruikt. N.v.t.
ip-filter action="allow | forbid" Hiermee geeft u op of aanroepen al dan niet moeten worden toegestaan voor de opgegeven IP-adressen en -adresbereiken. Yes N.v.t.

Gebruik

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

  • Beleidssecties: inkomende
  • Beleidsbereiken: alle scopes

Gebruiksquotum per abonnement instellen

Het quota beleid dwingt een verlengbaar of levensduur aanroepvolume en/of bandbreedtequotum af per abonnement.

Belangrijk

Dit beleid kan slechts één keer per beleidsdocument worden gebruikt.

Beleidsexpressie kan niet worden gebruikt in een van de beleidskenmerken voor dit beleid.

Notitie

Zie Snelheidslimieten en quota voor meer inzicht in het verschil tussen snelheidslimieten en quota.

Beleidsverklaring

<quota calls="number" bandwidth="kilobytes" renewal-period="seconds">
    <api name="API name" id="API id" calls="number" renewal-period="seconds" />
        <operation name="operation name" id="operation id" calls="number" renewal-period="seconds" />
    </api>
</quota>

Voorbeeld

<policies>
    <inbound>
        <base />
        <quota calls="10000" bandwidth="40000" renewal-period="3600" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Elementen

Naam Beschrijving Vereist
quota Hoofdelement. Yes
api Voeg een of meer van deze elementen toe om aanroepquota toe te voegen aan API's binnen het product. Quota voor product- en API-aanroepen worden onafhankelijk toegepast. Er kan naar de API worden verwezen via name of id . Als beide kenmerken zijn opgegeven, id worden gebruikt en worden name genegeerd. No
bewerking Voeg een of meer van deze elementen toe om aanroepquota toe te voegen aan bewerkingen binnen een API. Quota voor product-, API- en bewerkingsoproepen worden onafhankelijk toegepast. Er kan naar de bewerking worden verwezen via name of id . Als beide kenmerken zijn opgegeven, id worden gebruikt en worden name genegeerd. No

Kenmerken

Naam Beschrijving Vereist Standaard
naam De naam van de API of bewerking waarvoor het quotum van toepassing is. Yes N.v.t.
Bandbreedte Het maximale totale aantal kilobytes dat is toegestaan tijdens het tijdsinterval dat is opgegeven in de renewal-period . Zowel calls , als beide moeten samen worden bandwidth opgegeven. N.v.t.
Oproepen Het maximumaantal aanroepen dat is toegestaan tijdens het tijdsinterval dat is opgegeven in de renewal-period . Zowel calls , als beide moeten samen worden bandwidth opgegeven. N.v.t.
verlengingsperiode De periode in seconden waarna het quotum opnieuw wordt ingesteld. Wanneer deze is ingesteld op de 0 periode is ingesteld op oneindig. Yes N.v.t.

Gebruik

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

  • Beleidssecties: inkomende
  • Beleidsbereiken: product

Gebruiksquotum per sleutel instellen

Belangrijk

Deze functie is niet beschikbaar in de verbruikslaag van API Management.

Het quota-by-key beleid dwingt een verlengbaar of levensduur aanroepvolume en/of bandbreedtequotum per sleutel af. De sleutel kan een willekeurige tekenreekswaarde hebben en wordt doorgaans opgegeven met behulp van een beleidsexpressie. Optionele voorwaarde voor verhoging kan worden toegevoegd om op te geven welke aanvragen moeten worden geteld voor het quotum. Als meerdere beleidsregels dezelfde sleutelwaarde verhogen, wordt deze slechts één keer per aanvraag verhoogd. Wanneer de aanroepfrequentie wordt overschreden, ontvangt de aanroeper een 403 Forbidden antwoordstatuscode.

Zie Geavanceerde aanvraagbeperking met Azure API Management voor meer informatie en voorbeelden van dit beleid.

Notitie

Zie Snelheidslimieten en quota voor meer inzicht in het verschil tussen snelheidslimieten en quota.

Beleidsverklaring

<quota-by-key calls="number"
              bandwidth="kilobytes"
              renewal-period="seconds"
              increment-condition="condition"
              counter-key="key value" />

Voorbeeld

In het volgende voorbeeld wordt het quotum ingesteld op het IP-adres van de aanroeper.

<policies>
    <inbound>
        <base />
        <quota-by-key calls="10000" bandwidth="40000" renewal-period="3600"
                      increment-condition="@(context.Response.StatusCode >= 200 && context.Response.StatusCode < 400)"
                      counter-key="@(context.Request.IpAddress)" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Elementen

Naam Beschrijving Vereist
quota Hoofdelement. Yes

Kenmerken

Naam Beschrijving Vereist Standaard
Bandbreedte Het maximale totale aantal kilobytes dat is toegestaan tijdens het tijdsinterval dat is opgegeven in de renewal-period . Ofwel calls bandwidth , of beide samen moeten worden opgegeven. N.v.t.
Oproepen Het maximumaantal aanroepen dat is toegestaan tijdens het tijdsinterval dat is opgegeven in de renewal-period . Ofwel calls bandwidth , of beide samen moeten worden opgegeven. N.v.t.
tellersleutel De sleutel die moet worden gebruikt voor het quotumbeleid. Yes N.v.t.
increment-condition De Booleaanse expressie die opgeeft of de aanvraag moet worden geteld voor het quotum ( true ) No N.v.t.
verlengingsperiode De periode in seconden waarna het quotum opnieuw wordt ingesteld. Wanneer deze is ingesteld op 0 de periode is ingesteld op oneindig. Yes N.v.t.

Notitie

De kenmerkwaarde moet uniek zijn voor alle API's in de API Management als u het totaal niet wilt delen counter-key tussen de andere API's.

Gebruik

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

  • Beleidssecties: inkomende
  • Beleidsbereiken: alle scopes

JWT valideren

Het beleid dwingt de aanwezigheid en geldigheid af van een JWT (JSON-web-token) dat is geëxtraheerd uit een opgegeven validate-jwt HTTP-header of een opgegeven queryparameter.

Belangrijk

Het beleid vereist dat de geregistreerde claim is opgenomen in het validate-jwt exp JWT-token, tenzij het kenmerk require-expiration-time is opgegeven en is ingesteld op false . Het validate-jwt beleid ondersteunt HS256- en RS256-ondertekeningsalgoritmen. Voor HS256 moet de sleutel inline worden opgegeven binnen het beleid in het met Base64 gecodeerde formulier. Voor RS256 kan de sleutel worden opgegeven via een configuratie-eindpunt voor de open id of door de id op te geven van een geüpload certificaat dat de openbare sleutel of het modulus-exponent-paar van de openbare sleutel bevat. Het beleid ondersteunt tokens die zijn versleuteld met symmetrische sleutels met behulp van de volgende validate-jwt versleutelingsalgoritmen: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.

Beleidsverklaring

<validate-jwt
    header-name="name of http header containing the token (use query-parameter-name attribute if the token is passed in the URL)"
    failed-validation-httpcode="http status code to return on failure"
    failed-validation-error-message="error message to return on failure"
    token-value="expression returning JWT token as a string"
    require-expiration-time="true|false"
    require-scheme="scheme"
    require-signed-tokens="true|false"
    clock-skew="allowed clock skew in seconds"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
  <openid-config url="full URL of the configuration endpoint, e.g. https://login.constoso.com/openid-configuration" />
  <issuer-signing-keys>
    <key>base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key>base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </decryption-keys>
  <audiences>
    <audience>audience string</audience>
    <!-- if there are multiple possible audiences, then add additional audience elements -->
  </audiences>
  <issuers>
    <issuer>issuer string</issuer>
    <!-- if there are multiple possible issuers, then add additional issuer elements -->
  </issuers>
  <required-claims>
    <claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
      <value>claim value as it is expected to appear in the token</value>
      <!-- if there is more than one allowed values, then add additional value elements -->
    </claim>
    <!-- if there are multiple possible allowed values, then add additional value elements -->
  </required-claims>
</validate-jwt>

Voorbeelden

Eenvoudige tokenvalidatie

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key>  <!-- signing key specified as a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Tokenvalidatie met RSA-certificaat

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key certificate-id="my-rsa-cert" />  <!-- signing key specified as certificate ID, enclosed in double-quotes -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Azure Active Directory tokenvalidatie

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/contoso.onmicrosoft.com/.well-known/openid-configuration" />
    <audiences>
        <audience>25eef6e4-c905-4a07-8eb4-0d08d5df8b3f</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Azure Active Directory Validatie van B2C-token

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/b2c_1_signin/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>d313c4e4-de5f-4197-9470-e509a2f0b806</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Toegang verlenen tot bewerkingen op basis van tokenclaims

In dit voorbeeld ziet u hoe u het beleid JWT valideren gebruikt om toegang te verlenen tot bewerkingen op basis van de waarde van tokenclaims.

<validate-jwt header-name="Authorization" require-scheme="Bearer" output-token-variable-name="jwt">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key> <!-- signing key is stored in a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <issuers>
        <issuer>contoso.com</issuer>
    </issuers>
    <required-claims>
        <claim name="group" match="any">
            <value>finance</value>
            <value>logistics</value>
        </claim>
    </required-claims>
</validate-jwt>
<choose>
    <when condition="@(context.Request.Method == "POST" && !((Jwt)context.Variables["jwt"]).Claims["group"].Contains("finance"))">
        <return-response>
            <set-status code="403" reason="Forbidden" />
        </return-response>
    </when>
</choose>

Elementen

Element Beschrijving Vereist
validate-jwt Hoofdelement. Yes
Publiek Bevat een lijst met acceptabele doelgroepclaims die aanwezig kunnen zijn op het token. Als er meerdere doelgroepwaarden aanwezig zijn, wordt elke waarde geprobeerd totdat alle waarden zijn uitgeput (in dat geval mislukt de validatie) of totdat er een is geslaagd. Er moet ten minste één doelgroep worden opgegeven. No
issuer-signing-keys Een lijst met met Base64 gecodeerde beveiligingssleutels die worden gebruikt om ondertekende tokens te valideren. Als er meerdere beveiligingssleutels aanwezig zijn, wordt elke sleutel geprobeerd totdat alle sleutels zijn uitgeput (in dat geval mislukt de validatie) of een sleutel slaagt (handig voor token-rollover). Sleutelelementen hebben een optioneel id kenmerk dat wordt gebruikt om overeen te komen met de kid claim.

U kunt ook een ondertekeningssleutel voor de vergever leveren met behulp van:

- certificate-id in de indeling <key certificate-id="mycertificate" /> om de id op te geven van een certificaatentiteit die is geüpload naar API Management
- RSA modulus and exponent pair in format to specify the n e <key n="<modulus>" e="<exponent>" /> RSA parameters in base64url-encoded format		 No
decryption-keys Een lijst met met Base64 gecodeerde sleutels die worden gebruikt voor het ontsleutelen van de tokens. Als er meerdere beveiligingssleutels aanwezig zijn, wordt elke sleutel geprobeerd totdat alle sleutels zijn uitgeput (in welk geval validatie mislukt) of een sleutel slaagt. Sleutelelementen hebben een optioneel id kenmerk dat wordt gebruikt om overeen te komen met de kid claim.

U kunt ook een ontsleutelingssleutel leveren met behulp van:

- certificate-id in de indeling <key certificate-id="mycertificate" /> om de id op te geven van een certificaatentiteit die is geüpload naar API Management		 No
Emittenten Een lijst met acceptabele principals die het token hebben uitgegeven. Als er meerdere waarden voor vergevers aanwezig zijn, wordt elke waarde geprobeerd totdat alle waarden zijn uitgeput (in dat geval mislukt de validatie) of totdat er een is geslaagd. No
openid-config Het -element dat wordt gebruikt voor het opgeven van een compatibel Open ID-configuratie-eindpunt van waaruit ondertekeningssleutels en vergever kunnen worden verkregen. No
required-claims Bevat een lijst met claims die naar verwachting aanwezig zijn op het token om te worden beschouwd als geldig. Wanneer het match kenmerk is ingesteld op elke claimwaarde in het beleid moet aanwezig zijn in het all token om de validatie te laten slagen. Wanneer het kenmerk is ingesteld op ten minste één claim moet aanwezig zijn in het match any token om te kunnen worden gevalideerd. No

Kenmerken

Naam Beschrijving Vereist Standaard
clock-skew Tijdspanne. Gebruik om het maximale verwachte tijdsverschil op te geven tussen de systeemklok van de tokenuitgever en het API Management exemplaar. No 0 seconden
failed-validation-error-message Foutbericht dat wordt weergegeven in de http-antwoord-body als de JWT niet door de validatie komt. Dit bericht moet speciale tekens bevatten met de juiste escape-tekens. No Het standaardfoutbericht is afhankelijk van het validatieprobleem, bijvoorbeeld 'JWT niet aanwezig'.
failed-validation-httpcode HTTP-statuscode die moet worden retourneert als de JWT niet is gevalideerd. No 401
header-name De naam van de HTTP-header met het token. Een van header-name , of moet worden query-parameter-name token-value opgegeven. N.v.t.
query-parameter-name De naam van de queryparameter met het token. Een van header-name , of moet worden query-parameter-name token-value opgegeven. N.v.t.
token-value Expressie die een tekenreeks met JWT-token retourneert. U mag niet Bearer retourneren als onderdeel van de tokenwaarde. Een van header-name , of moet worden query-parameter-name token-value opgegeven. N.v.t.
id Met het kenmerk op het -element kunt u de tekenreeks opgeven die wordt gematcht met de claim in het id token (indien aanwezig) om de juiste sleutel te vinden die moet worden gebruikt voor key kid handtekeningvalidatie. No N.v.t.
Overeenkomen met Het kenmerk op het element geeft aan of elke claimwaarde in het beleid aanwezig moet zijn in het match claim token om de validatie te laten slagen. Mogelijke waarden zijn:

- all - elke claimwaarde in het beleid moet aanwezig zijn in het token om de validatie te laten slagen.

- any - er moet ten minste één claimwaarde aanwezig zijn in het token om de validatie te laten slagen.		 No all
require-expiration-time Booleaanse. Hiermee geeft u op of een vervaldatumclaim is vereist in het token. No true
require-scheme De naam van het tokenschema, bijvoorbeeld 'Bearer'. Wanneer dit kenmerk is ingesteld, zorgt het beleid ervoor dat het opgegeven schema aanwezig is in de waarde van de autorisatieheader. No N.v.t.
require-signed-tokens Booleaanse. Hiermee geeft u op of een token moet worden ondertekend. No true
Scheidingsteken Tekenreeks. Hiermee geeft u een scheidingsteken (bijvoorbeeld ",") moet worden gebruikt voor het extraheren van een set waarden uit een claim met meerdere waarden. No N.v.t.
url Open de URL van het eindpunt voor de id-configuratie van waar de metagegevens van de Open ID-configuratie kunnen worden verkregen. Het antwoord moet volgens de specificaties zijn zoals gedefinieerd op URL: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata . Gebruik Azure Active Directory URL: vervang de naam van uw https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration directory-tenant, bijvoorbeeld contoso.onmicrosoft.com . Yes N.v.t.
output-token-variable-name Tekenreeks. Naam van contextvariabele die tokenwaarde ontvangt als object van het type Jwt bij geslaagde tokenvalidatie No N.v.t.

Gebruik

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

  • Beleidssecties: inkomende
  • Beleidsbereiken: alle scopes

Clientcertificaat valideren

Gebruik het beleid om af te dwingen dat een certificaat dat door een client aan een API Management-exemplaar wordt gepresenteerd, overeenkomt met opgegeven validatieregels en claims, zoals onderwerp of vergever voor een of meer validate-client-certificate certificaatidentiteiten.

Om als geldig te worden beschouwd, moet een clientcertificaat overeenkomen met alle validatieregels die zijn gedefinieerd door de kenmerken van het element op het hoogste niveau en overeenkomen met alle gedefinieerde claims voor ten minste één van de gedefinieerde identiteiten.

Gebruik dit beleid om binnenkomende certificaateigenschappen te controleren op de gewenste eigenschappen. Gebruik dit beleid ook om de standaardvalidatie van clientcertificaten in deze gevallen te overschrijven:

  • Als u aangepaste CA-certificaten hebt geüpload om clientaanvragen naar de beheerde gateway te valideren
  • Als u aangepaste certificeringsinstanties hebt geconfigureerd voor het valideren van clientaanvragen naar een zelf-beheerde gateway

Zie How to add a custom CA certificate in Azure API Management (Een aangepast CA-certificaat toevoegen in Azure API Management) voor meer informatie over aangepaste CA-certificaten en certificeringsinstanties.

Beleidsverklaring

<validate-client-certificate 
    validate-revocation="true|false"
    validate-trust="true|false" 
    validate-not-before="true|false" 
    validate-not-after="true|false" 
    ignore-error="true|false">
    <identities>
        <identity 
            thumbprint="certificate thumbprint"
            serial-number="certificate serial number"
            common-name="certificate common name"
            subject="certificate subject string"
            dns-name="certificate DNS name"
            issuer-subject="certificate issuer"
            issuer-thumbprint="certificate issuer thumbprint"
            issuer-certificate-id="certificate identifier" />
    </identities>
</validate-client-certificate>

Voorbeeld

In het volgende voorbeeld wordt een clientcertificaat gevalideerd om te voldoen aan de standaardvalidatieregels van het beleid en wordt gecontroleerd of het onderwerp en de naam van de vergever overeenkomen met de opgegeven waarden.

<validate-client-certificate 
    validate-revocation="true" 
    validate-trust="true" 
    validate-not-before="true" 
    validate-not-after="true" 
    ignore-error="false">
    <identities>
        <identity
            subject="C=US, ST=Illinois, L=Chicago, O=Contoso Corp., CN=*.contoso.com"
            issuer-subject="C=BE, O=FabrikamSign nv-sa, OU=Root CA, CN=FabrikamSign Root CA" />
    </identities>
</validate-client-certificate>

Elementen

Element Beschrijving Vereist
validate-client-certificate Hoofdelement. Yes
Identiteiten Bevat een lijst met identiteiten met gedefinieerde claims op het clientcertificaat. No

Kenmerken

Naam Beschrijving Vereist Standaard
validate-revocation  Booleaanse. Hiermee geeft u op of het certificaat wordt gevalideerd op de online intrekkingslijst.  nee  Waar
validate-trust  Booleaanse. Hiermee geeft u op of validatie moet mislukken als de keten niet kan worden opgebouwd naar een vertrouwde CA. nee Waar
validate-not-before Booleaanse. Valideert de waarde ten opzichte van de huidige tijd. nee  Waar
validate-not-after  Booleaanse. Valideert de waarde ten opzichte van de huidige tijd. nee  Waar
ignore-error  Booleaanse. Hiermee geeft u op of het beleid moet doorgaan naar de volgende handler of naar on-error moet gaan bij mislukte validatie. nee Niet waar
identity Tekenreeks. Combinatie van certificaatclaimwaarden die het certificaat geldig maken. ja N.v.t.
Vingerafdruk Vingerafdruk van certificaat. nee N.v.t.
serienummer Serienummer van certificaat. nee N.v.t.
common-name Algemene naam van certificaat (onderdeel van onderwerpreeks). nee N.v.t.
Onderwerp Onderwerpreeks. Moet de indeling DN-naam volgen. nee N.v.t.
dns-name De waarde van de vermelding dnsName binnen de claim Alternatieve naam voor onderwerp. nee N.v.t.
issuer-subject Onderwerp van vergever. Moet de indeling DN-naam volgen. nee N.v.t.
issuer-thumbprint Vingerafdruk van verwijzer. nee N.v.t.
issuer-certificate-id Id van bestaande certificaatentiteit die de openbare sleutel van de vergever vertegenwoordigt. Sluiten elkaar wederzijds uit met andere vergeverkenmerken. nee N.v.t.

Gebruik

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

  • Beleidssecties: inkomende
  • Beleidsbereiken: alle scopes

Volgende stappen

Zie voor meer informatie over het werken met beleidsregels: