Depois de fazer login, como um servidor sabe que cada solicitação posterior é realmente sua? Uma resposta popular é um JSON Web Token, ou JWT, geralmente pronunciado como “jot”. É um pequeno dado assinado que o cliente envia com cada solicitação, e o servidor pode verificá-lo sem tocar no banco de dados.

A maneira mais rápida de entender um JWT é construir um e depois tentar quebrá-lo. Fizemos isso usando apenas a biblioteca padrão do Python, no Python 3.13, e a saída abaixo vem dessa execução. Este código é para aprendizado. Em uma aplicação real, use uma biblioteca bem mantida, porque é fácil errar nos detalhes da verificação.

O que é um JWT?

JWT é um padrão aberto, definido na RFC 7519, para passar declarações entre duas partes como uma string compacta. Uma reivindicação é simplesmente uma declaração, como “o ID deste usuário é 42”. Como o token está assinado, o destinatário pode confirmar quem o emitiu e se ninguém o alterou.

Pense em uma pulseira de festival. A equipe no portão verifica seu ingresso uma vez e lhe dá uma banda difícil de falsificar. Depois disso, cada barraca fica apenas olhando a banda, sem necessidade de ligar para a bilheteria. Um JWT funciona da mesma maneira que uma API.

Como funciona o login JWT

1. O usuário envia um nome de usuário e uma senha para o endpoint de login.
2. O servidor os verifica e cria um token assinado.
3. O cliente armazena o token.
4. Cada solicitação posterior inclui-o, normalmente em um cabeçalho: Authorization: Bearer <token>.
5. O servidor verifica a assinatura e a expiração e, em seguida, lê as declarações.

O principal benefício está na etapa 5. O servidor não precisa procurar uma sessão, o que é conveniente quando muitos serviços ou servidores precisam verificar o mesmo token. Se você é novo em APIs, comece com o que é uma API.

As três partes de um JWT

Um JWT parece um texto aleatório, mas consiste em três seções codificadas em Base64URL separadas por pontos. Aqui está um que geramos:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJzdWIiOiI0MiIsInJvbGUiOiJ1c2VyIiwiaWF0IjoxNzkzNTAwMDAwLCJleHAiOjE3OTM1MDA5MDB9
.7YfUDH_T-iDh8bMmUT8mmKYwOstzT8Ty--DTTAmQGWM

Adicionamos quebras de linha para facilitar a leitura. A decodificação das duas primeiras partes fornece JSON simples:

Header:  {"alg":"HS256","typ":"JWT"}
Payload: {"sub":"42","role":"user","iat":1793500000,"exp":1793500900}

Reivindicações padrão

Você também pode adicionar declarações personalizadas, como role. Os tempos são carimbos de data/hora Unix, em segundos. Mantenha a carga útil pequena, pois o token viaja com cada solicitação.

Construa um você mesmo

A criação de um token envolve a codificação das duas partes JSON e, em seguida, assiná-las com um segredo usando HMAC-SHA256:

import base64, hashlib, hmac, json

SECRET = b"demo-secret-do-not-use-in-production"

def b64url(data):
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()

def sign(message):
    return b64url(hmac.new(SECRET, message.encode(), hashlib.sha256).digest())

def create_token(payload):
    header = {"alg": "HS256", "typ": "JWT"}
    parts = [
        b64url(json.dumps(header, separators=(",", ":")).encode()),
        b64url(json.dumps(payload, separators=(",", ":")).encode()),
    ]
    message = ".".join(parts)
    return message + "." + sign(message)

A verificação funciona recalculando a assinatura e comparando-a com a do token. Somente alguém com o segredo pode produzir um correspondente:

def verify_token(token, now):
    header, payload, signature = token.split(".")
    expected = sign(header + "." + payload)
    if not hmac.compare_digest(signature, expected):
        raise ValueError("bad signature")
    claims = json.loads(b64url_decode(payload))
    if claims["exp"] < now:
        raise ValueError("token expired")
    return claims

Um token válido retornou suas reivindicações conforme esperado. compare_digest é utilizado porque roda em tempo constante, o que evita vazamento de informações por diferenças de tempo.

Tente mexer com isso

Suponha que um invasor decodifique a carga útil, altere "role":"user" para "role":"admin", codifique-a novamente e mantenha a assinatura antiga. Tentamos isso, junto com outros dois ataques:

Esta última tentativa visa uma verdadeira fraqueza histórica. Algumas bibliotecas já confiaram no próprio cabeçalho do token, então um invasor poderia simplesmente declarar que nenhuma assinatura era necessária. Nosso código sempre usa um algoritmo fixo, por isso foi rejeitado. Em uma biblioteca real, sempre especifique os algoritmos que você aceita.

Assinado, não criptografado

Este é o ponto mais incompreendido sobre os JWTs. Nosso token forjado foi rejeitado, mas seu conteúdo ainda era perfeitamente legível:

{"sub":"42","role":"admin","iat":1793500000,"exp":1793500900}

Base64URL é uma codificação, não uma criptografia, e qualquer pessoa pode revertê-la sem nenhuma chave. A assinatura impede que as pessoas alterem os dados, mas não os leiam. Portanto, nunca coloque senhas, números de cartão ou dados pessoais privados em uma carga JWT. Se o conteúdo precisar ser oculto, use tokens criptografados (JWE) ou apenas mantenha os dados no servidor.

HS256 versus RS256

Com a assinatura assimétrica, outros serviços podem verificar tokens sem serem capazes de cunhar os seus próprios, o que limita os danos caso um deles seja comprometido.

JWT versus sessões

Os JWTs são frequentemente apresentados como um substituto moderno para sessões. Na realidade, cada um tem vantagens e desvantagens:

Para um site tradicional renderizado por servidor, um cookie de sessão costuma ser mais simples e seguro. JWTs tendem a fazer mais sentido para APIs consumidas por diversos serviços ou para clientes móveis.

Onde armazenar tokens em um navegador

Muitos guias de segurança favorecem HttpOnly, Secure, SameSite cookies para aplicativos da web. Seja qual for sua escolha, sempre use HTTPS. Para enviar um token de JavaScript, consulte nosso tutorial da API JavaScript Fetch.

Atualizar tokens

A expiração curta limita o dano causado por um token roubado, mas ninguém quer fazer login a cada 15 minutos. A solução usual usa dois tokens:

• Token de acesso: de curta duração, como minutos, e enviado com cada solicitação de API.
• Token de atualização: tem vida mais longa, é armazenado com mais cuidado e é usado apenas para obter novos tokens de acesso.

O servidor monitora os tokens de atualização, para que possa revogá-los, o que proporciona um logout prático. Girá-los a cada uso também ajuda a detectar roubo, porque um token antigo roubado é reproduzido novamente.

Erros comuns de segurança

• Decodificação sem verificação. Ler uma carga útil não a torna confiável. Verifique sempre a assinatura.
• Aceitar qualquer algoritmo. Defina uma lista explícita de algoritmos permitidos.
• Usando um segredo fraco. Segredos curtos podem ser decifrados offline. Use um valor aleatório longo e mantenha-o fora do controle de origem.
• Ignorando a expiração. Tokens sem exp podem funcionar para sempre se roubados.
• Não verificar iss e aud. Caso contrário, um token emitido para um serviço poderá ser aceito por outro.
• Confiar em declarações obsoletas. Uma função dentro de um token pode ficar desatualizada até expirar.
• Tokens de registro. Qualquer pessoa que leia seus registros poderá reutilizá-los.
• Não testar caminhos de falha. Adicione testes para tokens expirados e modificados, bem como para tokens válidos. Nosso guia de teste de API com Postman pode ajudar.

Considerações finais

Um JWT são dados assinados nos quais um servidor pode confiar sem uma pesquisa, não um contêiner secreto e não uma atualização automática durante as sessões. Use prazos curtos, verifique tudo com uma biblioteca mantida e mantenha os dados privados fora da carga útil. Para ver por si mesmo, execute um pequeno script como o nosso, altere um caractere de um token e observe a falha na verificação.

Perguntas frequentes

Continue aprendendo