Políticas de restrição de acesso do Gerenciamento de API

Este tópico fornece uma referência para as políticas de Gerenciamento de API a seguir. Para obter mais informações sobre como adicionar e configurar políticas, consulte Políticas de Gerenciamento de API.

Políticas de restrição de acesso

Dica

Você pode usar políticas de restrição de acesso em escopos diferentes para finalidades distintas. Por exemplo, você pode proteger toda a API com a autenticação do AAD aplicando a política validate-jwt no nível da API ou no nível de operação da API e usar claims para um controle mais granular.

Verificar cabeçalho HTTP

Use a política check-header para impor que uma solicitação tem um cabeçalho HTTP especificado. Você pode, opcionalmente, verificar se o cabeçalho tem um valor específico ou procurar um intervalo de valores permitidos. Se a verificação falhar, a política encerrará o processamento da solicitação e retornará a mensagem de erro e código de status HTTP especificada pela política.

Declaração de política

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

Exemplo

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

Elementos

Nome Descrição Obrigatório
check-header Elemento raiz. Sim
value Valor do cabeçalho HTTP permitido. Quando vários elementos de valor são especificados, a verificação é considerada um sucesso se qualquer um dos valores é uma correspondência. No

Atributos

Nome Descrição Obrigatório Padrão
failed-check-error-message A mensagem de erro para retornar no corpo da resposta HTTP se o cabeçalho não existe ou tem um valor inválido. Esta mensagem deve conter quaisquer caracteres especiais adequadamente seguidos por caracteres de escape. Sim N/D
failed-check-httpcode O código de status HTTP para retornar se o cabeçalho não existir ou tiver um valor inválido. Sim N/D
header-name O nome do cabeçalho HTTP para verificar. Sim N/D
ignore-case Pode ser definido como True ou False. Se definido como True, maiúsculas e minúsculas são ignoradas quando o valor do cabeçalho é comparado com o conjunto de valores aceitáveis. Sim N/D

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: de entrada, de saída

  • Escopos da política: todos os escopos

Limitar a taxa de chamadas por assinatura

A política rate-limit impede picos de uso da API para cada assinatura, limitando a taxa de chamadas para um número especificado por um período de tempo especificado. Quando a taxa da chamada for ultrapassada, o chamador receberá um código de status de resposta 429 Too Many Requests.

Importante

Essa política pode ser usada apenas uma vez por cada documento de política.

As Expressões de política não podem ser usadas em nenhum dos atributos de política para esta política.

Cuidado

Devido à natureza distribuída da arquitetura de limitação, a limitação de taxa nunca é completamente precisa. A diferença entre a configuração e o número real de solicitações permitidas varia de acordo com o volume e a taxa de solicitação, a latência de back-end e outros fatores.

Observação

Para entender a diferença entre limites e cotas de taxa, confira Limites e cotas de taxa.

Declaração de política

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

Exemplo

No exemplo a seguir, o limite de taxa por assinatura é de 20 chamadas por 90 segundos. Após cada execução de política, as chamadas restantes permitidas no período são armazenadas na variável remainingCallsPerSubscription.

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

Elementos

Nome Descrição Obrigatório
rate-limit Elemento raiz. Yes
api Adicione um ou mais desses elementos para impor um limite de taxa de chamadas às APIs dentro do produto. Limites de taxa de chamadas à API e ao produto são aplicados de forma independente. A API pode ser referenciada através de name ou id. Se ambos os atributos são fornecidos, id será usado e name será ignorado. No
operation Adicione um ou mais desses elementos para impor um limite de taxa de chamadas às operações dentro de uma API. Limites de taxa de chamadas à API, operação e produto são aplicados de forma independente. A operação pode ser referenciada através de name ou id. Se ambos os atributos são fornecidos, id será usado e name será ignorado. No

Atributos

Nome Descrição Obrigatório Padrão
name O nome da API para a qual aplicar o limite de taxa. Sim N/D
chamadas O número total máximo de chamadas permitidas durante o intervalo de tempo especificado em renewal-period. Sim N/D
renewal-period A duração em segundos da janela deslizante durante a qual o número de solicitações permitidas não deve exceder o valor especificado em calls. Valor máximo permitido: 300 segundos. Sim N/D
retry-after-header-name O nome de um cabeçalho de resposta cujo valor é o intervalo de repetição recomendado em segundos depois que a taxa de chamada especificada é excedida. Não N/D
retry-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 depois que a taxa de chamada especificada é excedida. Não N/D
remaining-calls-header-name O nome de um cabeçalho de resposta cujo valor após cada execução de política é o número de chamadas restantes permitidas para o intervalo de tempo especificado no renewal-period. Não N/D
remaining-calls-variable-name O nome de uma variável de expressão de política que, depois de cada execução de política, armazena o número de chamadas restantes permitidas para o intervalo de tempo especificado no renewal-period. Não N/D
total-calls-header-name O nome de um cabeçalho de resposta cujo valor é aquele especificado em calls. Não N/D

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: de entrada

  • Escopos de política: produto, API, operação

