Validar JWT

Editar online

Use a política de segurança Validar JWT para ativar a validação de um JSON Web Token (JWT) em uma solicitação antes de permitir acesso às APIs.

Suporte de gateway

Tabela 1. Tabela que mostra quais gateways suportam esta política e a versão correspondente da política
Gateway	Versão da política
DataPower® Gateway (v5 compatible)	1.0.0
DataPower API Gateway	2.0.0

Este tópico descreve como configurar a política na interface de usuário do assembly; para obter detalhes sobre como configurar a política na sua fonte do OpenAPI, consulte jwt-validate.

Sobre

O JSON Web Token (JWT) é um meio compacto e protegido por URL de representar solicitações que devem ser transferidas entre duas partes. A política Validar JWT permite proteger o acesso a suas APIs usando a validação do JWT. Por exemplo, quando uma solicitação de entrada que contém um JWT no cabeçalho é recebida, a política Validar JWT extrai o token, verifica e decriptografa (se apropriado) a assinatura e valida a solicitação. Se válida, a solicitação é colocada em uma variável de tempo de execução (para uso subsequente, se necessário) e o acesso é permitido para a API. Se a solicitação não for válida, o acesso será negado.

Todas as solicitações especificadas na política Validar JWT são validadas, mas isso não é necessariamente todas as solicitações contidas no JWT. Nem todas as solicitações que estão no JWT devem ser validadas, mas se qualquer uma das solicitações especificadas na política Validar JWT falhar, a validação inteira falhará. Se a validação for bem-sucedida, o conjunto integral de solicitações contidas no JWT será gravado na variável de tempo de execução especificada na propriedade Output Claims. Dessa maneira, isso permite que qualquer ação subsequente para usar essa variável de tempo de execução valide adicionalmente o conjunto integral de solicitações que estavam no JWT, conforme necessário.

Nota:

Se a mensagem original foi assinada com uma Chave secreta compartilhada, o objeto criptográfico especificado também deverá ser uma Chave secreta compartilhada.
Se a mensagem original foi assinada com uma Chave privada, o objeto criptográfico especificado deverá ser um Certificado criptográfico (certificado público).
O material criptográfico pode ser fornecido por meio de um JSON Web Key (JWK).
Se um parâmetro de cabeçalho JWK estiver incluído no cabeçalho do JWT, o parâmetro deverá corresponder ao JWK ou objeto criptográfico especificado na política, ou a validação JWT falhará.
Se um objeto criptográfico e um JWK forem ambos especificados, o objeto criptográfico será usado para decriptografar ou verificar o JWT.
A ação de validação do JWT no DataPower API Gateway pode verificar um JWT usando um único JWK ou um conjunto de JWK

Pré-requisitos

Os seguintes pré-requisitos se aplicam:

IBM® DataPower V7.5 com a opção de Otimização de Aplicativos (AO).
Se você estiver usando um ou mais objetos criptográficos (objetos de criptografia), eles devem estar localizados no IBM API Connect domínio do dispositivo DataPower. Os objetos criptográficos devem referenciar a Chave secreta compartilhada ou o certificado público que é necessário para decriptografar o conteúdo JWT ou verificar a assinatura.
Se um JSON Web Key (JWK) ou conjunto JWK estiver sendo usado, ele deverá ser referenciado por uma variável de tempo de execução.

Propriedades

A tabela a seguir lista as propriedades de política, indica se uma propriedade é necessária, especifica os valores válidos e padrão para entrada e especifica o tipo de dados dos valores.

Tabela 2. Validar as propriedades da política JWT
Rótulo da propriedade	Obrigatório	Descrição	Tipo de dados
Título	True	O título da política. O valor padrão é `jwt-validate`.	sequência
Descrição	Não	Uma descrição da política.	sequência
JSON Web Token (JWT)	True	A variável de contexto ou de tempo de execução que contém o JWT a ser validado. O valor padrão é: `request.headers.authorization`. No entanto, se essa propriedade não for configurada, a política procurará o JWT no local `request.headers.authorization` por padrão. Nota: O formato do cabeçalho de autorização deve ser: `"Authorization: Bearer jwt-token"` em que `jwt-token` é o JWT codificado.	sequência
Solicitações de saída	True	A variável de tempo de execução à qual o conjunto integral de solicitações contidas no JWT está designado. O valor padrão é: `decoded.claims`.	sequência
Solicitação do emissor	Não	O Perl Compatible Regular Expressions (PCRE) para usar para validar a solicitação do Emissor (iss).	sequência
Solicitação do público	Não	O PCRE a ser usado par validar a solicitação do Público (aud).	sequência
Decriptografar objeto criptográfico	Não	O objeto criptográfico (uma chave compartilhada ou um certificado) a ser usado para decodificar a reivindicação^{^.1}	sequência
Decriptografar o nome de variável do JWK criptográfico	Não	Variável de tempo de execução que contém a chave JWK a ser usada para descriptografar o JWT. ^¹	sequência
Verificar o objeto criptográfico	Não	O objeto criptográfico (uma chave compartilhada ou um certificado) a ser usado para verificar a assinatura. ^²	sequência
Verificar o nome de variável do JWK criptográfico	Não	Variável de tempo de execução que contém a chave JWK, ou conjunto de chaves JWK, a ser usada para verificar a assinatura. ^²	sequência

Exemplo

- jwt-validate:
    version: 1.0.0
    title: jwt-validate
    jwt: request.headers.authorization
    output-claims: decoded.claims
    iss-claim: "'^data.*'"
    aud-claim: "'^id.*'"
    jwe-crypto: jweCryptoObjectName
    jwe-jwk: jwe.jwk
    jws-crypto: jwsCryptoObjectName
    jws-jwk: jws.jwk

Erros

O seguinte erro pode ser lançado enquanto a política está sendo executada:

RuntimeError - um erro genérico que captura todos os erros que ocorrem durante a execução da política. Após uma falha de validação, a mensagem de erro detalhada recebida do módulo JOSE subjacente é gravada no log do sistema padrão como uma mensagem de erro. Essa mensagem de erro detalhada também é designada à variável de tempo de execução jwt-validate.error-message, portanto, pode ser recuperada por meio de captura.

Se uma captura não estiver configurada, no caso de uma falha de validação, a política Validate JWT retornará um código HTTP 500 Invalid-JWT-Validate failure. A mensagem de erro detalhada do módulo JOSE subjacente pode ser localizada no log do sistema.

Atenção: se você for um desenvolvedor de API que está solucionando uma falha que um de seus clientes teve com sua API, considere os riscos de segurança antes de enviar a um cliente o conteúdo exato da mensagem de log. É possível evitar a possibilidade de um ataque baseado em informações recebidas sobre a mensagem de log enviando ao cliente somente informações gerais sobre a mensagem.

Para ver exemplos, consulte o jwt-validate.

¹ Um JWK e um Objeto criptográfico são ambas maneiras válidas de fornecer os dados criptográficos necessários para decriptografar o JWT. Entretanto, se ambos os tipos de dados forem especificados, somente o Objeto criptográfico será usado. Se você estiver usando um ou mais objetos criptográficos (objetos de criptografia), eles devem estar localizados no IBM API Connect domínio do dispositivo DataPower. Os objetos criptográficos devem referenciar a Chave secreta compartilhada ou o certificado público que é necessário para decriptografar o conteúdo JWT ou verificar a assinatura.

² Um conjunto JWK ou JWK e um Objeto Crypto são ambas maneiras válidas de fornecer os dados criptográficos necessários para verificar o JWT. Entretanto, se ambos os tipos de dados forem especificados, somente o Objeto criptográfico será usado.