JWT Validation

O JSON Web Token (JWT) é um padrão aberto (RFC 7519) que define uma forma compacta e autossuficiente para a transmissão segura de informações entre duas partes como um objeto JSON. A informação pode ser verificada e confiável porque há assinatura digital.

JWTs podem ser assinados usando um segredo (com o algoritmo HMAC) ou um par de chaves pública/privada usando RSA.

Para ler mais sobre isso, acesse: https://jwt.io/.

Generating a token

Antes de realizar a chamada para gerar o token JWT, é necessário fazermos uma chamada para gerar o Authorization Code. Para saber como gerá-lo, clique aqui.

Para utilizar o interceptor JWT, é necessário que uma app esteja criada, pois assim temos acesso ao client ID e ao client secret.

Para gerar o JWT, é necessário fazer uma requisição POST para o endpoint <url do gateway>/oauth/access-token.

O cabeçalho (header) deve conter as seguintes informações:

Authorization : Basic client_id:client_secret

Esse client_id:client_secret deve ser uma string convertida em Base64, usando os dados da app criada.

Aqui está um exemplo do cabeçalho com client ID e secret convertidos para Base64:

Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==

No corpo (body), devemos passar o código (code) gerado pelo endpoint de grant-code, com mais alguns itens, no formato x-www-form-urlencoded:

"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer"
"code" : "8748d39f-1d4f-311f-92c6-4b279db1b317"

Além de gerar um JWT, também é possível criar um token criptografado utilizando o padrão JWE (JSON Web Encryption). Para saber como gerar um JWE e proteger o conteúdo do token com criptografia, consulte o tópico JWE (JSON Web Encryption).

Por fim, o access token será gerado novamente e deverá aparecer conforme o exemplo abaixo:

{
  "access_token": "ca81cb16-43e4-3e96-aaea-4861e7791dc7",
  "refresh_token": "677b881a-d0b6-3b29-b9a8-f0cdb50ce035",
  "token_type": "access_token",
  "expires_in": 3600
}

Se sua API retornar o status code 401 Unauthorized ao utilizar este interceptor, a chave pode estar inválida. Veja mais detalhes nesta página de nossas FAQs.

Fluxo

Este interceptor pode ser inserido apenas no fluxo de requisição e contém duas informações obrigatórias a serem configuradas: localização (location) e nome (name).

As opções de localização são:

Query Param: valida a existência de um JWT passado via query param.
- A propriedade "Name" define o nome do query param esperado.
Header: valida um JWT passado via cabeçalho.
- A propriedade "Name" define o nome do header esperado.
Default JWT Header: valida um JWT passado via cabeçalho.
- Para esta opção, não existe a propriedade "Name"; neste caso, o JWT é esperado no header Authorization.

JWE (JSON Web Encryption)

Como mencionamos no início desta página, o JWT é um padrão que permite a transmissão de tokens de uma parte a outra com segurança quanto à legitimidade do token passado. É bastante comum que se utilize esse padrão para enviar outras informações adicionais, por meio de claims.

Entretanto, é importante que se esteja atento a um aspecto do JWT: ele é um padrão que garante a confiabilidade dos dados, mas não sua confidencialidade. Informações sensíveis passadas no corpo do token podem ser interceptadas e expostas.

O JWE (JSON Web Encryption) adiciona uma camada extra de segurança ao token, realizando a criptografia dos dados transmitidos. Dessa forma, é possível expandir a funcionalidade JWT para que, além de garantir autenticidade e integridade, também assegure a confidencialidade das informações trafegadas.

Opção Use JWE-JSON Web Encryption

Quando a opção Use JWE-JSON Web Encryption está ativada, o token criptografado na requisição é validado, descriptografado e então repassado ao backend. Esse processo garante que apenas os sistemas autorizados possam acessar o conteúdo do token, reforçando a segurança de ponta a ponta na comunicação entre as partes.

Requisitos para execução do fluxo

Para realizar o fluxo corretamente, é necessário:

Possuir API com interceptors OAuth, configurado para JWT e JWT Validation interceptor, com a funcionalidade JWE-JSON Web Encryption ativada.
Ter uma App associada à API.
Ter um Plan relacionado à API.

