Como depurar tokens JSON da Web (JWTs)

Muitas aplicações web modernas, tanto do lado do cliente quanto do lado do servidor, utilizam JSON Web Tokens (JWTs) para autenticação, o que é uma excelente abordagem. No entanto, quando algo dá errado, pode ser complicado descobrir o motivo.

Esta publicação tem como objetivo apresentar algumas dicas para entender e corrigir problemas relacionados a JWTs. Se você está apenas começando, confira a documentação sobre como trabalhar com JWTs e nossas APIs primeiro.

Seu JSON Web Token parece plausível?

Às vezes, o problema é tão simples quanto saber se você passou o valor certo no lugar certo — o equivalente à pergunta “está conectado?”.

Então, adicione um pouco de depuração ao seu código para exibir o JWT em algum lugar onde você possa vê-lo, como no seu log de erros ou no console.

Então, verifique o seguinte:

• Isso parece um token? Deveria ser composto por três conjuntos de sequências alfanuméricas que parecem confusas (tecnicamente, caracteres maiúsculos e minúsculos, dígitos numéricos, + e / são permitidos, com = usado para preenchimento), separados por pontos.

• Há espaços em branco ao redor, incluindo uma quebra de linha no final? Espaços em branco indesejados e espalhados podem causar problemas em algumas ferramentas.

• Será que isso existe mesmo? Digitei errado o nome de uma variável e gerei o token de novo algumas vezes antes de perceber que o problema sou eu, e não o token.

Se o token passar na inspeção visual, precisaremos utilizar algumas ferramentas mais específicas.

Verifique o JSON Web Token em jwt.io

Existe uma excelente ferramenta de depuração de JWT (obrigado, Auth0!) que pode nos ajudar a entender quando as coisas não estão saindo como esperávamos.

Cole seu JWT no painel à esquerda e, se ele for analisado, os detalhes das três seções serão exibidos no lado direito.

A primeira seção é o cabeçalho, que mostra o tipo e o algoritmo utilizados. Para assinar chamadas da API da Vonage, isso geralmente será typ de JWT e alg de RS256 (os JWTs na webhooks assinados da Messages API são HS256).

A seção do meio contém a maior parte dos dados propriamente ditos. Há alguns campos esperados aqui para chamadas à API da Vonage com JWTs:

• iat significa “emitido em” e deve ser um timestamp do UNIX

• exp é o “tempo de validade” e também é um timestamp do UNIX

• jti significa “JWT ID” e deve ser um identificador único (formato não especificado)

• application_id é obrigatório para chamadas à API da Vonage e deve corresponder à chave privada usada para assinar o token.

Você também pode ver um sub campo (os SDKs do cliente usam isso) ou algo chamado nbf , que é o carimbo de data e hora que indica “Não antes de” para esse token, o que significa que o token não é válido até esse momento.

A terceira e última seção do depurador do jwt.io é a assinatura. Os JWTs são criados com uma chave privada que não faz parte da carga útil.

A chave privada é, essencialmente, um segredo compartilhado entre você e a Vonage. Você pode verificar se a assinatura está correta inserindo sua chave privada na interface da web nesta seção.

Regenerar seu JWT

Às vezes, o problema que achamos que é o token é, na verdade, algo completamente diferente! Aqui estão algumas táticas que você pode tentar quando as duas primeiras etapas não surtirem efeito.

Experimente uma nova aplicação

Criar uma nova aplicação, gerar novas chaves, certificar-se de que você tem o arquivo correto chamado private key— todas essas etapas não deveriam fazer diferença, mas, às vezes, são tudo o que é necessário. Esse é o meu “truque esquisito” para problemas com JWT, e talvez ele ajude você também?

Gerar um token JSON Web diferente

Tente gerar um token e, em seguida, usá-lo em seu aplicativo ou em uma chamada direta à API a partir do seu cliente HTTP preferido.

Você pode gerar um JWT a partir da ferramenta CLI da Nexmo, usando seu ID de aplicativo e sua chave privada, desta forma:

nexmo jwt:generate path/to/private.key application_id=asdasdas-asdd-2344-2344-asdasdasd345

Como alternativa, temos uma ferramenta online disponível no nosso Portal do Desenvolvedor que você pode usar para gerar um JWT: https://developer.nexmo.com/jwt.

A depuração é uma habilidade

A depuração é uma habilidade à parte e, esperamos, que algo neste post tenha ajudado você a seguir em frente na criação de algo incrível. Se tiver mais dicas para compartilhar, conte para a gente! Estamos no @VonageDev no Twitter.