Principer för åtkomstbegränsning i API Management

Det här avsnittet innehåller en referens för följande API Management principer. Information om hur du lägger till och konfigurerar principer finns i Principer i API Management.

Principer för åtkomstbegränsning

• Kontrollera HTTP-huvud – Framtvingar förekomsten och/eller värdet för ett HTTP-huvud.
• Begränsa anropsfrekvensen per prenumeration – Förhindrar toppar i API-användning genom att begränsa anropsfrekvensen per prenumeration.
• Begränsa anropsfrekvensen efter nyckel – Förhindrar toppar i API-användningen genom att begränsa anropsfrekvensen per nyckel.
• Begränsa anropar-IP-adresser – Filtrerar (tillåter/nekar) anrop från specifika IP-adresser och/eller adressintervall.
• Ange användningskvot per prenumeration – Gör att du kan framtvinga en kvot för anropsvolym för förnyelse eller livslängd och/eller bandbredd per prenumeration.
• Ange användningskvot per nyckel – Gör att du kan framtvinga en kvot för anropsvolym för förnyelse eller livslängd och/eller bandbredd per nyckel.
• Verifiera JWT – Framtvingar förekomsten och giltigheten för en JWT som extraherats från antingen en angiven HTTP-rubrik eller en angiven frågeparameter.
• Verifiera klientcertifikat – Framtvingar att ett certifikat som presenteras av en klient API Management en instans matchar angivna verifieringsregler och anspråk.

Kontrollera HTTP-huvud

Använd principen check-header för att framtvinga att en begäran har ett angivet HTTP-huvud. Du kan också kontrollera om rubriken har ett visst värde eller söka efter ett intervall med tillåtna värden. Om kontrollen misslyckas avslutar principen bearbetningen av begäran och returnerar HTTP-statuskoden och felmeddelandet som anges av principen.

Principutdrag

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

Exempel

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

Element

Attribut

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande, utgående

• Principomfång: alla omfång

Begränsa anropsfrekvensen efter prenumeration

Principen rate-limit förhindrar API-användningstoppar per prenumeration genom att begränsa anropsfrekvensen till ett angivet tal per angiven tidsperiod. När anropsfrekvensen överskrids får anroparen en 429 Too Many Requests svarsstatuskod.

Principutdrag

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

Exempel

I följande exempel är gränsen per prenumerationspris 20 anrop per 90 sekunder. Efter varje principkörning lagras de återstående anrop som tillåts under tidsperioden i variabeln remainingCallsPerSubscription .

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

Element

Attribut

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande

• Principomfattningar: product, api, operation

Begränsa anropsfrekvensen efter nyckel

Principen rate-limit-by-key förhindrar api-användningstoppar per nyckel genom att begränsa anropsfrekvensen till ett angivet tal per angiven tidsperiod. Nyckeln kan ha ett godtyckligt strängvärde och tillhandahålls vanligtvis med hjälp av ett principuttryck. Valfritt ökningsvillkor kan läggas till för att ange vilka begäranden som ska räknas mot gränsen. När anropsfrekvensen överskrids får anroparen en 429 Too Many Requests svarsstatuskod.

Mer information och exempel på den här principen finns i Avancerad begränsning av förfrågningar med Azure API Management.

Principutdrag

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

Exempel

I följande exempel nyckelas frekvensgränsen på 10 anrop per 60 sekunder av anroparens IP-adress. Efter varje principkörning lagras de återstående anrop som tillåts under tidsperioden i variabeln 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>

Element

Attribut

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande

• Principomfång: alla omfång

Begränsa anropar-IP-adresser

Principen ip-filter filtrerar (tillåter/nekar) anrop från specifika IP-adresser och/eller adressintervall.

Principutdrag

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

Exempel

I följande exempel tillåter principen endast begäranden som kommer från antingen den enskilda IP-adressen eller intervallet med angivna IP-adresser

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

Element

Attribut

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande
• Principomfång: alla omfång

Ange användningskvot per prenumeration

Principen quota tillämpar en förnyelsebar volym eller livslängd för anropsvolym och/eller bandbreddskvot per prenumeration.

Principutdrag

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

Exempel

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

Element

Attribut

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande
• Principomfång: produkt

Ange användningskvot efter nyckel

Principen quota-by-key tillämpar en förnyelsebar volym eller livslängd för anropsvolym och/eller bandbreddskvot per nyckel. Nyckeln kan ha ett godtyckligt strängvärde och tillhandahålls vanligtvis med hjälp av ett principuttryck. Valfria ökningsvillkor kan läggas till för att ange vilka begäranden som ska räknas mot kvoten. Om flera principer skulle öka samma nyckelvärde ökas det bara en gång per begäran. När anropsfrekvensen överskrids får anroparen en 403 Forbidden svarsstatuskod.

Mer information och exempel på den här principen finns i Avancerad begränsning av förfrågningar med Azure API Management.

Principutdrag

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

Exempel

I följande exempel nyckelas kvoten av anroparens IP-adress.

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

Element

Attribut

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande
• Principomfång: alla omfång

Verifiera JWT

Principen validate-jwt framtvingar förekomsten och giltigheten för en JSON-webbtoken (JWT) som extraherats från antingen en angiven HTTP-rubrik eller en angiven frågeparameter.

Principsats

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

Exempel

Enkel tokenvalidering

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

Tokenvalidering med RSA-certifikat

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

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

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

Auktorisera åtkomst till åtgärder baserat på tokenanspråk

Det här exemplet visar hur du använder principen Validate JWT (Validera JWT) för att auktorisera åtkomst till åtgärder baserat på värdet för tokenanspråk.

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

Element

Attribut

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande
• Principomfång: alla omfång

Verifiera klientcertifikat

Använd principen för att framtvinga att ett certifikat som presenteras av en klient till en API Management-instans matchar angivna valideringsregler och anspråk som ämne eller utfärdare för en eller flera validate-client-certificate certifikatidentiteter.

För att anses vara giltigt måste ett klientcertifikat matcha alla valideringsregler som definierats av attributen på toppnivåelementet och matcha alla definierade anspråk för minst en av de definierade identiteterna.

Använd den här principen för att kontrollera inkommande certifikategenskaper mot önskade egenskaper. Använd även den här principen för att åsidosätta standardvalidering av klientcertifikat i dessa fall:

• Om du har laddat upp anpassade CA-certifikat för att verifiera klientbegäranden till den hanterade gatewayen
• Om du har konfigurerat anpassade certifikatutfärdare för att verifiera klientbegäranden till en egen hanterad gateway

Mer information om anpassade CA-certifikat och certifikatutfärdare finns i Så här lägger du till ett anpassat CA-certifikat i Azure API Management.

Principsats

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

Exempel

I följande exempel verifieras ett klientcertifikat så att det matchar principens standardvalideringsregler och kontrollerar om ämnes- och utfärdarnamnet matchar angivna värden.

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

Element

Attribut

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande
• Principomfång: alla omfång

Nästa steg

Mer information om hur du arbetar med principer finns i:

• Principer i API Management
• Transformera API:er
• Principreferens för en fullständig lista över principutdrag och deras inställningar
• Principexempel