Limitar a taxa de chamadas por chave

Importante

Esse recurso não está disponível na camada Consumo do Gerenciamento de API.

A política rate-limit-by-key impede picos de uso da API para cada chave, limitando a taxa de chamadas para um número especificado por um período de tempo especificado. A chave pode ter um valor de cadeia de caracteres arbitrária e geralmente é fornecida usando uma expressão de política. A condição de incremento opcional pode ser adicionada para especificar quais solicitações devem ser contadas para obtenção do limite. Quando essa taxa da chamada for ultrapassada, o chamador receberá um código de status de resposta 429 Too Many Requests.

Para obter mais informações e exemplos dessa política, consulte Limitação de solicitação avançada com o Gerenciamento de API do Azure.

Cuidado

Devido à natureza distribuída da arquitetura de limitação, a limitação de taxa nunca é completamente precisa. A diferença entre a configuração e o número real de solicitações permitidas varia de acordo com o volume e a taxa de solicitação, a latência de back-end e outros fatores.

Observação

Para entender a diferença entre limites e cotas de taxa, confira Limites e cotas de taxa.

Declaração de política

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

Exemplo

No exemplo a seguir, o limite de taxa de dez ligações a cada 60 segundos é codificado pelo endereço IP do chamador. Após cada execução de política, as chamadas restantes permitidas no período são armazenadas na variável 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>

Elementos

Nome Descrição Obrigatório
rate-limit-by-key Elemento raiz. Sim

Atributos

Nome Descrição Obrigatório Padrão
chamadas O número total máximo de chamadas permitidas durante o intervalo de tempo especificado no renewal-period. A expressão de política é permitida. Sim N/D
counter-key A chave a ser usada para a política de limite de taxa. Sim N/D
increment-condition A expressão booliana que especifica se a solicitação deve ser contabilizada para a taxa (true). Não N/D
renewal-period A duração em segundos da janela deslizante durante a qual o número de solicitações permitidas não deve exceder o valor especificado em calls. A expressão de política é permitida. Valor máximo permitido: 300 segundos. Sim N/D
retry-after-header-name O nome de um cabeçalho de resposta cujo valor é o intervalo de repetição recomendado em segundos depois que a taxa de chamada especificada é excedida. Não N/D
retry-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 depois que a taxa de chamada especificada é excedida. Não N/D
remaining-calls-header-name O nome de um cabeçalho de resposta cujo valor após cada execução de política é o número de chamadas restantes permitidas para o intervalo de tempo especificado no renewal-period. Não N/D
remaining-calls-variable-name O nome de uma variável de expressão de política que, depois de cada execução de política, armazena o número de chamadas restantes permitidas para o intervalo de tempo especificado no renewal-period. Não N/D
total-calls-header-name O nome de um cabeçalho de resposta cujo valor é aquele especificado em calls. Não N/D

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: de entrada

  • Escopos da política: todos os escopos

Restringir IPs do chamador

A política ip-filter filtra (permite/recusa) chamadas de endereços IP específicos e/ou intervalos de endereços.

Declaração de política

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

Exemplo

No exemplo a seguir, a política só permite solicitações provenientes do endereço IP único ou do intervalo de endereços IP especificados

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

Elementos

Nome Descrição Obrigatório
ip-filter Elemento raiz. Yes
address Especifica um único endereço IP no qual filtrar. Pelo menos um elemento address ou address-range é necessário.
address-range from="address" to="address" Especifica um intervalo de endereços IP nos quais filtrar. Pelo menos um elemento address ou address-range é necessário.

Atributos

Nome Descrição Obrigatório Padrão
address-range from="address" to="address" Um intervalo de endereços IP aos quais o acesso será permitido ou negado. Necessário quando o elemento address-range é usado. N/D
ip-filter action="allow | forbid" Especifica se chamadas para os endereços IP e intervalos de endereços IP especificados devem ou não ser permitidas. Sim N/D

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: de entrada
  • Escopos da política: todos os escopos

