O Que É JWT (JSON Web Token): Estrutura, Autenticação Stateless e Segurança

JSON Web Token (JWT) é um padrão aberto para envio seguro de dados entre sistemas. Normatizado pela RFC 7519 da IETF, ele transmite informações em objetos JSON compactos com assinatura digital.

Aplicações checam acessos sem consultar bancos em cada chamada. O emissor assina a credencial e os serviços validam sua autenticidade na hora.

O que é JSON Web Token e como ele funciona na arquitetura web?

JSON Web Token é um padrão aberto (RFC 7519) para transporte seguro de dados em JSON. Ele comprova quem é o usuário por assinatura digital sem manter estado na memória do servidor.

Em sistemas com API REST, validar acessos precisa ser ágil. No modelo antigo de sessão, cada chamada consulta o banco. Em picos de tráfego, essa rotina gera filas de espera e sobrecarrega a rede.

O JWT reúne os dados do usuário na própria credencial assinada após o login. O cliente envia esse valor no cabeçalho Authorization: Bearer <token>. Ao receber a chamada, qualquer microsserviço confere a assinatura digital pela chave pública em frações de milissegundo, sem consultas a bancos centrais.

O que significam Header, Payload e Signature na estrutura do JWT?

A estrutura do JWT é formada por três partes separadas por pontos: header.payload.signature. O cabeçalho indica o algoritmo usado, a carga útil guarda os dados do usuário e a assinatura assegura a integridade do conjunto.

As duas primeiras partes usam codificação Base64URL (RFC 4648 §5) para trânsito em cabeçalhos HTTP. Essa codificação não é criptografia. Qualquer pessoa lê a carga útil, proibindo senhas abertas no token.

O Cabeçalho (Header)

O cabeçalho traz os metadados técnicos do token em JSON. O campo typ define o formato como JWT. O campo alg indica o algoritmo de assinatura, como "ES256" ou "RS256". O campo kid identifica a chave ativa em rotinas de troca periódica.

A Carga Útil (Payload)

A carga útil traz as declarações chamadas de claims, com dados de identidade e permissões:

• iss (Issuer): identifica quem emitiu o token.
• sub (Subject): identifica o usuário autenticado.
• aud (Audience): serviços autorizados a aceitar a credencial.
• exp (Expiration Time): data limite para a validade do token.
• iat (Issued At): instante da emissão do token.
• jti (JWT ID): código único para prevenir repetição de requisições.

A Assinatura (Signature)

A assinatura digital impede alterações no cabeçalho e na carga útil. Ela é calculada com a junção dos blocos codificados somada a uma chave secreta ou privada. Se alguém alterar dados no payload, o cálculo falha e o servidor rejeita a chamada na hora.

Qual é a diferença prática entre sessão tradicional e autenticação stateless?

A sessão tradicional grava o estado de login na memória do servidor ou em banco centralizado. O JWT registra as permissões no próprio token assinado, viabilizando validação descentralizada.

No modelo com estado (stateful), o servidor busca a sessão no Redis a cada clique. Se o Redis falhar, os acessos caem juntos. No modelo sem estado (stateless), o token contém as permissões com assinatura digital. O serviço valida a credencial na CPU local em frações de milissegundo.

Quais algoritmos de assinatura você deve escolher para proteger suas APIs?

A escolha entre algoritmos simétricos e assimétricos determina a segurança da arquitetura. Para sistemas modernos distribuídos, pares assimétricos representam a escolha recomendada.

O algoritmo HS256 adota chave simétrica única para emitir e validar o token, criando riscos em microsserviços. Os algoritmos RS256 e ES256 usam chaves pública e privada. Apenas o servidor central de login emite credenciais com a chave privada, enquanto as APIs usam a chave pública para validação.

A norma RFC 8725 e a OWASP Foundation recomendam chaves assimétricas para nuvem e microsserviços.

Quais são os riscos de segurança mais comuns e como evitar falhas?

Falhas em JWT decorrem de validações incompletas e guarda insegura no cliente. Ajustes incorretos abrem brechas para sequestro de contas.

A documentação da OWASP Foundation aponta três riscos críticos em aplicações web:

1. Ataque do Algoritmo "none": Bibliotecas antigas aceitavam tokens sem assinatura quando o campo alg vinha como "none". Exija sempre validação explícita de algoritmo no validador.
2. Ataque de Confusão de Chaves: Ocorre quando uma API que espera chave assimétrica aceita validação simétrica com a chave pública. Defina uma lista fechada de algoritmos permitidos no validador.
3. Armazenamento Inseguro no Navegador: Salvar tokens em localStorage expõe credenciais a roubo por falhas de Cross-Site Scripting (OWASP XSS Cheat Sheet). Guarde os tokens em cookies seguros com as diretivas HttpOnly, Secure e SameSite=Strict.

Como gerenciar Access Token curto e rotação de Refresh Token?

Como tokens sem estado não podem ser cancelados à distância, use prazos curtos. O padrão une Access Token de cinco a quinze minutos com Refresh Token Rotation.

O Access Token curto concede acesso imediato às rotas da API. Ao vencer o prazo, a aplicação usa o Refresh Token para obter nova credencial. Em cada troca, o sistema gera um novo par e anula o anterior na hora.

Se um token antigo for reenviado, o sistema bloqueia a conta na hora. O MaxVision Code adota tokens de sessenta segundos com escopos restritos. Para estruturar APIs seguras, fale com nosso time no canal de contato.

Como implementar a validação segura de JWT em TypeScript?

A biblioteca jose é referência em TypeScript e Node.js. Ela roda sobre a API nativa Web Crypto de maneira rápida e segura.

O exemplo a seguir gera chaves ES256, emite token com prazo curto e valida emissor e público:

import { generateKeyPair, SignJWT, jwtVerify, type JWTPayload } from "jose";

interface CustomUserClaims extends JWTPayload {
  userId: string;
  role: "admin" | "developer" | "reviewer";
}

// 1. Gera par de chaves assimétricas ES256
const { publicKey, privateKey } = await generateKeyPair("ES256", {
  extractable: false,
});

const ISSUER = "https://auth.maxvision.com.br";
const AUDIENCE = "https://api.maxvision.com.br";

/**
 * Emite token com validade de 10 minutos
 */
export async function emitirTokenUsuario(
  userId: string,
  role: CustomUserClaims["role"]
): Promise<string> {
  return await new SignJWT({ userId, role })
    .setProtectedHeader({ alg: "ES256", typ: "JWT" })
    .setIssuer(ISSUER)
    .setAudience(AUDIENCE)
    .setSubject(userId)
    .setIssuedAt()
    .setExpirationTime("10m")
    .setJti(crypto.randomUUID())
    .sign(privateKey);
}

/**
 * Valida assinatura, emissor e expiração
 */
export async function validarToken(token: string): Promise<CustomUserClaims> {
  const { payload } = await jwtVerify(token, publicKey, {
    issuer: ISSUER,
    audience: AUDIENCE,
    algorithms: ["ES256"], // Bloqueia algoritmo "none"
  });

  return payload as CustomUserClaims;
}

try {
  const tokenValido = await emitirTokenUsuario("usr_4412", "developer");
  const claims = await validarToken(tokenValido);
  console.log("Acesso validado para:", claims.userId);
} catch (error) {
  console.error("Falha ao validar token:", error);
}

Esse modelo atende aos critérios da RFC 8725 e bloqueia qualquer troca de algoritmo.

Perguntas Frequentes sobre JSON Web Token (JWT)

O que significa a sigla JWT e para que ela serve?

JWT significa JSON Web Token, um padrão aberto da norma RFC 7519 da IETF. Ele serve para transmitir dados de login de forma segura e compacta entre sistemas web. Sua principal aplicação ocorre na autenticação descentralizada de APIs modernas e microsserviços.

O JWT criptografa os dados que estão dentro dele por padrão?

Não, o JWT tradicional com assinatura não esconde as informações gravadas no payload. Os dados recebem apenas codificação em Base64URL para tráfego em rede. Qualquer pessoa consegue ler os campos, o que exige nunca incluir dados sigilosos sem criptografia adicional.

Por que não se deve armazenar tokens JWT no localStorage do navegador?

Salvar credenciais em localStorage deixa a aplicação vulnerável a ataques XSS. Scripts maliciosos leem esse local e furtam acessos. A recomendação da OWASP é guardar tokens em cookies protegidos com HttpOnly e Secure.

O que é Refresh Token Rotation e como ele impede fraudes?

Refresh Token Rotation é uma rotina de segurança que troca o token de atualização a cada nova emissão de acesso. Se um token antigo for reenviado por um invasor, o sistema detecta o reuso e derruba a sessão na hora, protegendo a conta.

Fontes primárias e referências técnicas auditadas

• Internet Engineering Task Force (IETF): RFC 7519: JSON Web Token (JWT).
• Internet Engineering Task Force (IETF): RFC 7515: JSON Web Signature (JWS).
• Internet Engineering Task Force (IETF): RFC 8725: JSON Web Token Best Current Practices (BCP 225).
• Internet Engineering Task Force (IETF): RFC 4648: The Base16, Base32, and Base64 Data Encodings (§5 Base64URL).
• OWASP Foundation: JSON Web Token Cheat Sheet for Developers.
• OWASP Foundation: Cross-Site Scripting (XSS) Prevention Cheat Sheet.
• National Institute of Standards and Technology (NIST): Special Publication 800-63B: Digital Identity Guidelines.
• Panva / Open Source: jose Library Specification & Modern Web Cryptography API.