🎫
← Voltar aos guias

Estrutura do Token JWT Explicada: Header, Payload e Signature

· Tags: jwt-structure, jwt-header, jwt-payload, jwt-signature, json-web-token

Estrutura do Token JWT Explicada

Todo JSON Web Token (JWT) é uma string compacta e segura para URLs que transporta claims (declarações) entre duas partes. Entender sua estrutura interna é essencial para qualquer desenvolvedor que trabalhe com segurança baseada em tokens.

As Três Partes de um JWT

Um JWT consiste em três partes separadas por pontos (.):

header.payload.signature

Exemplo:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Cada parte é um JSON codificado em base64url. Um JWT é assinado, não criptografado — qualquer pessoa pode decodificar e ler seu conteúdo.

Parte 1: O Header (Cabeçalho)

O header contém metadados sobre o token — o algoritmo de assinatura e o tipo de token.

| Campo | Descrição | Valores de Exemplo | |-------|-----------|---------------------| | alg | Algoritmo de assinatura (obrigatório) | HS256, RS256, ES256 | | typ | Tipo de token (opcional) | JWT | | kid | ID da chave (opcional) | "key-1" |

{
  "alg": "HS256",
  "typ": "JWT"
}

O campo alg informa ao verificador qual algoritmo criou a assinatura. Uma incompatibilidade de algoritmo — ou aceitar alg: "none" — é uma vulnerabilidade comum de segurança em JWT.

Parte 2: O Payload

O payload contém claims (declarações) sobre o usuário e metadados. As claims se enquadram em três categorias:

Claims Registradas

| Claim | Nome Completo | Finalidade | |-------|----------------|------------| | iss | Issuer (Emissor) | Quem emitiu o token | | sub | Subject (Assunto) | Identifica o usuário | | aud | Audience (Público) | Destinatário pretendido | | exp | Expiration (Expiração) | Timestamp de expiração do token | | nbf | Not Before (Não Antes de) | Token não é válido antes deste horário | | iat | Issued At (Emitido Em) | Timestamp de criação do token | | jti | JWT ID | Identificador único do token |

Exemplo de Payload Decodificado

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "exp": 1516242622,
  "iss": "https://auth.example.com"
}

As claims públicas são definidas no registro da IANA ou usam URIs resistentes a colisões. As claims privadas são claims personalizadas acordadas entre o emissor e o consumidor.

Parte 3: A Signature (Assinatura)

A assinatura é criada combinando o header codificado, o payload codificado e uma chave secreta usando o algoritmo do header. Ela serve a dois propósitos:

  1. Integridade — confirma que o token não foi modificado após a assinatura.
  2. Autenticação — prova que o token foi assinado pela parte esperada.

Criação da Assinatura HS256

HMACSHA256(
  base64urlEncode(header) + "." + base64urlEncode(payload),
  secret
)

Criação da Assinatura RS256

RSASHA256(
  base64urlEncode(header) + "." + base64urlEncode(payload),
  privateKey
)

Base64url vs Base64 Padrão

| Aspecto | Base64 Padrão | Base64url | |---------|-----------------|------------| | Caractere 62 | + | - | | Caractere 63 | / | _ | | Preenchimento | = | Omitido |

Essa codificação garante que os JWTs sejam seguros para cabeçalhos HTTP, parâmetros de consulta e caminhos de URL sem necessidade de percent-encoding.

Processo Completo de Criação de um JWT

  1. Crie o JSON do header e codifique-o em base64url.
  2. Crie o JSON do payload e codifique-o em base64url.
  3. Concatene com um separador ..
  4. Assine com o algoritmo e o segredo escolhidos.
  5. Codifique a assinatura em base64url.
  6. Concatene as três partes com separadores ..

Considerações de Segurança

  • Nunca armazene segredos no payload. O payload é codificado, não criptografado.
  • Sempre valide a assinatura. Sem verificação, qualquer pessoa pode forjar tokens.
  • Verifique o header alg. Rejeite alg: "none" e tentativas de downgrade de algoritmo.
  • Defina tempos de expiração curtos. Use a claim exp em minutos ou horas, não em meses.

Decodifique um Token JWT Online

Use a ferramenta de decodificador de JWT para examinar qualquer token. Cole-o e veja instantaneamente o header decodificado, o payload e o algoritmo de assinatura. Todo o processamento acontece no seu navegador.

Estrutura do Token JWT Explicada: Header, Payload e Signature - CoolTool