Definir a cota de uso por assinatura

A política quota impõe uma cota renovável ou de tempo de vida de volume de chamadas e/ou largura de banda, para cada assinatura.

Importante

Essa política pode ser usada apenas uma vez por cada documento de política.

As Expressões de política não podem ser usadas em nenhum dos atributos de política para esta política.

Observação

Para entender a diferença entre limites e cotas de taxa, confira Limites e cotas de taxa.

Declaração de política

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

Exemplo

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

Elementos

Nome Descrição Obrigatório
quota Elemento raiz. Yes
api Adicione um ou mais desses elementos para impor uma cota às APIs dentro do produto. Cotas de API e produto são aplicadas de forma independente. A API pode ser referenciada através de name ou id. Se ambos os atributos são fornecidos, id será usado e name será ignorado. No
operation Adicione um ou mais desses elementos para impor uma cota às operações dentro de uma API. Cotas de operações, APIs e produtos são aplicadas de forma independente. A operação pode ser referenciada através de name ou id. Se ambos os atributos são fornecidos, id será usado e name será ignorado. No

Atributos

Nome Descrição Obrigatório Padrão
name O nome da API ou operação à qual a cota se aplica. Sim N/D
largura de banda O número total máximo de kilobytes permitidos durante o intervalo de tempo especificado no renewal-period. calls ou bandwidth ou ainda ambos juntos devem ser especificados. N/D
chamadas O número total máximo de chamadas permitidas durante o intervalo de tempo especificado no renewal-period. calls ou bandwidth ou ainda ambos juntos devem ser especificados. N/D
renewal-period O período de tempo, em segundos, durante o qual uma cota reinicia. Quando definido como 0, o período é definido como infinito. Sim N/D

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: de entrada
  • Escopos de política: produto

Definir uma cota de uso por chave

Importante

Esse recurso não está disponível na camada Consumo do Gerenciamento de API.

A política quota-by-key impõe uma cota renovável ou de tempo de vida de volume de chamadas e/ou largura de banda, para cada chave. A chave pode ter um valor de cadeia de caracteres arbitrária e geralmente é fornecida usando uma expressão de política. A condição de incremento opcional pode ser adicionada para especificar quais solicitações devem ser contadas para obtenção da cota. Se várias políticas incrementassem o mesmo valor de chave, ele seria incrementado apenas uma vez por solicitação. Quando a taxa da chamada for ultrapassada, o chamador receberá um código de status de resposta 403 Forbidden.

Para obter mais informações e exemplos dessa política, consulte Limitação de solicitação avançada com o Gerenciamento de API do Azure.

Observação

Para entender a diferença entre limites e cotas de taxa, confira Limites e cotas de taxa.

Declaração de política

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

Exemplo

No exemplo a seguir, a cota é codificada pelo endereço IP do chamador.

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

Elementos

Nome Descrição Obrigatório
quota Elemento raiz. Sim

Atributos

Nome Descrição Obrigatório Padrão
largura de banda O número total máximo de kilobytes permitidos durante o intervalo de tempo especificado no renewal-period. calls ou bandwidth ou ainda ambos juntos devem ser especificados. N/D
chamadas O número total máximo de chamadas permitidas durante o intervalo de tempo especificado no renewal-period. calls ou bandwidth ou ainda ambos juntos devem ser especificados. N/D
counter-key A chave a ser usada para a política de cota. Sim N/D
increment-condition A expressão booliana que especifica se a solicitação deve ser contabilizada para a cota (true) Não N/D
renewal-period O período de tempo, em segundos, durante o qual uma cota reinicia. Quando definido como 0, o período é definido como infinito. Sim N/D

Observação

O valor do atributo counter-key deve ser único em todas as APIs no Gerenciamento de API se você não quiser compartilhar o total entre as outras APIs.

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: de entrada
  • Escopos da política: todos os escopos

Validar JWT

A política validate-jwt impõe a existência e a validade de um JWT (token Web JSON) extraído de um cabeçalho HTTP ou um parâmetro de consulta especificado.

Importante

A política validate-jwt requer que a declaração registrada exp seja incluída no token JWT, a menos que o atributo require-expiration-time seja especificado e definido como false. A política validate-jwt dá suporte aos algoritmos de assinatura HS256 e RS256. Para HS256, a chave deve ser fornecida embutida na política no formato codificado em base64. Para RS256, a chave pode ser fornecida por meio de um ponto de extremidade de configuração de ID Aberta ou fornecendo a ID de um certificado carregado que contém a chave pública ou o par de módulo-expoente da chave pública. A política validate-jwt dá suporte a tokens criptografados com chaves simétricas usando os seguintes algoritmos de criptografia: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.

