Criteri di limitazione dell'accesso di Gestione APIAPI Management access restriction policies

Questo argomento fornisce un riferimento per i criteri di Gestione API seguenti.This topic provides a reference for the following API Management policies. Per informazioni sull'aggiunta e sulla configurazione dei criteri, vedere Criteri di Gestione API.For information on adding and configuring policies, see Policies in API Management.

Criteri di limitazione dell'accessoAccess restriction policies

Intestazione check-headerCheck HTTP header

Usare il criterio check-header per applicare una richiesta che presenta un'intestazione HTTP specificata.Use the check-header policy to enforce that a request has a specified HTTP header. Facoltativamente, è possibile verificare se l'intestazione presenta un valore specifico o un intervallo di valori consentiti.You can optionally check to see if the header has a specific value or check for a range of allowed values. Se la verifica ha esito negativo, il criterio termina l'elaborazione della richiesta e restituisce il codice di stato HTTP e il messaggio di errore specificati dai criteri.If the check fails, the policy terminates request processing and returns the HTTP status code and error message specified by the policy.

Istruzione del criterioPolicy statement

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

EsempioExample

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

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
check-headercheck-header Elemento radice.Root element. Yes
valuevalue Valore dell'intestazione HTTP consentito.Allowed HTTP header value. Quando vengono specificati più elementi per il valore, in caso di corrispondenza di uno dei valori il controllo ha esito positivo.When multiple value elements are specified, the check is considered a success if any one of the values is a match. NoNo

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
failed-check-error-messagefailed-check-error-message Messaggio di errore da restituire nel corpo della risposta HTTP se l'intestazione non esiste o presenta un valore non valido.Error message to return in the HTTP response body if the header doesn't exist or has an invalid value. I caratteri speciali eventualmente contenuti in questo messaggio devono essere adeguatamente preceduti da un carattere di escape.This message must have any special characters properly escaped. Yes N/DN/A
failed-check-httpcodefailed-check-httpcode Codice di stato HTTP da restituire se l'intestazione non esiste o presenta un valore non valido.HTTP Status code to return if the header doesn't exist or has an invalid value. Yes N/DN/A
header-nameheader-name Il nome dell'intestazione HTTP da verificare.The name of the HTTP Header to check. Yes N/DN/A
ignore-caseignore-case Può essere impostato su True o False.Can be set to True or False. Se impostato su True, il maiuscolo viene ignorato quando il valore dell'intestazione viene confrontato con il set di valori accettabili.If set to True case is ignored when the header value is compared against the set of acceptable values. Yes N/DN/A

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: inbound, outboundPolicy sections: inbound, outbound

  • Ambiti del criterio: globale, prodotto, API, operazionePolicy scopes: global, product, API, operation

Limita frequenza delle chiamate per sottoscrizioneLimit call rate by subscription

Il criterio rate-limit impedisce picchi d'uso dell'API per ogni sottoscrizione impostando la frequenza delle chiamate su un numero specificato per un periodo di tempo specificato.The rate-limit policy prevents API usage spikes on a per subscription basis by limiting the call rate to a specified number per a specified time period. All'attivazione di questo criterio, il chiamate riceve il codice di stato della risposta 429 Too Many Requests.When this policy is triggered the caller receives a 429 Too Many Requests response status code.

Importante

Questo criterio può essere impiegato una sola volta per ogni documento dei criteri.This policy can be used only once per policy document.

Per questo criterio, non è possibile usare espressioni di criteri negli attributi dei criteri.Policy expressions cannot be used in any of the policy attributes for this policy.

Istruzione del criterioPolicy statement

<rate-limit calls="number" renewal-period="seconds">  
    <api name="name" calls="number" renewal-period="seconds">  
        <operation name="name" calls="number" renewal-period="seconds" />  
    </api>  
</rate-limit>  

EsempioExample

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

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
set-limitset-limit Elemento radice.Root element. Yes
apiapi Aggiungere almeno uno di questi elementi per imporre un limite di frequenza delle chiamate alle API all'interno del prodotto.Add one or more of these elements to impose a call rate limit on APIs within the product. I limiti alla frequenza delle chiamate API e al prodotto vengono applicati in modo indipendente.Product and API call rate limits are applied independently. NoNo
operationoperation Aggiungere almeno uno di questi elementi per imporre un limite di frequenza delle chiamate alle operazioni all'interno di un'API.Add one or more of these elements to impose a call rate limit on operations within an API. I limiti alla frequenza delle chiamate alle operazioni, all'API e al prodotto vengono applicati in modo indipendente.Product, API, and operation call rate limits are applied independently. NoNo

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
namename Il nome dell'API a cui si desidera applicare il limite di frequenza.The name of the API for which to apply the rate limit. Yes N/DN/A
callscalls Il numero totale massimo di chiamate consentite durante l'intervallo di tempo specificato in renewal-period.The maximum total number of calls allowed during the time interval specified in the renewal-period. Yes N/DN/A
renewal-periodrenewal-period Periodo, in secondi, dopo il quale la quota si reimposta.The time period in seconds after which the quota resets. Yes N/DN/A

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: inboundPolicy sections: inbound

  • Ambiti del criterio: prodottoPolicy scopes: product

Limita la frequenza delle chiamate per chiaveLimit call rate by key

Il criterio rate-limit-by-key impedisce picchi d'uso dell'API per ogni chiave impostando la frequenza delle chiamate su un numero specificato per un periodo di tempo specificato.The rate-limit-by-key policy prevents API usage spikes on a per key basis by limiting the call rate to a specified number per a specified time period. La chiave può avere un valore di stringa arbitrario e viene indicata in genere usando un'espressione di criteri.The key can have an arbitrary string value and is typically provided using a policy expression. Per specificare le richieste da considerare nel limite, è possibile aggiungere una condizione opzionale di incremento.Optional increment condition can be added to specify which requests should be counted towards the limit. All'attivazione di questo criterio, il chiamate riceve il codice di stato della risposta 429 Too Many Requests.When this policy is triggered the caller receives a 429 Too Many Requests response status code.

Per altre informazioni ed esempi su questo criterio, vedere Advanced request throttling with Azure API Management (Limitazione avanzata delle richieste con Gestione API di Azure).For more information and examples of this policy, see Advanced request throttling with Azure API Management.

Importante

Questo criterio può essere impiegato una sola volta per ogni documento dei criteri.This policy can be used only once per policy document.

Istruzione del criterioPolicy statement

<rate-limit-by-key calls="number"  
                   renewal-period="seconds"   
                   increment-condition="condition"   
                   counter-key="key value" />  

EsempioExample

Nell'esempio seguente il limite alla frequenza viene associato a una chiave dall'indirizzo IP del chiamante.In the following example, the rate limit is keyed by the caller IP address.

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

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
set-limitset-limit Elemento radice.Root element. Yes

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
callscalls Il numero totale massimo di chiamate consentite durante l'intervallo di tempo specificato in renewal-period.The maximum total number of calls allowed during the time interval specified in the renewal-period. Yes N/DN/A
counter-keycounter-key La chiave deve essere usata per i criteri relativi ai limiti di frequenza.The key to use for the rate limit policy. Yes N/DN/A
increment-conditionincrement-condition Espressione booleana che specifica se la richiesta deve essere conteggiata ai fini della quota (true).The boolean expression specifying if the request should be counted towards the quota (true). NoNo N/DN/A
renewal-periodrenewal-period Periodo, in secondi, dopo il quale la quota si reimposta.The time period in seconds after which the quota resets. Yes N/DN/A

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: inboundPolicy sections: inbound

  • Ambiti del criterio: globale, prodotto, API, operazionePolicy scopes: global, product, API, operation

ip-filterRestrict caller IPs

Il criterio ip-filter filtra (permette/rifiuta) le chiamate da indirizzi IP e/o intervalli di indirizzi IP specifici.The ip-filter policy filters (allows/denies) calls from specific IP addresses and/or address ranges.

Istruzione del criterioPolicy statement

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

