JWT: compreender estrutura, assinatura, expiração e erros comuns

Um JSON Web Token é frequentemente utilizado para transportar informações entre sistemas. O formato compacto pode dar a impressão de um objeto cifrado ou intrinsecamente fiável, mas não é isso que um JWT garante.

Três partes, geralmente legíveis

Um JWT clássico contém header, payload e assinatura separados por pontos. As duas primeiras partes são codificadas, não necessariamente cifradas. Não coloque segredos no payload supondo que ficam invisíveis.

Um descodificador ou inspetor permite ler localmente os campos de um token, mas isso apenas mostra o seu conteúdo.

Descodificar não é verificar

Apresentar o payload prova apenas que a string tem um formato suficientemente válido para ser lida. Para confiar nos claims, a aplicação deve verificar a assinatura com a chave e o algoritmo esperados e depois aplicar os restantes controlos.

O que a assinatura prova

A assinatura é calculada a partir das partes codificadas do token e de uma chave segundo o algoritmo escolhido. Quando é corretamente verificada, permite detetar alterações e estabelecer que o token foi assinado por uma entidade que possuía a chave esperada. Não torna o payload confidencial.

Famílias simétricas como HS256 utilizam um segredo partilhado; famílias assimétricas como RS256 ou ES256 separam a chave privada de assinatura da chave pública de verificação.

A aplicação deve impor os algoritmos que aceita em vez de confiar cegamente no algoritmo declarado pelo token.

Expiração, audiência e emissor

Claims como exp, nbf, iat, iss e aud só têm valor quando são realmente verificados. Aceitar um token expirado, destinado a outra audiência ou proveniente de um emissor inesperado pode anular uma parte importante da proteção.

Uma pequena tolerância para diferenças de relógio entre sistemas pode ser necessária, mas não deve tornar-se uma extensão excessiva da validade.

Tokens curtos e renovação

Reduzir a duração de um access token limita a janela de utilização em caso de roubo, mas exige uma estratégia de renovação. Refresh tokens, quando existem, são segredos de elevado valor e devem ser protegidos e revogáveis de acordo com a arquitetura.

A revogação é menos natural num token totalmente autónomo do que numa sessão armazenada no servidor. Isto não torna JWT uma má solução; é apenas um compromisso que deve ser compreendido.

Onde guardar um token no navegador?

Não existe uma resposta universal. Um armazenamento acessível a JavaScript fica exposto em caso de XSS. Um cookie HttpOnly reduz esse acesso, mas introduz considerações relacionadas com cookies, SameSite e CSRF.

A decisão depende do modelo de ameaça e da forma como o cliente comunica com o backend. Evite sempre colocar JWT em URLs, onde podem ficar registados no histórico, logs ou referrers.

JWT é apenas uma peça da arquitetura

Gestão de sessão, revogação, armazenamento no cliente, CSRF, XSS e duração dos tokens continuam a ser decisões arquiteturais. Um JWT válido não determina automaticamente se um utilizador tem autorização para executar uma determinada ação.

Autenticação e autorização são diferentes: mesmo depois de validar o token, o servidor deve confirmar que o utilizador tem permissão para aceder ao recurso solicitado.

Erros frequentes

Entre os erros mais comuns estão:

• aceitar um algoritmo inesperado;
• não verificar iss ou aud;
• utilizar chaves fracas;
• atribuir uma duração demasiado longa;
• colocar dados sensíveis no payload;
• confiar num papel declarado sem verificar a autorização no servidor.

As ferramentas JWT são úteis para aprender, inspecionar e criar dados de teste. Por si só, porém, não transformam uma implementação numa arquitetura de autenticação segura.

Para enquadrar JWT nos fluxos de autorização modernos e compreender PKCE, JWK e JWKS, consulte OAuth 2.0, PKCE, JWT, JWK e JWKS.