Declaração de política

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

Exemplos

Validação de token simples

<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 de token com certificado RSA

<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 de token do Azure Active Directory

<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 de token do Azure Active Directory B2C

<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 para operações baseadas em declarações de token

Este exemplo mostra como usar a política Validar JWT para autorizar o acesso a operações baseadas no valor de declarações de token.

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

Elementos

Elemento Descrição Obrigatório
validate-jwt Elemento raiz. Yes
públicos-alvo Contém uma lista de declarações de público-alvo aceitáveis que podem estar presentes no token. Se vários valores de público-alvo estiverem presentes, cada valor será tentado até que todos sejam esgotados (nesse caso, a validação falhará) ou até obter êxito. Pelo menos um público-alvo deve ser especificado. No
issuer-signing-keys Uma lista de chaves de segurança codificadas em Base64 usadas para validar tokens assinados. Se várias chaves de segurança estiverem presentes, cada chave será tentada até que todas sejam esgotadas (nesse caso, a validação falhará) ou até obter êxito (útil para sobreposição de token). Elementos-chave têm um atributo id opcional usado para correspondência com a declaração kid.

Como alternativa, forneça uma chave de autenticação do emissor usando:

- certificate-id no formato <key certificate-id="mycertificate" /> para especificar o identificador de uma entidade de certificado carregada no Gerenciamento de API
-Par RSA de módulo n e expoente e no formato <key n="<modulus>" e="<exponent>" /> para especificar os parâmetros RSA no formato codificado em base64url
No
decryption-keys Uma lista de chaves codificadas em Base64 para descriptografar os tokens. Se várias chaves de segurança estiverem presentes, cada chave será tentada até que todas elas sejam esgotadas (nesse caso, a validação falhará) ou até uma chave obter êxito. Elementos-chave têm um atributo id opcional usado para correspondência com a declaração kid.

Como alternativa, forneça uma chave de descriptografia usando:

- certificate-id no formato <key certificate-id="mycertificate" /> para especificar o identificador de uma entidade de certificado carregada no Gerenciamento de API
No
emissores Uma lista de entidades aceitáveis que emitiram o token. Se vários valores de emissor estiverem presentes, cada valor será tentado até que todos sejam esgotados (nesse caso, a validação falhará) ou até obter êxito. No
openid-config O elemento usado para especificar um ponto de extremidade de configuração de Open ID em conformidade do qual chaves de assinatura e emissor podem ser obtidos. No
required-claims Contém uma lista de declarações cuja presença é esperada no token para que ele possa ser considerado válido. Quando o atributo match é definido como all, cada valor de declaração na política deve estar presente no token para que a validação seja bem-sucedida. Quando o atributo match é definido como any, pelo menos uma declaração deve estar presente no token para que a validação seja bem-sucedida. No

Atributos

Nome Descrição Obrigatório Padrão
clock-skew Período de tempo. Use para especificar a diferença de tempo máxima esperada entre os relógios do sistema do emissor do token e a instância do Gerenciamento de API. No 0 segundos
failed-validation-error-message Mensagem de erro para retornar no corpo da resposta HTTP se o JWT não passar na validação. Esta mensagem deve conter quaisquer caracteres especiais adequadamente seguidos por caracteres de escape. No A mensagem de erro padrão depende do problema de validação, por exemplo, "O JWT não está presente."
failed-validation-httpcode O código de status HTTP para retornar se o JWT não passar na validação. No 401
header-name O nome do cabeçalho HTTP contendo o token. É necessário especificar header-name, query-parameter-name ou token-value. N/D
nome do parâmetro de consulta O nome do parâmetro de consulta que contém o token. É necessário especificar header-name, query-parameter-name ou token-value. N/D
token-value Expressão que retorna uma cadeia de caracteres que contém o token JWT. Você não deve retornar Bearer como parte do valor do token. É necessário especificar header-name, query-parameter-name ou token-value. N/D
id O atributo id no elemento key permite que você especifique a cadeia de caracteres cuja correspondência será verificada em relação à declaração kid no token (se presente) para descobrir a chave apropriada a ser usada para validação de assinatura. Não N/D
match O atributo match no elemento claim especifica se todos os valores de declaração na política devem estar presentes no token para que a validação seja bem-sucedida. Os valores possíveis são:

- all – todos os valores de declaração na política devem estar presentes no token para que a validação seja bem-sucedida.

- any – pelo menos um valor de declaração na política deve estar presente no token para que a validação seja bem-sucedida.
No all
require-expiration-time Booliano. Especifica se uma declaração de expiração é necessária no token. No true
require-scheme O nome do esquema do token, por exemplo, "Portador". Quando esse atributo for definido, a política garantirá que o esquema especificado esteja presente no valor do cabeçalho de Autorização. Não N/D
require-signed-tokens Booliano. Especifica se é necessário que um determinado token seja assinado. No true
separator Cadeia de caracteres. Especifica um separador (por exemplo, ",") a ser usado para extrair um conjunto de valores de uma declaração com valores múltiplos. Não N/D
url URL ponto de extremidade de configuração de Open ID da qual é possível obter os metadados de configuração de Open ID. A resposta deve ser de acordo com as especificações definidas na URL:https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata. Para o Azure Active Directory, use a seguinte URL: https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration substituindo o seu nome de locatário do diretório, por exemplo, contoso.onmicrosoft.com. Sim N/D
output-token-variable-name Cadeia de caracteres. Nome da variável de contexto que receberá o valor de token como um objeto do tipo Jwt após a validação de token bem-sucedida Não N/D

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: de entrada
  • Escopos da política: todos os escopos

Validar um certificado de cliente

Use a política validate-client-certificate para impor que um certificado apresentado por um cliente a uma instância de Gerenciamento de API corresponda a regras de validação e declarações especificadas como assunto ou emissor para uma ou mais identidades de certificado.

Para ser considerado válido, um certificado de cliente deve corresponder a todas as regras de validação definidas pelos atributos no elemento de nível superior, e corresponder a todas as declarações definidas para pelo menos uma das identidades definidas.

Use essa política para verificar as propriedades do certificado de entrada em relação às propriedades desejadas. Além disso, use essa política para substituir a validação padrão de certificados de cliente nesses casos:

  • Se você carregou certificados de autoridade de certificação personalizados para validar solicitações do cliente para o gateway gerenciado
  • Se você configurou autoridades de certificação personalizadas para validar solicitações de cliente para um gateway autogerenciado

Para obter mais informações sobre certificados de autoridade de certificação personalizados e autoridades de certificação, consulte Como adicionar um certificado de autoridade de certificação personalizado no Gerenciamento de API do Azure.

Declaração de política

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

Exemplo

O exemplo a seguir valida um certificado de cliente para corresponder às regras de validação padrão da política e verifica se o assunto e o nome do emissor correspondem aos valores especificados.

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

Elementos

Elemento Descrição Obrigatório
validate-client-certificate Elemento raiz. Sim
identidades Contém uma lista de identidades com declarações definidas no certificado do cliente. Não

Atributos

Nome Descrição Obrigatório Padrão
validate-revocation  Booliano. Especifica se o certificado é validado com base na lista de revogação online.  não  True
validate-trust  Booliano. Especifica se a validação deve falhar caso a cadeia não possa ser criada com êxito para a AC confiável. não True
validate-not-before Booliano. Valida o valor em relação à hora atual. não  True
validate-not-after  Booliano. Valida o valor em relação à hora atual. não  True
ignore-error  Booliano. Especifica se a política deve prosseguir para o próximo manipulador ou pular para em erro após a validação com falha. não Falso
identidade Cadeia de caracteres. Combinação de valores de declaração de certificado que tornam o certificado válido. sim N/D
thumbprint Impressão digital do certificado. não N/D
serial-number Número de série do certificado. não N/D
common-name Nome comum do certificado (parte da cadeia de caracteres Assunto). não N/D
subject Cadeia de caracteres Assunto. Deve seguir o formato de Nome Diferenciado. não N/D
dns-name Valor da entrada dnsName dentro da declaração Nome Alternativo da Assunto. não N/D
issuer-subject Assunto do emissor. Deve seguir o formato de Nome Diferenciado. não N/D
issuer-thumbprint Impressão digital do emissor. não N/D
issuer-certificate-id Identificador da entidade de certificado existente que representa a chave pública do emissor. Mutuamente exclusivo com outros atributos do emissor. não N/D

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: de entrada
  • Escopos da política: todos os escopos

Próximas etapas

Para obter mais informações sobre como trabalhar com políticas, consulte: