Como Decodificar Tokens JWT com Segurança

JWT (JSON Web Token) é um formato de token compacto e seguro para URL definido pela RFC 7519. É usado para autenticação e troca de informações entre partes. JWTs se tornaram o padrão de fato para representar claims de forma segura entre duas partes, como um cliente e um servidor em uma aplicação web moderna. Eles são autocontidos, significando que toda a informação necessária para autenticar uma requisição está embutida diretamente no próprio token, eliminando a necessidade de armazenamento de sessão no servidor em muitas arquiteturas.

A popularidade dos JWTs abrange aplicações de página única, aplicativos móveis, gateways de API e comunicação entre microsserviços. Quando um usuário faz login em uma aplicação, o servidor emite um JWT que o cliente armazena e apresenta com cada requisição subsequente. O servidor então verifica a assinatura do token para autenticar e autorizar a requisição. Entender como decodificar e inspecionar JWTs com segurança é crítico para desenvolvedores que precisam depurar fluxos de autenticação, verificar claims e solucionar problemas relacionados a tokens sem expor dados sensíveis ou introduzir vulnerabilidades.

Entendendo a Estrutura JWT

Um JWT consiste em três partes separadas por pontos, cada uma codificada usando Base64URL (uma variante segura para URL da codificação Base64):

header.payload.signature

Exemplo:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwi
bmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4
fwpMeJf36POk6yJV_adQssw5c

O primeiro segmento é o cabeçalho, que contém metadados sobre o token, incluindo o algoritmo de assinatura e o tipo de token. O segundo segmento é o payload, que carrega as claims ou declarações sendo feitas. O terceiro segmento é a assinatura, que é computada pegando o cabeçalho e payload codificados, combinando-os com um ponto, e assinando o resultado usando o algoritmo especificado no cabeçalho juntamente com uma chave secreta ou chave privada.

Detalhe da Codificação Base64URL

JWT usa codificação Base64URL, que difere do Base64 padrão de duas maneiras importantes. Primeiro, substitui o caractere + por - para evitar problemas em parâmetros de consulta URL onde + é interpretado como espaço. Segundo, substitui o caractere / por _ para evitar conflitos com separadores de caminho URL. Além disso, caracteres de preenchimento (=) são removidos do final dos segmentos JWT porque são desnecessários para a decodificação e apenas adicionariam bytes desnecessários ao token.

Claims do Cabeçalho JWT

O cabeçalho tipicamente contém o algoritmo e o tipo de token, mas também pode incluir metadados adicionais para cenários avançados.

A claim kid (Key ID) é particularmente importante em ambientes onde múltiplas chaves de assinatura estão em rotação. Permite que o servidor encontre a chave correta a partir de um conjunto de chaves sem adivinhar. A claim jku aponta para uma URL contendo um Conjunto de Chaves Web JSON (JWKS), que o verificador pode buscar para obter a chave pública para verificação de assinatura. No entanto, buscar chaves de URLs especificadas em tokens não confiáveis introduz riscos de segurança e só deve ser feito com validação adequada.

Claims Comuns do Payload JWT

O payload contém claims que fornecem informações sobre o usuário e o próprio token. Estas claims são categorizadas como registradas, públicas e privadas.

Claims registradas são padronizadas pela especificação JWT e têm significados específicos. A claim exp é particularmente crítica para a segurança. Se um token não incluir um tempo de expiração, ou se o servidor falhar em validá-lo, o token permanece válido indefinidamente, criando uma vulnerabilidade grave se o token for vazado. A claim iat registra quando o token foi criado e pode ser usada para determinar a idade do token ou implementar políticas de rotação de tokens.

Além dessas claims registradas, as aplicações tipicamente incluem claims personalizadas para funções de usuário, permissões, endereços de email e outros dados específicos da aplicação. Por exemplo, um token pode incluir "role": "admin" ou "permissions": ["read", "write", "delete"]. Estas claims personalizadas devem ser inspecionadas cuidadosamente, mas nunca confiadas sem verificação de assinatura.

Decodificar vs Verificar

A distinção entre decodificar e verificar é o conceito mais importante a entender ao trabalhar com JWTs. Confundir os dois é uma fonte comum de vulnerabilidades de segurança.

Decodificar simplesmente aplica decodificação Base64URL ao cabeçalho e payload. Qualquer pessoa pode decodificar um JWT sem qualquer chave secreta. Você pode decodificar qualquer JWT colando-o em uma ferramenta de decodificação ou executando uma função simples de decodificação Base64URL nos dois primeiros segmentos. Isso torna os JWTs úteis para inspeção e depuração, mas também significa que o conteúdo do payload é publicamente legível.

Verificar verifica a assinatura usando uma chave secreta (HMAC) ou chave pública (RSA/ECDSA). Isso confirma que o token não foi adulterado e que foi emitido por uma parte confiável. A verificação é a etapa que fornece segurança. Sem ela, um atacante poderia modificar o payload para alterar o ID do usuário ou função, re-codificar o cabeçalho e payload, e criar uma nova assinatura que pareceria válida para um servidor que pula ou implementa incorretamente a verificação de assinatura.

Ataques de Confusão de Algoritmo

Uma das vulnerabilidades JWT mais perigosas é o ataque de confusão de algoritmo, também conhecido como ataque de confusão de chave. Este ataque explora o fato de que o algoritmo é especificado no cabeçalho, que é controlado pelo atacante, já que o cabeçalho é apenas codificado em Base64URL e não criptografado.

Em um cenário típico, um servidor usa RS256 (RSA com SHA-256) para assinar tokens. A chave pública do servidor está amplamente disponível, enquanto a chave privada é mantida em segredo. Um atacante intercepta um token válido e altera o cabeçalho alg de RS256 para HS256. Como HS256 usa uma chave secreta simétrica, o servidor tentará verificar a assinatura usando o algoritmo HS256. O erro crítico é se o servidor usar a chave pública RS256 como o segredo HS256. Como a chave pública é pública, o atacante pode computar uma assinatura HS256 válida para qualquer payload usando a chave pública como o segredo HMAC. O servidor então verifica a assinatura usando a mesma chave pública e aceita o token forjado.

Para prevenir este ataque, os servidores devem validar que o algoritmo corresponde ao algoritmo esperado antes de verificar, ou usar uma biblioteca que seja imune a este ataque por design. Muitas bibliotecas JWT modernas agora usam métodos separados para verificação assimétrica e simétrica para eliminar este risco.

Etapas de Decodificação Segura

Siga estas etapas sempre que precisar decodificar e inspecionar um token JWT.

1. Copie o token JWT da sua aplicação. Certifique-se de ter capturado o token completo incluindo todos os três segmentos separados por pontos. Um token parcial falhará ao decodificar corretamente.

2. Use uma ferramenta de decodificação confiável como o Decodificador JWT que execute inteiramente no navegador ou em sua máquina local. Evite colar tokens em ferramentas online desconhecidas que podem registrar ou transmitir seus tokens para servidores remotos. Mesmo que um token tenha vida curta, expô-lo a terceiros pode permitir que eles o repitam dentro de sua janela de validade.

3. Inspecione o cabeçalho em busca do algoritmo. Confirme que o algoritmo corresponde ao que você espera que seu servidor use. Se você vir um algoritmo inesperado como none ou uma mudança de RS256 para HS256, trate o token como suspeito.

4. Revise as claims do payload. Verifique os timestamps de exp (expiração) e nbf (não antes) para confirmar que o token é atualmente válido. Verifique se a claim iss (emissor) corresponde ao identificador do seu servidor. Confirme que a claim aud (audiência), se presente, inclui sua aplicação.

5. Nunca compartilhe o token publicamente. Tokens postados em relatórios de bug, perguntas no Stack Overflow ou gists do GitHub podem ser abusados por qualquer pessoa que os encontre antes de expirarem. Sempre redija ou substitua tokens por exemplos fictícios antes de compartilhar.

6. Nunca verifique com chaves não confiáveis. Se seu código de verificação aceitar chaves de entrada do usuário, URLs remotas ou arquivos de configuração que podem ser modificados por atacantes, todo seu sistema de autenticação está comprometido.

Decodificando JWTs em Código

Embora ferramentas online sejam convenientes para inspeção ad-hoc, você frequentemente precisará decodificar JWTs programaticamente em sua aplicação. Aqui está como decodificar um payload JWT em algumas linguagens de programação populares sem realizar verificação de assinatura.

JavaScript (Node.js)

function decodeJWT(token) {
  const payload = token.split('.')[1];
  const decoded = Buffer.from(payload, 'base64url').toString('utf8');
  return JSON.parse(decoded);
}

const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';
console.log(decodeJWT(token));

Python

import base64
import json

def decode_jwt(token):
    payload = token.split('.')[1]
    # Adicionar padding para decodificação base64
    padding = 4 - len(payload) % 4
    if padding != 4:
        payload += '=' * padding
    decoded = base64.urlsafe_b64decode(payload)
    return json.loads(decoded)

token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
print(decode_jwt(token))

Estes exemplos demonstram a decodificação apenas para fins de inspeção. Para verificação em produção, sempre use uma biblioteca JWT bem auditada que lide corretamente com validação de algoritmo, gerenciamento de chaves e verificação de assinatura.

Melhores Práticas de Segurança

Além de decodificar com segurança, seguir estas melhores práticas manterá sua implementação JWT segura.

Use tempos de expiração curtos. Tokens de acesso devem expirar dentro de 15 a 60 minutos. Tokens de curta duração limitam o dano se um token for vazado. Combine tokens de acesso com tokens de atualização que têm vidas úteis mais longas e podem ser revogados individualmente.

Valide todas as claims necessárias. Sempre verifique as claims exp, nbf, iss e aud durante a verificação. Muitos ataques exploram validação de claims ausente ou incorreta.

Use algoritmos assimétricos para sistemas distribuídos. RS256 ou ES256 permitem que o servidor assine tokens com uma chave privada enquanto qualquer serviço pode verificá-los com a chave pública. Isso elimina a necessidade de compartilhar segredos entre serviços.

Implemente lista negra de tokens. Para cenários onde você precisa revogar tokens antes que expirem, mantenha uma lista negra ou use um número de versão de token armazenado em seu banco de dados. Incremente a versão em mudanças de senha ou suspensão de conta para invalidar todos os tokens existentes.

Aviso de Segurança

Nunca aceite tokens de fontes não confiáveis. Sempre verifique a assinatura em seu servidor antes de confiar no payload. Esteja ciente de ataques de confusão de algoritmo onde um atacante muda RS256 para HS256 para usar a chave pública como um segredo. Use bibliotecas JWT respeitáveis que implementem verificação de assinatura de forma segura e mantenha-as atualizadas para se beneficiar das últimas correções de segurança.

Lembre-se que decodificar não é verificar. Qualquer pessoa pode ler o conteúdo de um JWT simplesmente decodificando Base64 do payload. Trate payloads JWT como informação pública no que diz respeito à confidencialidade, e confie na verificação de assinatura para integridade e autenticidade.