EsempioExample

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

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
ip-filterip-filter Elemento radice.Root element. Yes
Addressaddress Specifica un singolo indirizzo IP su cui applicare il filtro.Specifies a single IP address on which to filter. È obbligatorio almeno un elemento address o address-range.At least one address or address-range element is required.
address-range from="address" to="address"address-range from="address" to="address" Specifica un intervallo di indirizzi IP su cui applicare il filtro.Specifies a range of IP address on which to filter. È obbligatorio almeno un elemento address o address-range.At least one address or address-range element is required.

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
address-range from="address" to="address"address-range from="address" to="address" Intervallo di indirizzi IP per cui permettere o negare l'accesso.A range of IP addresses to allow or deny access for. Obbligatorio quando viene usato l'elemento address-range.Required when the address-range element is used. N/DN/A
ip-filter action="allow | forbid"ip-filter action="allow | forbid" Specifica se le chiamate devono essere consentite o rifiutate per gli indirizzi e gli intervalli di indirizzi IP specificati.Specifies whether calls should be allowed or not for the specified IP addresses and ranges. Yes N/DN/A

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: inboundPolicy sections: inbound
  • Ambiti del criterio: globale, prodotto, API, operazionePolicy scopes: global, product, API, operation

Imposta quota di utilizzo per sottoscrizioneSet usage quota by subscription

Il criterio quota consente di applicare una quota rinnovabile o permanente per il volume di chiamate e/o per la larghezza di banda, per sottoscrizione.The quota policy enforces a renewable or lifetime call volume and/or bandwidth quota, on a per subscription basis.

Importante

Questo criterio può essere impiegato una sola volta per ogni documento dei criteri.This policy can be used only once per policy document.

Per questo criterio, non è possibile usare espressioni di criteri negli attributi dei criteri.Policy expressions cannot be used in any of the policy attributes for this policy.

Istruzione del criterioPolicy statement

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

EsempioExample

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

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
quotaquota Elemento radice.Root element. Yes
apiapi Aggiungere almeno uno di questi elementi per imporre una quota alle API all'interno del prodotto.Add one or more of these elements to impose a quota on APIs within the product. Le quote delle API e del prodotto vengono applicate in modo indipendente.Product and API quotas are applied independently. NoNo
operationoperation Aggiungere almeno uno di questi elementi per imporre una quota alle operazioni all'interno di un'API.Add one or more of these elements to impose a quota on operations within an API. Le quote delle operazioni, delle API e del prodotto vengono applicate in modo indipendente.Product, API, and operation quotas are applied independently. NoNo

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
namename Nome dell'API o dell'operazione per cui è applicabile la quota.The name of the API or operation for which the quota applies. Yes N/DN/A
bandwidthbandwidth Il numero totale massimo di kilobyte consentiti durante l'intervallo di tempo specificato in renewal-period.The maximum total number of kilobytes allowed during the time interval specified in the renewal-period. Devono essere specificati calls, bandwidth o entrambi.Either calls, bandwidth, or both together must be specified. N/DN/A
callscalls Il numero totale massimo di chiamate consentite durante l'intervallo di tempo specificato in renewal-period.The maximum total number of calls allowed during the time interval specified in the renewal-period. Devono essere specificati calls, bandwidth o entrambi.Either calls, bandwidth, or both together must be specified. N/DN/A
renewal-periodrenewal-period Periodo, in secondi, dopo il quale la quota si reimposta.The time period in seconds after which the quota resets. Yes N/DN/A

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: inboundPolicy sections: inbound
  • Ambiti del criterio: prodottoPolicy scopes: product

Impostare la quota per chiaveSet usage quota by key

Il criterio quota-by-key consente di applicare una quota rinnovabile o permanente per il volume di chiamate e/o per la larghezza di banda, per chiave.The quota-by-key policy enforces a renewable or lifetime call volume and/or bandwidth quota, on a per key basis. La chiave può avere un valore di stringa arbitrario e viene indicata in genere usando un'espressione di criteri.The key can have an arbitrary string value and is typically provided using a policy expression. Per specificare le richieste da considerare nella quota, è possibile aggiungere una condizione opzionale di incremento.Optional increment condition can be added to specify which requests should be counted towards the quota.

Per altre informazioni ed esempi su questo criterio, vedere Advanced request throttling with Azure API Management (Limitazione avanzata delle richieste con Gestione API di Azure).For more information and examples of this policy, see Advanced request throttling with Azure API Management.

Importante

Questo criterio può essere impiegato una sola volta per ogni documento dei criteri.This policy can be used only once per policy document.

Per questo criterio, non è possibile usare espressioni di criteri negli attributi dei criteri.Policy expressions cannot be used in any of the policy attributes for this policy.

Istruzione del criterioPolicy statement

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

EsempioExample

Nell'esempio seguente la quota viene associata a una chiave dall'indirizzo IP del chiamante.In the following example, the quota is keyed by the caller IP address.

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

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
quotaquota Elemento radice.Root element. Yes

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
bandwidthbandwidth Il numero totale massimo di kilobyte consentiti durante l'intervallo di tempo specificato in renewal-period.The maximum total number of kilobytes allowed during the time interval specified in the renewal-period. Devono essere specificati calls, bandwidth o entrambi.Either calls, bandwidth, or both together must be specified. N/DN/A
callscalls Il numero totale massimo di chiamate consentite durante l'intervallo di tempo specificato in renewal-period.The maximum total number of calls allowed during the time interval specified in the renewal-period. Devono essere specificati calls, bandwidth o entrambi.Either calls, bandwidth, or both together must be specified. N/DN/A
counter-keycounter-key La chiave deve essere usata per i criteri relativi alla quota.The key to use for the quota policy. Yes N/DN/A
increment-conditionincrement-condition Espressione booleana che specifica se la richiesta deve essere conteggiata ai fini della quota (true).The boolean expression specifying if the request should be counted towards the quota (true) NoNo N/DN/A
renewal-periodrenewal-period Periodo, in secondi, dopo il quale la quota si reimposta.The time period in seconds after which the quota resets. Yes N/DN/A

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: inboundPolicy sections: inbound
  • Ambiti del criterio: globale, prodotto, API, operazionePolicy scopes: global, product, API, operation

Convalida token JWTValidate JWT

Il criterio validate-jwt impone l'esistenza e la validità di un token JWT estratto da un'intestazione HTTP specificata o da un parametro di query specificato.The validate-jwt policy enforces existence and validity of a JWT extracted from either a specified HTTP Header or a specified query parameter.

Importante

Il criterio validate-jwt richiede che l'attestazione exp registrata venga inclusa nel token JWT, a meno che non venga specificato l'attributo require-expiration-time e impostato su false.The validate-jwt policy requires that the exp registered claim is inlcuded in the JWT token, unless require-expiration-time attribute is specified and set to false.
Il criterio validate-jwt supporta gli algoritmi di firma HS256 e RS256.The validate-jwt policy supports HS256 and RS256 signing algorithms. Per HS256, la chiave deve essere fornita incorporata all'interno del criterio nel formato con codificata Base64.For HS256 the key must be provided inline within the policy in the base64 encoded form. Per RS256, la chiave deve essere fornita attraverso un endpoint di configurazione Open ID.For RS256 the key has to be provide via an Open ID configuration endpoint.

Istruzione del criterioPolicy statement

<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"   
    require-expiration-time="true|false"
    require-scheme="scheme"
    require-signed-tokens="true|false"   
    clock-skew="allowed clock skew in seconds">  
  <issuer-signing-keys>  
    <key>base64 encoded signing key</key>  
    <!-- if there are multiple keys, then add additional key elements -->  
  </issuer-signing-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>  
  <openid-config url="full URL of the configuration endpoint, e.g. https://login.constoso.com/openid-configuration" />  
  <zumo-master-key id="key identifier">key value</zumo-master-key>  
</validate-jwt>  

EsempiExamples

Convalida del token dei Servizi mobili di AzureAzure Mobile Services token validation

<validate-jwt header-name="x-zumo-auth" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Supplied access token is invalid.">  
    <issuers>  
        <issuer>urn:microsoft:windows-azure:zumo</issuer>  
    </issuers>  
    <audiences>  
        <audience>Facebook</audience>  
    </audiences>  
    <issuer-signing-keys>  
        <zumo-master-key id="0">insert key here</zumo-master-key>  
    </issuer-signing-keys>  
</validate-jwt>  

Convalida del token di Azure Active DirectoryAzure Active Directory token validation

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

Convalida del token di Azure Active Directory B2CAzure Active Directory B2C token validation

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

Autorizzare l'accesso a operazioni basate su attestazioni dei tokenAuthorize access to operations based on token claims

Questo esempio illustra come usare il criterio Convalida token JWT per preautorizzare l'accesso alle operazioni in base alle attestazioni dei token.This example shows how to use the Validate JWT policy to pre-authorize access to operations based on token claims. Per una dimostrazione relativa alla configurazione e all'uso di questo criterio, vedere l'episodio 177 di Cloud Cover su altre funzionalità di Gestione API con Vlad Vinogradsky e passare direttamente al minuto 13:50.For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 13:50. Passare a 15:00 minuti per vedere i criteri configurati nell'editor dei criteri e quindi a 18:50 minuti per una dimostrazione della chiamata di un'operazione dal portale per sviluppatori, con e senza il token di autorizzazione richiesto.Fast forward to 15:00 to see the policies configured in the policy editor and then to 18:50 for a demonstration of calling an operation from the developer portal both with and without the required authorization token.

<!-- Copy the following snippet into the inbound section at the api (or higher) level to pre-authorize access to operations based on token claims -->  
<set-variable name="signingKey" value="insert signing key here" />  
<choose>  
  <when condition="@(context.Request.Method.Equals("patch",StringComparison.OrdinalIgnoreCase))">  
    <validate-jwt header-name="Authorization">  
      <issuer-signing-keys>  
        <key>@((string)context.Variables["signingKey"])</key>  
      </issuer-signing-keys>  
      <required-claims>  
        <claim name="edit">  
          <value>true</value>  
        </claim>  
      </required-claims>  
    </validate-jwt>  
  </when>  
  <when condition="@(new [] {"post", "put"}.Contains(context.Request.Method,StringComparer.OrdinalIgnoreCase))">  
    <validate-jwt header-name="Authorization">  
      <issuer-signing-keys>  
        <key>@((string)context.Variables["signingKey"])</key>  
      </issuer-signing-keys>  
      <required-claims>  
        <claim name="create">  
          <value>true</value>  
        </claim>  
      </required-claims>  
    </validate-jwt>  
  </when>  
  <otherwise>  
    <validate-jwt header-name="Authorization">  
      <issuer-signing-keys>  
        <key>@((string)context.Variables["signingKey"])</key>  
      </issuer-signing-keys>  
    </validate-jwt>  
  </otherwise>  
</choose>  

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
validate-jwtvalidate-jwt Elemento radice.Root element. Yes
audiencesaudiences Contiene un elenco di attestazioni "audience" accettabili che possono essere presenti nel token.Contains a list of acceptable audience claims that can be present on the token. Se sono presenti più valori "audience", viene provato ogni valore fino al completamento di tutti i valori (caso in cui la convalida ha esito negativo) o fino a quando un valore non ha esito positivo.If multiple audience values are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds. È necessario specificare almeno un "audience".At least one audience must be specified. NoNo
issuer-signing-keysissuer-signing-keys Elenco di chiavi di sicurezza con codifica Base64 usato per convalidare i token firmati.A list of Base64-encoded security keys used to validate signed tokens. Se sono presenti più chiavi di sicurezza, viene provata ogni chiave fino al completamento di tutte le chiavi (caso in cui la convalida ha esito negativo) o fino a quando una chiave non ha esito positivo.If multiple security keys are present, then each key is tried until either all are exhausted (in which case validation fails) or until one succeeds (useful for token rollover). Gli elementi chiave contengono un attributo id facoltativo, usato per il confronto con l'attestazione kid.Key elements have an optional id attribute used to match against kid claim. NoNo
issuersissuers Elenco di entità accettabili che hanno emesso il token.A list of acceptable principals that issued the token. Se sono presenti più valori emittenti, viene provato ogni valore fino al completamento di tutti i valori (caso in cui la convalida ha esito negativo) o fino a quando un valore non ha esito positivo.If multiple issuer values are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds. NoNo
openid-configopenid-config Elemento usato per specificare un endpoint di configurazione Open ID conforme da cui è possibile ottenere le chiavi di firma e l'emittente.The element used for specifying a compliant Open ID configuration endpoint from which signing keys and issuer can be obtained. NoNo
required-claimsrequired-claims Contiene un elenco di attestazioni da includere nel token affinché possa essere considerato valido.Contains a list of claims expected to be present on the token for it to be considered valid. Perché la convalida abbia esito positivo, quando l'attributo match è impostato su all ogni valore dell'attestazione nel criterio deve essere presente nel token.When the match attribute is set to all every claim value in the policy must be present in the token for validation to succeed. Perché la convalida abbia esito positivo, quando l'attributo match è impostato su any almeno un'attestazione deve essere presente nel token.When the match attribute is set to any at least one claim must be present in the token for validation to succeed. NoNo
zumo-master-keyzumo-master-key Chiave master per i token rilasciati da Servizi mobili di AzureMaster key for tokens issued by Azure Mobile Services NoNo

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
clock-skewclock-skew TimeSpan.Timespan. Fornisce un minimo margine temporale nel caso in cui nel token sia presente l'attestazione di scadenza del token e abbia superato la data/l'ora corrente.Provides some small leeway in case the token's expiration claim is present in the token and is past the current date / time. NoNo 0 secondi0 seconds
failed-validation-error-messagefailed-validation-error-message Messaggio di errore da restituire nel corpo della risposta HTTP se il token JWT non supera la convalida.Error message to return in the HTTP response body if the JWT does not pass validation. I caratteri speciali eventualmente contenuti in questo messaggio devono essere adeguatamente preceduti da un carattere di escape.This message must have any special characters properly escaped. NoNo Il messaggio di errore predefinito dipende dal problema della convalida, ad esempio "JWT not present" ("JWT non presente").Default error message depends on validation issue, for example "JWT not present."
failed-validation-httpcodefailed-validation-httpcode Codice di stato HTTP da restituire se il token JWT non supera la convalida.HTTP Status code to return if the JWT doesn't pass validation. NoNo 401401
header-nameheader-name Il nome dell'intestazione HTTP che contiene il token.The name of the HTTP header holding the token. È necessario specificare header-name o query-paremeter-name, ma non entrambi.Either header-name or query-paremeter-name must be specified; but not both. N/DN/A
idid L'attributo id nell'elemento key consente di specificare la stringa che verrà confrontata con l'attestazione kid nel token (se presente) per individuare la chiave appropriata da usare per la convalida della firma.The id attribute on the key element allows you to specify the string that will be matched against kid claim in the token (if present) to find out the appropriate key to use for signature validation. NoNo N/DN/A
matchmatch Perché la convalida abbia esito positivo, l'attributo match sull'elemento claim specifica se il valore dell'attestazione nel criterio deve essere presente nel token.The match attribute on the claim element specifies whether every claim value in the policy must be present in the token for validation to succeed. I valori possibili sono:Possible values are:

- all: ogni valore dell'attestazione nel criterio deve essere presente nel token perché la convalida abbia esito positivo.- all - every claim value in the policy must be present in the token for validation to succeed.

- any: almeno un valore dell'attestazione deve essere presente nel token perché la convalida abbia esito positivo.- any - at least one claim value must be present in the token for validation to succeed.
NoNo tuttiall
query-paremeter-namequery-paremeter-name Nome di parametro di query che contiene il token.The name of the the query parameter holding the token. È necessario specificare header-name o query-paremeter-name, ma non entrambi.Either header-name or query-paremeter-name must be specified; but not both. N/DN/A
require-expiration-timerequire-expiration-time Booleano.Boolean. Specifica se è necessaria un'attestazione di scadenza nel token.Specifies whether an expiration claim is required in the token. NoNo truetrue
require-schemerequire-scheme Il nome dello schema di token, ad esempio "Bearer".The name of the token scheme, e.g. "Bearer". Quando questo attributo è impostato, il criterio assicura che lo schema specificato sia presente nel valore dell'intestazione di autorizzazione.When this attribute is set, the policy will ensure that specified scheme is present in the Authorization header value. NoNo N/DN/A
require-signed-tokensrequire-signed-tokens Booleano.Boolean. Specifica se è necessario firmare un token.Specifies whether a token is required to be signed. NoNo truetrue
separatorseparator Stringa.String. Specifica un separatore (ad esempio ",") da usare per l'estrazione di un set di valori da un'attestazione multivalore.Specifies a separator (e.g. ",") to be used for extracting a set of values from a multi-valued claim. NoNo N/DN/A
URLurl URL dell'endpoint di configurazione Open ID dal quale è possibile ottenere i metadati della configurazione Open ID.Open ID configuration endpoint URL from where Open ID configuration metadata can be obtained. Per Azure Active Directory, usare il seguente URL: https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration sostituendo il nome del tenant della directory in uso, ad esempio contoso.onmicrosoft.com.For Azure Active Directory use the following URL: https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration substituting your directory tenant name, e.g. contoso.onmicrosoft.com. Yes N/DN/A

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: inboundPolicy sections: inbound
  • Ambiti del criterio: globale, prodotto, API, operazionePolicy scopes: global, product, API, operation

Passaggi successiviNext steps

Per altre informazioni sull'uso di questi criteri, vedere:For more information working with policies, see: