T
jwt debugging security authentication web-development

Resolvendo 'JWT expired' e erros comuns de JSON Web Token

Um guia completo para corrigir erros de JWT como 'invalid signature', 'token expired' e 'malformed token'. Aprenda a depurar problemas de autenticación.

2026-04-11 Usar esta ferramenta

Resolvendo "JWT expired" e erros comuns de JSON Web Token: Guia Completo

Os JSON Web Tokens (JWT) são o padrão da indústria para transmitir informações de forma segura entre partes como um objeto JSON. Eles são amplamente utilizados para autenticação e autorização em aplicações web e móveis modernas. No entanto, por serem assinados criptograficamente e muitas vezes terem regras de expiração rígidas, podem ser uma grande fonte de dores de cabeça na depuração.

Neste guia, vamos detalhar os erros de JWT mais comuns, explicar por que eles acontecem e mostrar como corrigi-los.

1. Mensagens de erro comuns de JWT

Dependendo da biblioteca que você utiliza (como jsonwebtoken no Node.js), você encontrará estes nomes de erro comuns:

  • TokenExpiredError: O token é válido, mas ultrapassou o tempo de expiração.
  • JsonWebTokenError: invalid signature: A assinatura do token não corresponde ao segredo/chave fornecida.
  • JsonWebTokenError: jwt malformed: A string fornecida não é uma estrutura JWT válida.
  • JsonWebTokenError: jwt signature is required: Um token foi fornecido sem a seção de assinatura.
  • JsonWebTokenError: jwt invalid audience: A claim aud no token não corresponde ao valor esperado.

2. Principais causas e soluções

2.1 "TokenExpiredError" (JWT expired)

Todo JWT seguro deve ter uma claim exp (expiração). Assim que o tempo atual ultrapassa esse valor, o token não é mais válido.

O sintoma: Os usuários são deslogados repentinamente, ou as requisições de API começam a retornar erros 401 Unauthorized com a mensagem jwt expired.

A solução:

  1. Refresh Tokens: Implemente uma estratégia de "Refresh Token" para que os usuários não precisem fazer login manualmente toda vez que um token de acesso expirar.
  2. Sincronização de relógio: Certifique-se de que o relógio do seu servidor esteja sincronizado usando NTP. Mesmo alguns segundos de desvio podem causar problemas.
  3. Verifique iat e nbf: Certifique-se de que as claims "emitido em" (iat) e "não antes de" (nbf) também estejam corretas.

2.2 "invalid signature" (invalid JWT signature)

Um JWT consiste em três partes: Cabeçalho (Header), Payload e Assinatura (Signature). A assinatura é criada fazendo o hash do cabeçalho e do payload com uma chave secreta. Se apenas um caractere no payload mudar, ou se a chave secreta errada for usada, a assinatura torna-se inválida.

A causa:

  • Uso do secret ou public key errado para verificar o token.
  • Uma incompatibilidade entre o algoritmo usado para assinar (ex: HS256) e verificar (ex: RS256).
  • O token foi adulterado ou corrompido durante a transmissão.

A solução:

  • Verifique duas vezes suas variáveis de ambiente para a chave secreta.
  • Verifique se o cabeçalho alg no JWT corresponde ao algoritmo que você está usando para a verificação.

2.3 "jwt malformed" ou "jwt decode failed"

Um JWT válido deve ter três partes separadas por pontos (header.payload.signature). Se qualquer parte estiver faltando ou se a string não for um Base64URL válido, ela é considerada malformada.

A causa:

  • Passar um prefixo "Bearer " diretamente para a biblioteca (ex: atob("Bearer <token>")).
  • Copiar e colar um token parcial.
  • Espaços em branco extras ou caracteres ocultos na string do token.

A solução: Certifique-se de remover o prefixo Bearer antes de passá-lo para o seu decodificador.

const token = authHeader.split(' ')[1]; // Extrair token de "Bearer <token>"

2.4 "jwt invalid audience" ou "jwt invalid issuer"

Esses erros ocorrem quando as claims aud (audiência) ou iss (emissor) no payload não correspondem aos valores que seu servidor espera.

A solução: Certifique-se de que a configuração no seu servidor de autenticação (ex: Auth0, Firebase ou o seu próprio) corresponda às opções de verificação no código da sua aplicação.

3. Solução de problemas avançada

3.1 Inspecionando o Payload

Se você estiver recebendo um erro de assinatura, o primeiro passo é inspecionar o payload para ver se ele contém os dados esperados. Você não precisa da chave secreta para decodificar e ler o payload (já que ele é apenas codificado em Base64).

3.2 Ataques de confusão de algoritmo (Algorithm Confusion Attacks)

Certifique-se de que sua biblioteca esteja configurada para permitir apenas os algoritmos específicos que você espera. Algumas bibliotecas mais antigas eram vulneráveis a um ataque onde um invasor poderia alterar o cabeçalho para alg: none, ignorando a segurança. As bibliotecas modernas corrigiram isso na maioria das vezes, mas sempre defina explicitamente seus algoritmos permitidos.

jwt.verify(token, secret, { algorithms: ['HS256'] });

4. Prevenção e melhores práticas

  1. Tokens de acesso de curta duração: Mantenha os tokens de acesso com vida curta (ex: 15 minutos) e use tokens de atualização para sessões mais longas.
  2. Segredos seguros: Nunca coloque seu segredo JWT diretamente no código. Use variáveis de ambiente e mude-as periodicamente.
  3. Valide cada requisição: Nunca confie em um JWT sem verificar sua assinatura no lado do servidor.
  4. Use HTTPS: Sempre transmita tokens via HTTPS para evitar ataques de interceptação do tipo "Man-in-the-Middle".

5. FAQ: Perguntas frequentes

P: Posso ler os dados dentro de um JWT sem o segredo?

R: Sim. O cabeçalho e o payload são apenas codificados em Base64URL, não criptografados. Qualquer pessoa que tenha o token pode ler os dados. Nunca coloque informações sensíveis, como senhas ou números de cartão de crédito, no payload de um JWT.

P: Qual é a diferença entre HS256 e RS256?

R: O HS256 usa uma única chave secreta tanto para assinar quanto para verificar (simétrico). O RS256 usa uma chave privada para assinar e uma chave pública para verificar (assimétrico), o que é mais seguro para sistemas distribuídos.

P: Como lidar com um erro "jwt expired" no frontend?

R: Capture o erro 401 no seu interceptor de API. Se o erro for "jwt expired", tente chamar seu endpoint de "refresh token". Se isso falhar, redirecione o usuário para a página de login.

6. Ferramenta de verificação rápida

Está com problemas com um token específico? Use nosso Decodificador e Depurador de JWT. Ele permite que você:

  • Decodifique instantaneamente qualquer JWT para ver seu cabeçalho e payload.
  • Verifique o status de expiração e claims como iat, exp e nbf.
  • Identifique tokens malformados (malformed tokens) e problemas de codificação.
  • Valide assinaturas (se você fornecer sua chave secreta localmente).

Erros relacionados

  • Resolvendo erros 'Unexpected token in JSON'
  • Como corrigir erros 'invalid base64 string'
  • Resolvendo erros 'invalid regular expression'
Voltar ao blog Decodificador e Gerador JWT →