API Management erişim kısıtlama ilkeleri

Bu konu, aşağıdaki API Management ilkelerine yönelik bir başvuru sağlar. İlke ekleme ve yapılandırma hakkında daha fazla bilgi için bkz. API Management ilkeleri.

Erişim kısıtlama ilkeleri

• Http üstbilgisini denetle -http üstbilgisinin varlığını ve/veya değerini uygular.
• Abonelik ile çağrı hızını sınırla -çağrı hızını her abonelik IÇIN sınırlayarak API kullanım artışlarını engeller.
• Anahtara göre çağrı hızını sınırla -çağrı hızını anahtar TEMELINDE sınırlayarak API kullanım artışlarını engeller.
• Belirli IP adreslerinden ve/veya adres aralıklarından çağrı IP 'leri filtrelerini kısıtla (izin verir/reddeder).
• Kullanım kotasını aboneliğe göre ayarla -yenilenebilir bir veya yaşam süresi araması hacmi ve/veya bant genişliği kotasını abonelik başına temelinde zorlamanıza olanak sağlar.
• Anahtar temelinde kullanım kotasını ayarlama -bir yenilenebilir veya yaşam süresi çağrı hacmi ve/veya bant genişliği kotasını anahtar başına temelinde zorlamanıza olanak sağlar.
• JWT 'Yi doğrula -BELIRTILEN bir http üst bilgisinden veya belirtilen sorgu parametresinden AYıKLANAN bir JWT 'ın varlığını ve geçerliliğini zorlar.
• İstemci sertifikasını doğrula -istemci tarafından bir API Management örneğine sunulan bir sertifikanın belirtilen doğrulama kuralları ve talepler ile eşleştiğinden zorlar.

HTTP üstbilgisini denetle

check-headerBir isteğin belirtilen BIR http üst bilgisine sahip olmasını zorlamak için ilkeyi kullanın. İsteğe bağlı olarak, başlığın belirli bir değere sahip olup olmadığını veya bir dizi izin verilen değer olup olmadığını kontrol edebilirsiniz. Denetim başarısız olursa, ilke istek işlemeyi sonlandırır ve ilke tarafından belirtilen HTTP durum kodunu ve hata iletisini döndürür.

İlke ekstresi

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

Örnek

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

Öğeler

Öznitelikler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlardakullanılabilir.

• İlke bölümleri: gelen, giden

• İlke kapsamları: tüm kapsamlar

Çağrı hızını aboneliğe göre sınırla

rate-limitİlke, belirli bir süre için çağrı oranını belirtilen bir sayı ile sınırlayarak, her abonelik IÇIN API kullanım artışlarını engeller. Çağrı hızı aşıldığında, çağıran bir 429 Too Many Requests yanıt durum kodu alır.

İlke ekstresi

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

Örnek

Aşağıdaki örnekte, abonelik başına hız sınırı 90 saniye başına 20 çağrı olur. Her ilke yürütmeden sonra, zaman döneminde izin verilen kalan çağrılar değişkende depolanır remainingCallsPerSubscription .

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

Öğeler

Öznitelikler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlardakullanılabilir.

• İlke bölümleri: gelen

• İlke kapsamları: ürün, API, işlem

Çağrı hızını anahtarla sınırla

rate-limit-by-keyİlke, belirli bir süre için çağrı hızını belirtilen bir sayı ile sınırlayarak, her anahtar IÇIN API kullanım artışlarını engeller. Anahtar rastgele bir dize değerine sahip olabilir ve genellikle bir ilke ifadesi kullanılarak sağlanır. Hangi isteklerin sınıra doğru sayılması gerektiğini belirtmek için isteğe bağlı artış koşulu eklenebilir. Bu çağrı hızı aşıldığında, çağıran bir 429 Too Many Requests yanıt durum kodu alır.

Bu ilkenin daha fazla bilgi ve örnekleri için bkz. Azure API Management Ile Gelişmiş istek azaltma.

İlke ekstresi

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

Örnek

Aşağıdaki örnekte, 60 saniye başına 10 çağrının hız limiti arayan IP adresi tarafından anahtarlanır. Her ilke yürütmeden sonra, zaman döneminde izin verilen kalan çağrılar değişkende depolanır 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>

Öğeler

Öznitelikler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlardakullanılabilir.

• İlke bölümleri: gelen

• İlke kapsamları: tüm kapsamlar

Çağıranın IP'lerini kısıtlama

ip-filterİlke, belirli IP adreslerinden ve/veya adres aralıklarından gelen çağrıları filtreler (izin verir/etkinleştirir).

İlke deyimi

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

Örnek

Aşağıdaki örnekte, ilke yalnızca tek IP adresi veya belirtilen IP adresi aralığından gelen isteklere izin verir

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

Öğeler

Öznitelikler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

• İlke bölümleri: gelen
• İlke kapsamları: tüm kapsamlar

Aboneliğe göre kullanım kotası ayarlama

quotaİlke, abonelik başına yenilenebilir veya yaşam süresi çağrı hacmi ve/veya bant genişliği kotası zorlar.

İlke deyimi

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

Örnek

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

Öğeler

Öznitelikler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

• İlke bölümleri: gelen
• İlke kapsamları: ürün

Anahtara göre kullanım kotası ayarlama

quota-by-keyİlke, anahtar temelinde yenilenebilir veya yaşam süresi çağrı hacmi ve/veya bant genişliği kotası zorlar. Anahtarın rastgele bir dize değeri olabilir ve genellikle bir ilke ifadesi kullanılarak sağlanır. Kotaya hangi isteklerin sayılacağı belirtmek için isteğe bağlı artırma koşulu eklenebilir. Birden çok ilke aynı anahtar değerini artırırsa, istek başına yalnızca bir kez artırılır. Çağrı hızı aşılırsa çağıranın yanıt 403 Forbidden durum kodu alır.

Bu ilkeye ilişkin daha fazla bilgi ve örnekler için bkz. Azure API Management ile gelişmiş istek azaltma.

İlke deyimi

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

Örnek

Aşağıdaki örnekte, kota çağıran IP adresine göre anahtarlanır.

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

Öğeler

Öznitelikler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlardakullanılabilir.

• İlke bölümleri: gelen
• İlke kapsamları: tüm kapsamlar

JWT 'yi doğrula

validate-jwtİlke, belirtilen BIR http üstbilgisinden veya belirtilen sorgu parametresinden AYıKLANAN JSON Web belirtecinin (JWT) varlığını ve geçerliliğini zorlar.

İlke ekstresi

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

Örnekler

Basit belirteç doğrulama

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

RSA sertifikası ile belirteç doğrulama

<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 belirteci doğrulaması

<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 belirteci doğrulaması

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

Belirteç taleplerine göre işlemlere erişim yetkisi verme

Bu örnek, belirteç talep değerine göre işlemlere erişim yetkisi vermek için JWT Ilkesini doğrula ' nın nasıl kullanılacağını gösterir.

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

Öğeler

Öznitelikler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlardakullanılabilir.

• İlke bölümleri: gelen
• İlke kapsamları: tüm kapsamlar

İstemci sertifikasını doğrula

Bir validate-client-certificate istemci tarafından bir API Management örneğine sunulan bir sertifikanın, bir veya daha fazla sertifika kimliği için konu veya veren gibi belirtilen doğrulama kurallarını ve taleplerini eşleştirmesini zorlamak için ilkeyi kullanın.

Geçerli kabul edilmesi için, bir istemci sertifikası üst düzey öğedeki öznitelikler tarafından tanımlanan tüm doğrulama kurallarıyla eşleşmelidir ve tanımlanan kimliklerin en az biri için tüm tanımlı talepleri eşleştirin.

Gelen sertifika özelliklerini istenen özelliklere göre denetlemek için bu ilkeyi kullanın. Bu ilkeyi Ayrıca, bu durumlarda istemci sertifikalarının varsayılan doğrulamasını geçersiz kılmak için kullanın:

• Yönetilen ağ geçidine istemci isteklerini doğrulamak için özel CA sertifikaları yüklediyseniz
• İstemci isteklerini otomatik olarak yönetilen bir ağ geçidine doğrulamak için özel sertifika yetkilileri yapılandırdıysanız

Özel CA sertifikaları ve sertifika yetkilileri hakkında daha fazla bilgi için bkz. Azure API Management özel CA sertifikası ekleme.

İlke ekstresi

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

Örnek

Aşağıdaki örnek, ilkenin varsayılan doğrulama kurallarını eşleştirmek üzere bir istemci sertifikasını doğrular ve konu ve verenin adının belirtilen değerlerle eşleşip eşleşmediğini denetler.

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

Öğeler

Öznitelikler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlardakullanılabilir.

• İlke bölümleri: gelen
• İlke kapsamları: tüm kapsamlar

Sonraki adımlar

İlkelerle çalışma hakkında daha fazla bilgi için bkz.

• API Management ilkeler
• API dönüştürme
• İlke deyimlerinin ve ayarlarının tam listesi için Ilke başvurusu
• İlke örnekleri