Partilhar via

Validar JWT

APLICA-SE A: Todas as camadas de gerenciamento de API

A validate-jwt política garante a existência e validade de um token web JSON suportado (JWT) fornecido por um fornecedor de identidade. O JWT pode ser extraído de um cabeçalho HTTP especificado, extraído de um parâmetro de consulta especificado ou correspondente a um valor específico.

Nota

Use a política validate-azure-ad-token para validar um JWT fornecido por Microsoft Entra.

Nota

Defina os elementos da política e os elementos filho na ordem fornecida na declaração de política. Para ajudá-lo a configurar essa política, o portal fornece um editor guiado baseado em formulários. Saiba mais sobre como definir ou editar políticas de Gerenciamento de API.

Declaração de política

<validate-jwt
    header-name="name of HTTP header containing the token (alternatively, use query-parameter-name or token-value attribute to specify token)"
    query-parameter-name="name of query parameter used to pass the token (alternative, use header-name or token-value attribute to specify token)"
    token-value="expression returning the token as a string (alternatively, use header-name or query-parameter attribute to specify token)"
    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"
    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, for example, https://login.constoso.com/openid-configuration" validate-connectivity="true | false"/>
  <issuer-signing-keys>
    <key id="kid-claim" certificate-id="mycertificate" n="modulus" e="exponent">Base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key certificate-id="mycertificate">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 value, then add additional value elements -->
    </claim>
    <!-- if there are multiple possible allowed claim, then add additional claim elements -->
  </required-claims>
</validate-jwt>

Atributos

Atributo Descrição Necessário Predefinição
nome do cabeçalho O nome do cabeçalho HTTP que contém o token. São permitidas expressões de política. Um dos header-name, query-parameter-name ou token-value deve ser especificado. N/A
query-nome-parâmetro O nome do parâmetro de consulta que contém o token. São permitidas expressões de política. Um dos header-name, query-parameter-name ou token-value deve ser especificado. N/A
valor do token Expressão que retorna uma cadeia de caracteres que contém o token. Não deve devolver Bearer como parte do valor do token. São permitidas expressões de política. Um dos header-name, query-parameter-name ou token-value deve ser especificado. N/A
failed-validation-httpcode Código de status HTTP para retornar se o JWT não passar na validação. São permitidas expressões de política. Não 401
falha-validação-erro-mensagem Mensagem de erro para retornar no corpo da resposta HTTP se o JWT não passar na validação. Esta mensagem deve ter todos os caracteres especiais escapados corretamente. São permitidas expressões de política. Não A mensagem de erro padrão depende do problema de validação, por exemplo, "JWT não está presente".
exigir-expiração-tempo Booleano. Especifica se uma declaração de expiração é necessária no token. São permitidas expressões de política. Não verdadeiro
require-regime O nome do esquema de token, por exemplo, "Portador". Quando esse atributo for definido, a política garantirá que o esquema especificado esteja presente no valor do cabeçalho Authorization. São permitidas expressões de política. Não N/A
require-signed-tokens Booleano. Especifica se um token precisa ser assinado. São permitidas expressões de política. Não verdadeiro
distorção do relógio Intervalo 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 de Gerenciamento de API. São permitidas expressões de política. Não 0 segundos
output-token-variable-name Cadeia Nome da variável de contexto que receberá o valor do token como objeto do tipo Jwt após validação bem-sucedida do token. Expressões de política não são permitidas. Não N/A

Elementos

Elemento Descrição Necessário
openid-config Adicione um ou mais destes elementos para especificar um endpoint de configuração OpenID compatível (url atributo) de onde se possam obter as chaves de assinatura e o emissor.

Opcionalmente, defina validate-connectivity o atributo para false desativar a verificação da disponibilidade do endpoint se a URL não puder ser resolvida via DNS público.

A configuração, incluindo o JSON Web Key set (JWKS), é extraída do ponto de extremidade a cada 1 hora e armazenada em cache. Se o token a validar referenciar uma chave de validação (usando kid a reivindicação) que está em falta na configuração em cache, ou se a recuperação falhar, a Gestão da API retira do endpoint no máximo uma vez a cada 5 minutos. Estes intervalos estão sujeitos a alterações sem aviso prévio.

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 Microsoft Entra ID utilize o endpoint de metadados OpenID Connect configurado no registo da sua aplicação, tais como:
- v2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
- v2 Multi-Inquilino https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
- v1 https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration
- Inquilino cliente (pré-visualização) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration

Substituindo o nome ou ID do seu inquilino de diretório, por contoso.onmicrosoft.comexemplo , por {tenant-name}.		 Não
chaves de assinatura do emissor Uma lista de chaves de segurança codificadas em Base64, em key subelementos, usadas para validar tokens assinados. Se várias chaves de segurança estiverem presentes, cada chave será tentada até que todas se esgotem (caso em que a validação falha) ou uma seja bem-sucedida (útil para a substituição de tokens).

Opcionalmente, especifique uma chave usando o id atributo para corresponder à reivindicação do kid token. Para validar um token assinado com uma chave assimétrica, especifique opcionalmente a chave pública usando um certificate-id atributo com valor definido como o identificador de um certificado carregado para a API Management, ou o par de módulo n RSA e expoente e da chave de assinatura no formato codificado Base64url.		 Não
chaves de desencriptação Uma lista de chaves codificadas em Base64, em key subelementos, usadas para desencriptar os tokens. Se várias chaves de segurança estiverem presentes, cada chave será tentada até que todas as chaves se esgotem (caso em que a validação falha) ou uma chave seja bem-sucedida.

Para desencriptar um token encriptado com uma chave assimétrica, especifique opcionalmente a chave pública usando um certificate-id atributo com valor definido como identificador de um certificado carregado para a API Management.		 Não
Audiências Uma lista de reivindicações de audiência aceitáveis, em audience subelementos, que podem estar presentes no token. Se vários valores de audiência estiverem presentes, cada valor será tentado até que todos estejam esgotados (caso em que a validação falhará) ou até que um seja bem-sucedido. Pelo menos um público deve ser especificado. Não
emitentes Uma lista de princípios aceitáveis, em issuer subelementos, que emitiram o token. Se vários valores do emissor estiverem presentes, cada valor será tentado até que todos estejam esgotados (caso em que a validação falhará) ou até que um seja bem-sucedido. Não
reclamações-obrigatórias Uma lista de reivindicações, em claim subelementos, que se espera que estejam presentes no token para que este seja considerado válido. Quando há múltiplas reivindicações presentes, o token deve corresponder aos valores das reivindicações de acordo com o valor do match atributo. Não

atributos-chave

Atributo Descrição Necessário Predefinição
ID (Somente chave de assinatura do emissor) String. Identificador usado para corresponder kid à reivindicação apresentada no JWT. Se nenhuma chave corresponder à declaração, o Gerenciamento de API tentará cada chave especificada. Saiba mais sobre a kid reivindicação no RFC. Não N/A
ID do certificado Identificador de uma entidade certificada carregada para a API Management, usada para especificar a chave pública para verificar um token assinado com uma chave assimétrica. Não N/A
n (Somente chave de assinatura do emissor) Módulo da chave pública usada para verificar o emissor de um token assinado com uma chave assimétrica. Deve ser especificado com o valor do expoente e. Expressões de política não são permitidas. Não N/A
e (Somente chave de assinatura do emissor) Expoente da chave pública usada para verificar o emissor de um token assinado com uma chave assimétrica. Deve ser especificado com o valor do módulo n. Expressões de política não são permitidas. Não N/A

atributos de declaração

Atributo Descrição Necessário Predefinição
Jogo O match atributo no claim elemento especifica se cada valor de reivindicação na apólice deve estar presente no token para que a validação tenha sucesso. Os valores possíveis são:

- all - cada valor de reivindicação na apólice deve estar presente no token para que a validação tenha sucesso.

- any - pelo menos um valor de reivindicação deve estar presente no token para que a validação tenha sucesso.		 Não todos
separador Cadeia Especifica um separador (por exemplo, ",") a ser usado para extrair um conjunto de valores de uma declaração de vários valores. Não N/A

Utilização

Notas de utilização

  • A validate-jwt apólice exige que a reivindicação exp registada esteja incluída no JWT, a menos que require-expiration-time o atributo seja especificado e definido para false.
  • A política suporta algoritmos de assinatura simétricos e assimétricos:
    • Simétrico - São suportados os seguintes algoritmos de encriptação: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
      • Se usada na política, a chave deve ser fornecida embutida dentro da política no formulário codificado em Base64.
    • Assimétrico - São suportados os seguintes algoritmos de encriptação: PS256, RS256, RS512, ES256.
      • Se usada na política, a chave pode ser fornecida por meio de um ponto de extremidade de configuração OpenID ou fornecendo a ID de um certificado carregado (no formato PFX) que contém a chave pública ou o par módulo-expoente da chave pública.
  • Se a instância de Gestão de API for injetada ou integrada numa rede virtual e openid-config as URLs dos endpoints forem configuradas na política, defina o validate-connectivity atributo para false desativar a verificação da disponibilidade do endpoint.
  • Pode utilizar políticas de restrição de acesso em diferentes âmbitos para diferentes finalidades. Por exemplo, pode proteger toda a API com autenticação Microsoft Entra aplicando a política validate-jwt ao nível da API, ou pode aplicá-la ao nível operacional da API e usar claims para controlo mais detalhado.
  • Ao usar um cabeçalho personalizado (header-name), o esquema necessário configurado (require-scheme) será ignorado. Para usar um esquema obrigatório, os JWTs devem ser fornecidos no Authorization cabeçalho.

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>

Microsoft Entra ID validação de token de inquilino único

<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>00001111-aaaa-2222-bbbb-3333cccc4444</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Validação de token de cliente Microsoft Entra ID

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
	<openid-config url="https://<tenant-name>.ciamlogin.com/<tenant-id>/v2.0/.well-known/openid-configuration" />
	<required-claims>
		<claim name="azp" match="all">
			<value>insert claim here</value>
		</claim>
	</required-claims>
</validate-jwt>

Azure Active Directory Validação de tokens 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>11112222-bbbb-3333-cccc-4444dddd5555</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Importante

A partir de 1 de maio de 2025, o Azure AD B2C deixará de estar disponível para compra para novos clientes. Saiba mais nas nossas Perguntas Frequentes.

Validação de token usando chave de desencriptação

Este exemplo mostra como usar a validate-jwt política para validar um token que é desencriptado usando uma chave de desencriptação. A chave é especificada usando a ID de um certificado carregado (no formato PFX) que contém a chave pública.

<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>
    <decryption-keys>
        <key certificate-id="my-certificate-in-api-management" /> <!-- decryption key specified as certificate ID -->
    </decryption-keys>
</validate-jwt>

Autorizar o acesso a operações com base em declarações de token

Este exemplo mostra como usar a validate-jwt política para autorizar o acesso a operações com base no valor das reivindicações do 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>

Conteúdos relacionados

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

  • Last updated on