Políticas de restrição de acesso à Gestão de APIAPI Management access restriction policies

Este tópico fornece uma referência para as seguintes políticas de Gestão da API.This topic provides a reference for the following API Management policies. Para obter informações sobre políticas de adição e configuração, consulte Políticas em Gestão de API.For information on adding and configuring policies, see Policies in API Management.

Políticas de restrição de acessoAccess restriction policies

Dica

Pode utilizar políticas de restrição de acesso em diferentes âmbitos para diferentes finalidades.You can use access restriction policies in different scopes for different purposes. Por exemplo, pode proteger toda a API com autenticação AAD aplicando a validate-jwt política ao nível da API ou pode aplicá-la ao nível de operação da API e usá-la claims para um controlo mais granular.For example, you can secure the whole API with AAD authentication by applying the validate-jwt policy on the API level or you can apply it on the API operation level and use claims for more granular control.

Verifique o cabeçalho HTTPCheck HTTP header

Utilize a check-header política para impor que um pedido tem um cabeçalho HTTP especificado.Use the check-header policy to enforce that a request has a specified HTTP header. Pode verificar opcionalmente se o cabeçalho tem um valor específico ou se verifica uma gama de valores permitidos.You can optionally check to see if the header has a specific value or check for a range of allowed values. Se a verificação falhar, a apólice termina o processamento do pedido e devolve o código de estado HTTP e a mensagem de erro especificada pela apólice.If the check fails, the policy terminates request processing and returns the HTTP status code and error message specified by the policy.

Declaração políticaPolicy 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>

ExemploExample

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

ElementosElements

NomeName DescriçãoDescription ObrigatórioRequired
cabeçalho de verificaçãocheck-header Elemento de raiz.Root element. YesYes
valorvalue Valor do cabeçalho HTTP permitido.Allowed HTTP header value. Quando vários elementos de valor são especificados, a verificação é considerada um sucesso se algum dos valores for compatível.When multiple value elements are specified, the check is considered a success if any one of the values is a match. NoNo

AtributosAttributes

NomeName DescriçãoDescription ObrigatórioRequired PredefiniçãoDefault
falha na verificação de erro-mensagemfailed-check-error-message Error message to return in the HTTP response body if the header don't exist or has a invalid value.Error message to return in the HTTP response body if the header doesn't exist or has an invalid value. Esta mensagem deve ter quaisquer caracteres especiais devidamente escapados.This message must have any special characters properly escaped. YesYes N/DN/A
falha no cheque-httpcodefailed-check-httpcode HTTP Código de estado para devolver se o cabeçalho não existir ou tiver um valor inválido.HTTP Status code to return if the header doesn't exist or has an invalid value. YesYes N/DN/A
cabeçalho-nomeheader-name O nome do cabeçalho HTTP para verificar.The name of the HTTP Header to check. YesYes N/DN/A
ignorar casoignore-case Pode ser definido como Verdadeiro ou Falso.Can be set to True or False. Se definido para o caso Verdadeiro é ignorado quando o valor do cabeçalho é comparado com o conjunto de valores aceitáveis.If set to True case is ignored when the header value is compared against the set of acceptable values. YesYes N/DN/A

UtilizaçãoUsage

Esta política pode ser utilizada nas seguintes secções e âmbitos políticos.This policy can be used in the following policy sections and scopes.

  • Secções políticas: entrada, saídaPolicy sections: inbound, outbound

  • Âmbitos de política: todos os âmbitosPolicy scopes: all scopes

Taxa de chamada limite por subscriçãoLimit call rate by subscription

A rate-limit política impede picos de utilização da API por subscrição, limitando a taxa de chamada a um número especificado por um período de tempo especificado.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. Quando a taxa de chamada é excedida, o chamador recebe um 429 Too Many Requests código de estado de resposta.When the call rate is exceeded, the caller receives a 429 Too Many Requests response status code.

Importante

Esta política só pode ser utilizada uma vez por documento político.This policy can be used only once per policy document.

As expressões políticas não podem ser utilizadas em nenhum dos atributos políticos para esta política.Policy expressions cannot be used in any of the policy attributes for this policy.

Atenção

Devido à natureza distribuída da arquitetura de estrangulamento, a limitação das taxas nunca é completamente precisa.Due to the distributed nature of throttling architecture, rate limiting is never completely accurate. A diferença entre configurado e o número real de pedidos permitidos varia em função do volume e taxa de pedido, da latência de backend e de outros fatores.The difference between configured and the real number of allowed requests vary based on request volume and rate, backend latency, and other factors.

Nota

Para compreender a diferença entre limites de taxa e quotas, consulte limites de taxa e quotas.To understand the difference between rate limits and quotas, see Rate limits and quotas.

Declaração políticaPolicy statement

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

ExemploExample

No exemplo seguinte, o limite de taxa por subscrição é de 20 chamadas por 90 segundos.In the following example, the per subscription rate limit is 20 calls per 90 seconds. Após cada execução política, as chamadas restantes permitidas no período de tempo são armazenadas na variável remainingCallsPerSubscription .After each policy execution, the remaining calls allowed in the time period are stored in the variable remainingCallsPerSubscription.

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

ElementosElements

NomeName DescriçãoDescription ObrigatórioRequired
limite de taxarate-limit Elemento de raiz.Root element. YesYes
apiapi Adicione um ou mais destes elementos para impor um limite de taxa de chamada às APIs dentro do produto.Add one or more of these elements to impose a call rate limit on APIs within the product. Os limites de taxa de chamada de produto e API são aplicados de forma independente.Product and API call rate limits are applied independently. A API pode ser referenciada através name ou id . .API can be referenced either via name or id. Se ambos os atributos forem fornecidos, id serão utilizados e name serão ignorados.If both attributes are provided, id will be used and name will be ignored. NoNo
operationoperation Adicione um ou mais destes elementos para impor um limite de taxa de chamada às operações dentro de uma API.Add one or more of these elements to impose a call rate limit on operations within an API. Os limites de taxa de chamada de produto, API e operação são aplicados de forma independente.Product, API, and operation call rate limits are applied independently. A operação pode ser referenciada através name ou id . .Operation can be referenced either via name or id. Se ambos os atributos forem fornecidos, id serão utilizados e name serão ignorados.If both attributes are provided, id will be used and name will be ignored. NoNo

AtributosAttributes

NomeName DescriçãoDescription ObrigatórioRequired PredefiniçãoDefault
namename O nome da API para a aplicação do limite de taxa.The name of the API for which to apply the rate limit. YesYes N/DN/A
chamacalls O número máximo total de chamadas permitidas durante o intervalo de tempo especificado em renewal-period .The maximum total number of calls allowed during the time interval specified in renewal-period. YesYes N/DN/A
período de renovaçãorenewal-period O comprimento em segundos da janela de deslizamento durante o qual o número de pedidos permitidos não deve exceder o valor especificado em calls .The length in seconds of the sliding window during which the number of allowed requests should nor exceed the value specified in calls. YesYes N/DN/A
recandidutar-pós-cabeçalho-nomeretry-after-header-name O nome de um cabeçalho de resposta cujo valor é o intervalo de repetição recomendado em segundos após a exceção da taxa de chamada especificada.The name of a response header whose value is the recommended retry interval in seconds after the specified call rate is exceeded. NoNo N/DN/A
recandidutar-pós-nome variávelretry-after-variable-name O nome de uma variável de expressão de política que armazena o intervalo de repetição recomendado em segundos após a taxa de chamada especificada é excedida.The name of a policy expression variable that stores the recommended retry interval in seconds after the specified call rate is exceeded. NoNo N/DN/A
restantes chamadas-cabeçalho-nomeremaining-calls-header-name O nome de um cabeçalho de resposta cujo valor após cada execução política é o número de chamadas restantes permitidas para o intervalo de tempo especificado no renewal-period .The name of a response header whose value after each policy execution is the number of remaining calls allowed for the time interval specified in the renewal-period. NoNo N/DN/A
restantes chamadas-nome variávelremaining-calls-variable-name O nome de uma variável de expressão política que após cada execução de política armazena o número de chamadas restantes permitidas para o intervalo de tempo especificado no renewal-period .The name of a policy expression variable that after each policy execution stores the number of remaining calls allowed for the time interval specified in the renewal-period. NoNo N/DN/A
total-chamadas-cabeçalho-nometotal-calls-header-name O nome de um cabeçalho de resposta cujo valor é o valor especificado em calls .The name of a response header whose value is the value specified in calls. NoNo N/DN/A

UtilizaçãoUsage

Esta política pode ser utilizada nas seguintes secções e âmbitos políticos.This policy can be used in the following policy sections and scopes.

  • Secções políticas: entradaPolicy sections: inbound

  • Âmbitos de política: produto, api, operaçãoPolicy scopes: product, api, operation

Taxa de chamada limite por chaveLimit call rate by key

Importante

Esta funcionalidade não está disponível no nível de Consumo da Gestão da API.This feature is unavailable in the Consumption tier of API Management.

A rate-limit-by-key política impede picos de utilização da API numa base-chave, limitando a taxa de chamada a um número especificado por um período de tempo especificado.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. A chave pode ter um valor de cadeia arbitrária e é normalmente fornecida usando uma expressão política.The key can have an arbitrary string value and is typically provided using a policy expression. A condição de incremento opcional pode ser adicionada para especificar quais os pedidos que devem ser contados para o limite.Optional increment condition can be added to specify which requests should be counted towards the limit. Quando esta taxa de chamada é excedida, o chamador recebe um 429 Too Many Requests código de estado de resposta.When this call rate is exceeded, the caller receives a 429 Too Many Requests response status code.

Para obter mais informações e exemplos desta política, consulte o pedido avançado de estrangulamento com a Azure API Management.For more information and examples of this policy, see Advanced request throttling with Azure API Management.

Atenção

Devido à natureza distribuída da arquitetura de estrangulamento, a limitação das taxas nunca é completamente precisa.Due to the distributed nature of throttling architecture, rate limiting is never completely accurate. A diferença entre configurado e o número real de pedidos permitidos varia em função do volume e taxa de pedido, da latência de backend e de outros fatores.The difference between configured and the real number of allowed requests vary based on request volume and rate, backend latency, and other factors.

Nota

Para compreender a diferença entre limites de taxa e quotas, consulte limites de taxa e quotas.To understand the difference between rate limits and quotas, see Rate limits and quotas.

Declaração políticaPolicy statement

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

ExemploExample

No exemplo seguinte, o limite de taxa de 10 chamadas por 60 segundos é chavedo pelo endereço IP do autor da chamada.In the following example, the rate limit of 10 calls per 60 seconds is keyed by the caller IP address. Após cada execução política, as chamadas restantes permitidas no período de tempo são armazenadas na variável remainingCallsPerIP .After each policy execution, the remaining calls allowed in the time period are stored in the variable 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>

ElementosElements

NomeName DescriçãoDescription ObrigatórioRequired
taxa-limite-por-chaverate-limit-by-key Elemento de raiz.Root element. YesYes

AtributosAttributes

NomeName DescriçãoDescription ObrigatórioRequired PredefiniçãoDefault
chamacalls O número máximo total de chamadas permitidas durante o intervalo de tempo especificado no renewal-period .The maximum total number of calls allowed during the time interval specified in the renewal-period. YesYes N/DN/A
contra-chavecounter-key A chave a utilizar para a política de limite de taxas.The key to use for the rate limit policy. YesYes N/DN/A
incremento condiçãoincrement-condition A expressão booleana especificando se o pedido deve ser contado para a taxa true ().The boolean expression specifying if the request should be counted towards the rate (true). NoNo N/DN/A
período de renovaçãorenewal-period O comprimento em segundos da janela de deslizamento durante o qual o número de pedidos permitidos não deve exceder o valor especificado em calls .The length in seconds of the sliding window during which the number of allowed requests should nor exceed the value specified in calls. YesYes N/DN/A
recandidutar-pós-cabeçalho-nomeretry-after-header-name O nome de um cabeçalho de resposta cujo valor é o intervalo de repetição recomendado em segundos após a exceção da taxa de chamada especificada.The name of a response header whose value is the recommended retry interval in seconds after the specified call rate is exceeded. NoNo N/DN/A
recandidutar-pós-nome variávelretry-after-variable-name O nome de uma variável de expressão de política que armazena o intervalo de repetição recomendado em segundos após a taxa de chamada especificada é excedida.The name of a policy expression variable that stores the recommended retry interval in seconds after the specified call rate is exceeded. NoNo N/DN/A
restantes chamadas-cabeçalho-nomeremaining-calls-header-name O nome de um cabeçalho de resposta cujo valor após cada execução política é o número de chamadas restantes permitidas para o intervalo de tempo especificado no renewal-period .The name of a response header whose value after each policy execution is the number of remaining calls allowed for the time interval specified in the renewal-period. NoNo N/DN/A
restantes chamadas-nome variávelremaining-calls-variable-name O nome de uma variável de expressão política que após cada execução de política armazena o número de chamadas restantes permitidas para o intervalo de tempo especificado no renewal-period .The name of a policy expression variable that after each policy execution stores the number of remaining calls allowed for the time interval specified in the renewal-period. NoNo N/DN/A
total-chamadas-cabeçalho-nometotal-calls-header-name O nome de um cabeçalho de resposta cujo valor é o valor especificado em calls .The name of a response header whose value is the value specified in calls. NoNo N/DN/A

UtilizaçãoUsage

Esta política pode ser utilizada nas seguintes secções e âmbitos políticos.This policy can be used in the following policy sections and scopes.

  • Secções políticas: entradaPolicy sections: inbound

  • Âmbitos de política: todos os âmbitosPolicy scopes: all scopes

Restringir os IPs de chamadasRestrict caller IPs

Os ip-filter filtros de política (permite/nega) chamadas de endereços IP específicos e/ou intervalos de endereços.The ip-filter policy filters (allows/denies) calls from specific IP addresses and/or address ranges.

Declaração políticaPolicy statement

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

ExemploExample

No exemplo seguinte, a política apenas permite pedidos provenientes do único endereço IP ou intervalo de endereços IP especificadosIn the following example, the policy only allows requests coming either from the single IP address or range of IP addresses specified

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

ElementosElements

NomeName DescriçãoDescription ObrigatórioRequired
ip-filtroip-filter Elemento de raiz.Root element. YesYes
addressaddress Especifica um único endereço IP para filtrar.Specifies a single IP address on which to filter. Pelo menos um address ou address-range elemento é necessário.At least one address or address-range element is required.
endereço-gama de="endereço" para ="endereço"address-range from="address" to="address" Especifica uma gama de endereços IP para filtrar.Specifies a range of IP address on which to filter. Pelo menos um address ou address-range elemento é necessário.At least one address or address-range element is required.

AtributosAttributes

NomeName DescriçãoDescription ObrigatórioRequired PredefiniçãoDefault
endereço-gama de="endereço" para ="endereço"address-range from="address" to="address" Uma gama de endereços IP para permitir ou negar acesso.A range of IP addresses to allow or deny access for. Requerido quando o address-range elemento é utilizado.Required when the address-range element is used. N/DN/A
ip-filter action="permitir | proibir"ip-filter action="allow | forbid" Especifica se as chamadas devem ser permitidas ou não para os endereços e intervalos IP especificados.Specifies whether calls should be allowed or not for the specified IP addresses and ranges. YesYes N/DN/A

UtilizaçãoUsage

Esta política pode ser utilizada nas seguintes secções e âmbitos políticos.This policy can be used in the following policy sections and scopes.

  • Secções políticas: entradaPolicy sections: inbound
  • Âmbitos de política: todos os âmbitosPolicy scopes: all scopes

Definir quota de utilização por subscriçãoSet usage quota by subscription

A quota política aplica um volume de chamadas renováveis ou vitalícios e/ou quota de largura de banda, por subscrição.The quota policy enforces a renewable or lifetime call volume and/or bandwidth quota, on a per subscription basis.

Importante

Esta política só pode ser utilizada uma vez por documento político.This policy can be used only once per policy document.

As expressões políticas não podem ser utilizadas em nenhum dos atributos políticos para esta política.Policy expressions cannot be used in any of the policy attributes for this policy.

Nota

Para compreender a diferença entre limites de taxa e quotas, consulte limites de taxa e quotas.To understand the difference between rate limits and quotas, see Rate limits and quotas.

