Compartilhar via

Validar JWT

  • Artigo

APLICA-SE A: todas as camadas do Gerenciamento de API

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

Observação

Para validar um JWT fornecido pelo serviço Microsoft Entra, o Gerenciamento de API também fornece a política validate-azure-ad-token.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Para ajudá-lo a configurar essa política, o portal fornece um editor guiado baseado em formulário. Saiba mais sobre como definir e editar as 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" />
  <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 Obrigatório Padrão
header-name O nome do cabeçalho HTTP contendo o token. Expressões de política são permitidas. É 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. Expressões de política são permitidas. É 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. Você não deve retornar Bearer como parte do valor do token. Expressões de política são permitidas. É necessário especificar header-name, query-parameter-name ou token-value. N/D
failed-validation-httpcode O código de status HTTP para retornar se o JWT não passar na validação. Expressões de política são permitidas. Não 401
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. Expressões de política são permitidas. Não A mensagem de erro padrão depende do problema de validação, por exemplo, "O JWT não está presente."
require-expiration-time Booliano. Especifica se uma declaração de expiração é necessária no token. Expressões de política são permitidas. Não 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. Expressões de política são permitidas. No N/D
require-signed-tokens Booliano. Especifica se é necessário que um determinado token seja assinado. Expressões de política são permitidas. Não true
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. Expressões de política são permitidas. Não 0 segundos
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. Expressões de política não são permitidas. Não N/D

Elementos

Elemento Descrição Obrigatório
openid-config Adicionar um ou mais desses elementos para especificar um URL de ponto de extremidade de configuração do OpenID em conformidade do qual as chaves e o emissor de assinatura podem ser obtidos.

A configuração incluindo o JWKS (Conjunto de Chaves Web JSON) é extraída do ponto de extremidade a cada 1 hora e armazenada em cache. Se o token que está sendo validado fizer referência a uma chave de validação (usando declaração kid) que está ausente na configuração armazenada em cache ou se a recuperação falhar, o Gerenciamento de API efetua pull do ponto de extremidade no máximo uma vez a cada 5 minutos. Esses intervalos estão sujeitos a alterações sem aviso prévio.

A resposta deve estar de acordo com as especificações definidas na URL: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.

Para o Microsoft Entra ID, use o ponto de extremidade de metadados do OpenID Connect configurado no registro do aplicativo, como:
- v2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
- Multilocatário v2 https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
- v1 https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration
- Locatário do cliente (versão prévia) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration

Substituir o nome ou a ID do locatário do diretório, por exemplo, contoso.onmicrosoft.com por {tenant-name}.		 No
issuer-signing-keys Uma lista de chaves de segurança codificadas em Base64, em subelementos key, 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).

Opcionalmente, especifique uma chave usando o atributo id para corresponder à declaração kid do token. Para validar um token assinado com uma chave assimétrica, especifique opcionalmente a chave pública usando um atributo certificate-id com o valor definido para o identificador de um certificado carregado no API Management ou o módulo RSA n e o par e de expoentes da chave de assinatura no formato codificado em Base64url.		 Não
decryption-keys Uma lista de chaves codificadas em Base64, em subelementos key, 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.

Para descriptografar um token criptografado com uma chave assimétrica, especifique opcionalmente a chave pública usando um atributo certificate-id com valor definido como o identificador de um certificado carregado no Gerenciamento de API.		 Não
públicos-alvo Uma lista de declarações de público-alvo aceitáveis, em subelementos audience, 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
emissores Uma lista de entidades aceitáveis, em subelementos issuer, 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
required-claims Uma lista de declarações, em subelementos claim, cuja presença é esperada no token para que ele possa ser considerado válido. Quando várias declarações estão presentes, o token deve corresponder aos valores de declaração de acordo com o valor do atributo match. Não

Atributos de chave

Atributo Descrição Obrigatório Padrão
ID (Somente chave de assinatura do emissor) Cadeia de caracteres. Identificador usado para corresponder kid à declaração apresentada no JWT. Se nenhuma chave corresponder à declaração, o Gerenciamento de API tentará cada chave especificada. Saiba mais sobre a declaração de kid no RFC. Não N/D
ID do certificado Identificador de uma entidade de certificado carregada no API Management, usada para especificar a chave pública para verificar um token assinado com uma chave assimétrica. Não N/D
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/D
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/D

atributos de declaração

Atributo Descrição Obrigatório Padrão
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
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

Uso

Observações de uso

  • 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 dá suporte a algoritmos de assinatura simétricos e assimétricos:
    • Simétrico– há suporte para os seguintes algoritmos de criptografia: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
      • Se for usada na política, a chave deverá ser fornecida em linha na política no formato codificado em Base64.
    • Assimétrico - Há suporte para os seguintes algoritmos de criptografia: PS256, RS256, RS512, ES256.
      • Se usada na política, a chave poderá ser fornecida por meio de um ponto de extremidade de configuração do OpenID ou fornecendo a ID de um certificado carregado (no formato PFX) que contenha a chave pública ou o par módulo-expoente da chave pública.
  • Para configurar a política com um ou mais pontos de extremidade de configuração do OpenID para uso com um gateway auto-hospedado, as URLs de pontos de extremidade de configuração do OpenID também devem ser acessíveis pelo gateway de nuvem.
  • 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 Microsoft Entra aplicando a política validate-jwt no nível da API ou pode aplicá-la no nível de operação da API e usar claims para um controle mais granular.
  • Ao usar um cabeçalho personalizado (header-name), o esquema obrigatório configurado (require-scheme) será ignorado. Para usar um esquema necessário, os tokens JWT devem ser fornecidos no cabeçalho Authorization.

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 do token de locatário único do 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://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 do token de locatário do cliente do 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>

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>11112222-bbbb-3333-cccc-4444dddd5555</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 validate-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>

Conteúdo relacionado

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