Certifique-se de que a API OAuth 2.0 esteja disponível em seu ambiente. Caso contrário, será necessário criá-la antes de seguir.

Os próximos passos dependem dos requisitos acima. Garanta que todos estejam concluídos antes de prosseguir.

Gerando o JWE

O processo de geração do JWE envolve duas etapas principais:

Gerar o grant code;
Gerar o JWE propriamente dito.

1. Gerar grant code

A geração de um grant code é uma etapa essencial para criar o JWE.

Efetue uma requisição POST para a rota /oauth/grant-code da API OAuth, conforme o exemplo abaixo:

Request

curl --location '<gateway_url>/oauth/grant-code' \
--header 'Content-Type: application/json' \
--data '{
  "client_id": "<app_client_id>",
  "extraInfo": {},
  "redirect_uri": "http://localhost/",
  "state": "string"
}'

Substitua:

Substitua <app_client_id> pelo valor do client_id da sua aplicação.
Substitua <redirect_url> pela URL de redirecionamento desejada.
Substitua <gateway_url> pelo endereço do gateway do seu ambiente.

Response

{
  "redirect_uri": "http://localhost/?state=string&code=**40a7848a-2615-49ba-ae27-cff175095c16**"
}

Após efetuar a requisição, será retornada uma resposta com a "redirect_uri".

Copie o valor de "code" retornado, pois ele será usado na próxima etapa.

A API deve conter um interceptor OAuth com a opção JWT marcada. Caso contrário, ocorrerá um bad request com a mensagem informando que o grant type é inválido.

Exemplo de retorno

{
    "result": "failure",
    "errors": [
        {
            "type": "INVALID",
            "message": "grand_type!"
        }
    ],
    "status": 400
}

2. Gerar JWE

Com o code obtido, é hora de gerar o JWE. Veja o exemplo de requisição abaixo.

Request

curl --location 'https://<gateway_url>/oauth/access-token' \
--header 'Authorization: Basic NmM5MWUwNDQtYTJkMS00ZmFiLTkwYjgtMWRhNmMwZDc2YWMzOjI5Y2I4ODE1LWM2ODEtNGIwZC04Yzc2LTg2NzdmMzFlODY2Yg==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
--data-urlencode 'code=40a7848a-2615-49ba-ae27-cff175095c16' \
--data-urlencode 'encrypt=true'

O parâmetro encrypt=true é obrigatório para que o token seja gerado no formato JWE (JSON Web Encryption). Sem esse parâmetro, o token será emitido como um JWT, sem criptografia, o que expõe as informações no payload.

No exemplo acima:

O parâmetro code deve conter o valor obtido na etapa anterior.
O parâmetro encrypt=true indica que o token está sendo trafegado com JWE – JSON Web Encryption habilitado.

Adapte o exemplo conforme necessário:

Inclua o header Authorization com o código Base64 da sua App;
Insira o code obtido anteriormente;
Adicione o parâmetro encrypt=true;
Substitua <gateway_url> pelo endereço do gateway do seu ambiente.

A requisição deve seguir no formato x-www-form-urlencoded.

Response

{
  "access_token": "eyJleHAiOjE3NTUyODAxMzIyNDEsImFsZyI6ImRpciIsImVuYyI6IkExMjhHQ00ifQ..6r0yEMyxMrCutmGq.ywwIieYyG79S5G1ZEk1V9HDrYyvNknP_G1u4Wpzw3yW3-FAJT-oHuQUIRGVpqXtphOyEKaw-WNUhZYsasnX6o_Ju8uRLjEPVdeVa8y4SXU1c8wBWXe1jD9GK-TogVPAaaHrHq4q-iUL-gZJiOzsoCm0li3LgwjZPUq8A7RIcWUDSfsSZobow5Hi8xpn16L6V4iCcUZ-UA6hywS_UeR2J7uUPzj8273w8kAXvyWkWqrFnDf7Dv6T7vAY69vI3ZfBUgUquDD38V7gsmGuG6vSdcSRqKCYTvVgGCxbwPARJFxLw3rXE76R1F6GVmzmrSJQCtrcajNH5X_ZJnI9c12mnBGWwKtj8UjsJlsVBn4EAzWtxX6Fl-kXubclS1RW_VtcKXBd_yzBRCKUksR8QoHET2wDKSPJl9hg0-6g9xhvrSo-aVVo4FZkBQoBmAv7FN3C0CNwWJ5nId2mTnwckdAmHWqLpqq3rwcED42pLvy3pnYz4LHU5FZHQrk1Z0kExaVY_YOYJvN6fV-Whc5fSyG82B0R2AQ36AzxQq1-Fcqy9Xw.Ah69e5r8RS1MBqaJgS61wQ",
  "token_type": "access_token",
  "expires_in": null
}

Copie o valor do campo access_token. Esse valor corresponde ao seu JWE.

O uso do JWE segue o mesmo padrão do JWT. Para mais detalhes, consulte o tópico JWT (JSON Web Token).

Validando o fluxo JWE (opcional)

Para validar que o token foi realmente criptografado, você pode utilizar o JWT Debugger.

Será possível observar que o conteúdo do token não pode ser lido, confirmando a aplicação da criptografia.

Para validar o funcionamento da opção Use JWE-JSON Web Encryption:

Faça uma requisição para a sua API, informando o client_id da sua App e o access_token (JWE) gerado.
No campo destination da API, utilize um mock que permita visualizar o recebimento do access_token já descriptografado — como o Supermock Sensedia, por exemplo.

Exemplo de requisição

curl --location 'https://api-sensediaqa1.sensedia-eng.com/jwt' \
--header 'client_id: 6c91e044-a2d1-4fab-90b8-1da6c0d76ac3' \
--header 'access_token: eyJleHAiOjE3NTUyODAxMzIyNDEsImFsZyI6ImRpciIsImVuYyI6IkExMjhHQ00ifQ..6r0yEMyxMrCutmGq.ywwIieYyG79S5G1ZEk1V9HDrYyvNknP_G1u4Wpzw3yW3-FAJT-oHuQUIRGVpqXtphOyEKaw-WNUhZYsasnX6o_Ju8uRLjEPVdeVa8y4SXU1c8wBWXe1jD9GK-TogVPAaaHrHq4q-iUL-gZJiOzsoCm0li3LgwjZPUq8A7RIcWUDSfsSZobow5Hi8xpn16L6V4iCcUZ-UA6hywS_UeR2J7uUPzj8273w8kAXvyWkWqrFnDf7Dv6T7vAY69vI3ZfBUgUquDD38V7gsmGuG6vSdcSRqKCYTvVgGCxbwPARJFxLw3rXE76R1F6GVmzmrSJQCtrcajNH5X_ZJnI9c12mnBGWwKtj8UjsJlsVBn4EAzWtxX6Fl-kXubclS1RW_VtcKXBd_yzBRCKUksR8QoHET2wDKSPJl9hg0-6g9xhvrSo-aVVo4FZkBQoBmAv7FN3C0CNwWJ5nId2mTnwckdAmHWqLpqq3rwcED42pLvy3pnYz4LHU5FZHQrk1Z0kExaVY_YOYJvN6fV-Whc5fSyG82B0R2AQ36AzxQq1-Fcqy9Xw.Ah69e5r8RS1MBqaJgS61wQ'

Após a execução, o backend receberá o token já descriptografado, e será possível validar o fluxo completo da feature Use JWE-JSON Web Encryption.

Exemplo de response (parcial)

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJhcGktYXV0aG9yaXphdGlvbi5zaGFyZWQuc3ZjLmNsdXN0ZXIubG9jYWwiLCJpc3MiOiIxMC4xMzUuNTAuODUiLCJqdGkiOiI0N2UxM2Q3Mi05OGQ1LTRhOGQtODgzYi05NzFkMDgxYmQ0OTIiLCJzdWIiOiI2YzkxZTA0NC1hMmQxLTRmYWItOTBiOC0xZGE2YzBkNzZhYzMiLCJleHAiOjAsImlhdCI6MTc1NTI4MDEzMiwiQXBwOiAiOiJBcHAiLCJDb2RlOiAiOiI0MGE3ODQ4YS0yNjE1LTQ5YmEtYWUyNy1jZmYxNzUwOTVjMTYifQ.xJ7YfU_v0mb4ZTMmglPcj5g5zuJbDlFZnRoE-e8AplM",
    "token_type": "access_token",
    "expires_in": null
}

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]