Declaração políticaPolicy statement

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

ExemploExample

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

ElementosElements

NomeName DescriçãoDescription ObrigatórioRequired
quotaquota Elemento de raiz.Root element. YesYes
apiapi Adicione um ou mais destes elementos para impor quotas de chamada em APIs dentro do produto.Add one or more of these elements to impose call quota on APIs within the product. As quotas de chamadas de produtos e API são aplicadas de forma independente.Product and API call quotas are applied independently. A API pode ser referenciada através name ou id . .API can be referenced either via name or id. Se ambos os atributos forem fornecidos, id serão utilizados e name serão ignorados.If both attributes are provided, id will be used and name will be ignored. NoNo
operationoperation Adicione um ou mais destes elementos para impor quota de chamada em operações dentro de uma API.Add one or more of these elements to impose call quota on operations within an API. As quotas de chamadas de produtos, API e operação são aplicadas de forma independente.Product, API, and operation call quotas are applied independently. A operação pode ser referenciada através name ou id . .Operation can be referenced either via name or id. Se ambos os atributos forem fornecidos, id serão utilizados e name serão ignorados.If both attributes are provided, id will be used and name will be ignored. NoNo

AtributosAttributes

NomeName DescriçãoDescription ObrigatórioRequired PredefiniçãoDefault
namename O nome da API ou da operação para a qual o contingente se aplica.The name of the API or operation for which the quota applies. YesYes N/DN/A
largura de bandabandwidth O número total máximo de quilobytes permitido durante o intervalo de tempo especificado no renewal-period .The maximum total number of kilobytes allowed during the time interval specified in the renewal-period. Ou calls , ou ambos bandwidth juntos devem ser especificados.Either calls, bandwidth, or both together must be specified. N/DN/A
chamacalls O número máximo total de chamadas permitidas durante o intervalo de tempo especificado no renewal-period .The maximum total number of calls allowed during the time interval specified in the renewal-period. Ou calls , ou ambos bandwidth juntos devem ser especificados.Either calls, bandwidth, or both together must be specified. N/DN/A
período de renovaçãorenewal-period O período de tempo em segundos após o qual a quota se repõe.The time period in seconds after which the quota resets. Quando está definido para 0 o período é definido para infinito.When it's set to 0 the period is set to infinite. YesYes N/DN/A

UtilizaçãoUsage

Esta política pode ser utilizada nas seguintes secções e âmbitos políticos.This policy can be used in the following policy sections and scopes.

  • Secções políticas: entradaPolicy sections: inbound
  • Âmbitos de política: produtoPolicy scopes: product

Definir quota de utilização por chaveSet usage quota by key

Importante

Esta funcionalidade não está disponível no nível de Consumo da Gestão da API.This feature is unavailable in the Consumption tier of API Management.

A quota-by-key política aplica, por título, um volume de chamadas renováveis ou vitalícios e/ou uma quota de largura de banda.The quota-by-key policy enforces a renewable or lifetime call volume and/or bandwidth quota, on a per key basis. A chave pode ter um valor de cadeia arbitrária e é normalmente fornecida usando uma expressão política.The key can have an arbitrary string value and is typically provided using a policy expression. A condição de incremento opcional pode ser adicionada para especificar quais os pedidos que devem ser contabilizados para o contingente.Optional increment condition can be added to specify which requests should be counted towards the quota. Se várias políticas incrementar o mesmo valor-chave, é incrementada apenas uma vez por pedido.If multiple policies would increment the same key value, it is incremented only once per request. Quando a taxa de chamada é excedida, o chamador recebe um 403 Forbidden código de estado de resposta.When the call rate is exceeded, the caller receives a 403 Forbidden response status code.

Para obter mais informações e exemplos desta política, consulte o pedido avançado de estrangulamento com a Azure API Management.For more information and examples of this policy, see Advanced request throttling with Azure API Management.

Nota

Para compreender a diferença entre limites de taxa e quotas, consulte limites de taxa e quotas.To understand the difference between rate limits and quotas, see Rate limits and quotas.

Declaração políticaPolicy statement

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

ExemploExample

No exemplo seguinte, a quota é chaveda pelo endereço IP do autor da chamada.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>

ElementosElements

NomeName DescriçãoDescription ObrigatórioRequired
quotaquota Elemento de raiz.Root element. YesYes

AtributosAttributes

NomeName DescriçãoDescription ObrigatórioRequired PredefiniçãoDefault
largura de bandabandwidth O número total máximo de quilobytes permitido durante o intervalo de tempo especificado no renewal-period .The maximum total number of kilobytes allowed during the time interval specified in the renewal-period. Ou calls , ou ambos bandwidth juntos devem ser especificados.Either calls, bandwidth, or both together must be specified. N/DN/A
chamacalls O número máximo total de chamadas permitidas durante o intervalo de tempo especificado no renewal-period .The maximum total number of calls allowed during the time interval specified in the renewal-period. Ou calls , ou ambos bandwidth juntos devem ser especificados.Either calls, bandwidth, or both together must be specified. N/DN/A
contra-chavecounter-key A chave a utilizar para a política de quotas.The key to use for the quota policy. YesYes N/DN/A
incremento condiçãoincrement-condition A expressão booleana especificando se o pedido deve ser contado para a quota true ()The boolean expression specifying if the request should be counted towards the quota (true) NoNo N/DN/A
período de renovaçãorenewal-period O período de tempo em segundos após o qual a quota se repõe.The time period in seconds after which the quota resets. Quando está definido para 0 o período é definido para infinito.When it's set to 0 the period is set to infinite. YesYes N/DN/A

UtilizaçãoUsage

Esta política pode ser utilizada nas seguintes secções e âmbitos políticos.This policy can be used in the following policy sections and scopes.

  • Secções políticas: entradaPolicy sections: inbound
  • Âmbitos de política: todos os âmbitosPolicy scopes: all scopes

Validar JWTValidate JWT

A validate-jwt política impõe a existência e a validade de um token web JSON (JWT) extraído de um cabeçalho HTTP especificado ou de um parâmetro de consulta especificado.The validate-jwt policy enforces existence and validity of a JSON web token (JWT) extracted from either a specified HTTP Header or a specified query parameter.

Importante

A validate-jwt política exige que a exp reclamação registada esteja incluída no token JWT, a menos que o require-expiration-time atributo seja especificado e definido para false .The validate-jwt policy requires that the exp registered claim is included in the JWT token, unless require-expiration-time attribute is specified and set to false. A validate-jwt política suporta algoritmos de assinatura HS256 e RS256.The validate-jwt policy supports HS256 and RS256 signing algorithms. Para o HS256, a chave deve ser fornecida em linha dentro da política na forma codificada base64.For HS256 the key must be provided inline within the policy in the base64 encoded form. Para o RS256, a chave pode ser fornecida através de um ponto final de configuração open ID, ou fornecendo o ID de um certificado carregado que contenha a chave pública ou o par expoente modulus da chave pública.For RS256 the key may be provided either via an Open ID configuration endpoint, or by providing the ID of an uploaded certificate that contains the public key or modulus-exponent pair of the public key. A validate-jwt política suporta fichas encriptadas com chaves simétricas usando os seguintes algoritmos de encriptação: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.The validate-jwt policy supports tokens encrypted with symmetric keys using the following encryption algorithms: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.

Declaração políticaPolicy 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"
    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>

ExemplosExamples

Validação simples do símboloSimple token validation

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

Validação token com certificado RSAToken validation with RSA certificate

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

Validação do token do Azure Ative 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>

Validação do símbolo do Azure Ative 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>

Autorizar o acesso a operações com base em sinistros simbólicosAuthorize access to operations based on token claims

Este exemplo mostra como utilizar a política validada do JWT para autorizar o acesso a operações com base no valor das reclamações simbólicas.This example shows how to use the Validate JWT policy to authorize access to operations based on token claims value.

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

ElementosElements

ElementoElement DescriçãoDescription ObrigatórioRequired
validar-jwtvalidate-jwt Elemento de raiz.Root element. YesYes
públicosaudiences Contém uma lista de reclamações aceitáveis de audiência que podem estar presentes no token.Contains a list of acceptable audience claims that can be present on the token. Se estiverem presentes vários valores de audiência, cada valor é tentado até que todos estejam esgotados (caso em que a validação falha) ou até que um tenha sucesso.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. Pelo menos uma audiência deve ser especificada.At least one audience must be specified. NoNo
emitentes-assinatura-chavesissuer-signing-keys Uma lista de chaves de segurança codificadas pela Base64 usadas para validar fichas assinadas.A list of Base64-encoded security keys used to validate signed tokens. Se estiverem presentes várias teclas de segurança, cada tecla é tentada até que todas estejam esgotadas (caso em que a validação falha) ou uma delas é bem sucedida (útil para o capotamento do token).If multiple security keys are present, then each key is tried until either all are exhausted (in which case validation fails) or one succeeds (useful for token rollover). Os elementos-chave têm um atributo opcional id usado para corresponder à kid reclamação.Key elements have an optional id attribute used to match against kid claim.

Alternativamente, forneça uma chave de assinatura de emitente utilizando:Alternatively supply an issuer signing key using:

- certificate-id em formato <key certificate-id="mycertificate" /> para especificar o identificador de uma entidade de certificados enviado para a API Management- certificate-id in format <key certificate-id="mycertificate" /> to specify the identifier of a certificate entity uploaded to API Management
- Par de módulos e expoentes RSA n e em formato para <key n="<modulus>" e="<exponent>" /> especificar os parâmetros RSA em formato codificado base64url- RSA modulus n and exponent e pair in format <key n="<modulus>" e="<exponent>" /> to specify the RSA parameters in base64url-encoded format
NoNo
desencriptação-chavesdecryption-keys Uma lista de chaves codificadas da Base64 usadas para desencriptar os tokens.A list of Base64-encoded keys used to decrypt the tokens. Se estiverem presentes várias teclas de segurança, cada tecla é experimenta até que todas as teclas estejam esgotadas (caso em que a validação falha) ou uma chave tenha sucesso.If multiple security keys are present, then each key is tried until either all keys are exhausted (in which case validation fails) or a key succeeds. Os elementos-chave têm um atributo opcional id usado para corresponder à kid reclamação.Key elements have an optional id attribute used to match against kid claim.

Alternativamente, forneça uma chave de desencriptação utilizando:Alternatively supply a decryption key using:

- certificate-id em formato <key certificate-id="mycertificate" /> para especificar o identificador de uma entidade de certificados enviado para a API Management- certificate-id in format <key certificate-id="mycertificate" /> to specify the identifier of a certificate entity uploaded to API Management
NoNo
emitentesissuers Uma lista de princípios aceitáveis que emitiu o símbolo.A list of acceptable principals that issued the token. Se estiverem presentes vários valores emitentes, cada valor é tentado até que todos estejam esgotados (caso em que a validação falha) ou até que um tenha sucesso.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 O elemento utilizado para especificar um ponto final de configuração open id compatível a partir do qual podem ser obtidas teclas de assinatura e emitente.The element used for specifying a compliant Open ID configuration endpoint from which signing keys and issuer can be obtained. NoNo
reivindicações necessáriasrequired-claims Contém uma lista de reclamações que se espera estarem presentes no token para que seja considerada válida.Contains a list of claims expected to be present on the token for it to be considered valid. Quando o match atributo for definido para cada valor de all reclamação na apólice deve estar presente no símbolo para que a validação tenha sucesso.When the match attribute is set to all every claim value in the policy must be present in the token for validation to succeed. Quando o match atributo for definido para pelo menos uma any reclamação deve estar presente no símbolo para validação ter sucesso.When the match attribute is set to any at least one claim must be present in the token for validation to succeed. NoNo

AtributosAttributes

NomeName DescriçãoDescription ObrigatórioRequired PredefiniçãoDefault
relógio-distorcerclock-skew Tempo.Timespan. Utilize para especificar a diferença de tempo máxima esperada entre os relógios do sistema do emitente simbólico e a instância de Gestão da API.Use to specify maximum expected time difference between the system clocks of the token issuer and the API Management instance. NoNo 0 segundos0 seconds
falha-validação-erro-mensagemfailed-validation-error-message Error message to return in the HTTP response body if the JWT does passes validation.Error message to return in the HTTP response body if the JWT does not pass validation. Esta mensagem deve ter quaisquer caracteres especiais devidamente escapados.This message must have any special characters properly escaped. NoNo A mensagem de erro por defeito depende de problema de validação, por exemplo "JWT não está presente".Default error message depends on validation issue, for example "JWT not present."
código de validação-httpcode falhadofailed-validation-httpcode HTTP Código de estado para retornar se o JWT não passar na validação.HTTP Status code to return if the JWT doesn't pass validation. NoNo 401401
cabeçalho-nomeheader-name O nome do cabeçalho HTTP segurando o símbolo.The name of the HTTP header holding the token. Um dos header-name , ou deve ser query-parameter-name token-value especificado.One of header-name, query-parameter-name or token-value must be specified. N/DN/A
consulta-parâmetro-nomequery-parameter-name O nome do parâmetro de consulta que mantém o símbolo.The name of the query parameter holding the token. Um dos header-name , ou deve ser query-parameter-name token-value especificado.One of header-name, query-parameter-name or token-value must be specified. N/DN/A
valor simbólicotoken-value Expressão devolvendo uma corda contendo ficha JWTExpression returning a string containing JWT token Um dos header-name , ou deve ser query-parameter-name token-value especificado.One of header-name, query-parameter-name or token-value must be specified. N/DN/A
IDid O id atributo no elemento permite key especificar a cadeia que será correspondida com kid a reclamação no token (se presente) para descobrir a chave adequada a usar para validação de assinatura.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
combinarmatch O match atributo sobre o elemento especifica se cada valor de reclamação na apólice deve estar presente no símbolo para que a claim validação tenha sucesso.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. Os valores possíveis são:Possible values are:

- all - todos os valores de reclamação da apólice devem estar presentes no símbolo para que a validação seja bem sucedida.- all - every claim value in the policy must be present in the token for validation to succeed.

- any - pelo menos um valor de reclamação deve estar presente no símbolo para que a validação tenha êxito.- any - at least one claim value must be present in the token for validation to succeed.
NoNo allall
exigir tempo de expiraçãorequire-expiration-time O Boolean.Boolean. Especifica se é necessário um pedido de caducidade no token.Specifies whether an expiration claim is required in the token. NoNo truetrue
exigir esquemarequire-scheme O nome do esquema simbólico, por exemplo, "Portador".The name of the token scheme, e.g. "Bearer". Quando este atributo for definido, a política garantirá que o regime especificado esteja presente no valor do cabeçalho de autorização.When this attribute is set, the policy will ensure that specified scheme is present in the Authorization header value. NoNo N/DN/A
exigir fichas assinadasrequire-signed-tokens O Boolean.Boolean. Especifica se um símbolo é necessário para ser assinado.Specifies whether a token is required to be signed. NoNo truetrue
separadorseparator Cadeia.String. Especifica um separador (por exemplo, "") a utilizar para extrair um conjunto de valores de uma reivindicação multivalores.Specifies a separator (e.g. ",") to be used for extracting a set of values from a multi-valued claim. NoNo N/DN/A
urlurl Open ID configuração URL de onde podem ser obtidos metadados de configuração de ID aberto.Open ID configuration endpoint URL from where Open ID configuration metadata can be obtained. A resposta deve ser de acordo com as especificações definidas na URL: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata .The response should be according to specs as defined at URL:https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata. Para o Azure Ative Directory utilize o seguinte URL: https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration substituindo o nome do seu inquilino de diretório, por contoso.onmicrosoft.com exemplo.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. YesYes N/DN/A
nome variável-ficha de saídaoutput-token-variable-name Cadeia.String. Nome da variável de contexto que receberá valor simbólico como objeto de tipo Jwt após validação de símbolos bem sucedidoName of context variable that will receive token value as an object of type Jwt upon successful token validation NoNo N/DN/A

UtilizaçãoUsage

Esta política pode ser utilizada nas seguintes secções e âmbitos políticos.This policy can be used in the following policy sections and scopes.

  • Secções políticas: entradaPolicy sections: inbound
  • Âmbitos de política: todos os âmbitosPolicy scopes: all scopes

Passos seguintesNext steps

Para obter mais informações sobre as políticas, consulte:For more information working with policies, see: