Pesquise como os JWTs se encaixam na autenticação por e-mail e senha e você encontrará sempre as mesmas perguntas: é seguro colocar credenciais em um token, ainda preciso de HTTPS, quem deve ler isso e o que acontece quando ele expira? As respostas são curtas, e acertá-las é a maior parte do trabalho.
Este tutorial percorre o ciclo de vida completo de um JSON Web Token em um app de e-mail/senha, do primeiro cadastro ao logout, usando a API REST do AuthFlow™. O formato do token é definido na RFC 7519; você não precisa lê-la para acompanhar.
O que um JWT é e o que ele não é
Um JWT é o resultado da autenticação, não um substituto dela. O usuário prova quem é uma única vez, com e-mail e senha. O servidor então devolve um token assinado que diz "esta pessoa já se autenticou", e cada requisição seguinte leva o token em vez da senha. É isso que torna os JWTs úteis em sistemas distribuídos e sem estado: qualquer serviço que tenha a chave correta pode verificar o token sem mais uma consulta ao banco de dados.
Um JWT tem três partes: um cabeçalho (tipo do token e algoritmo de assinatura), um payload com declarações (claims) sobre o usuário e uma assinatura. A assinatura prova que o token não foi alterado. Ela não esconde nada. O payload é apenas codificado em base64, então qualquer pessoa que obtenha o token pode lê-lo. Trate um JWT como à prova de adulteração, não como secreto.
Nunca coloque a senha no token
Uma dúvida frequente de iniciantes é se as credenciais do usuário podem ser armazenadas no JWT. Em geral, você não deveria precisar: o próprio token já é uma credencial de curta duração gerada pelo login. Se precisar identificar o usuário, coloque um identificador na claim sub, mais um papel ou nível de acesso se o seu backend precisar. Deixe de fora senhas, segredos e qualquer coisa que você não gostaria de ver exposta em um navegador.
O HTTPS é uma preocupação separada, e você deve usá-lo para tudo. Ele protege o tráfego entre cliente e servidor, enquanto a assinatura do JWT protege a integridade do token. Um não substitui o outro.
Passo 1: Mantenha a chave de API no seu servidor
Toda chamada ao AuthFlow é feita em nome da sua organização, usando a chave de API do painel do proprietário. Essa chave deve ficar em uma infraestrutura que você controla, como uma variável de ambiente no servidor, por exemplo AUTHFLOW_API_KEY. Nunca a envie no JavaScript do navegador. O desenho seguro mais simples é um pequeno backend (ou o proxy ExpressJS que publicamos) com o qual seu frontend conversa e que, por sua vez, fala com /auth em nome dele.
Passo 2: Cadastro e login
Antes de um cadastro ou login, seu backend solicita a /auth/fooBar um token antiabuso de curta duração para o e-mail do usuário. Ele expira em 45 segundos, então busque-o imediatamente antes da próxima chamada e nunca o reutilize. Em seguida, chame /auth/signUp com o valor foobar, sua api_key, o email, uma password que atenda à regra de complexidade (8 a 32 caracteres com maiúscula, minúscula, número e caractere especial), o fullname e disclaimed definido como true. Um cadastro bem-sucedido retorna imediatamente um token de sessão, e um e-mail e papel duplicados retornam 409.
O login funciona da mesma forma em /auth/login. Em caso de sucesso, você recebe o token de sessão: um JWT assinado com RS512. O RS512 usa um par de chaves, então os tokens são assinados com uma chave privada que você nunca vê e podem ser verificados sem compartilhar nenhum segredo.
Passo 3: Armazene o token com cuidado
Quando o backend tiver o token, decida onde ele ficará. Cookies HTTP-only são a opção recomendada porque os scripts da página não conseguem lê-los, o que limita o dano de uma falha de cross-site scripting. Seja qual for a sua escolha, guarde o token de sessão, não um temporário, e garanta que ele nunca seja gravado em logs.
Passo 4: Valide em toda rota protegida
Antes de atender a uma requisição protegida, seu backend deve verificar o token. Chame /auth/validate com o sessionToken e o email do usuário; um token válido tem sucesso, e um inválido ou expirado retorna 401. Use /auth/me quando precisar do perfil do usuário atual. Fazer isso no servidor a cada requisição protegida é importante, porque um token assinado que você nunca verifica não protege nada.
A expiração faz parte do projeto. Quando um token expira, o usuário faz login novamente, em vez de o seu app tentar estendê-lo silenciosamente. Garanta que o app trate esse 401 com elegância, enviando o usuário de volta à tela de login.
Passo 5: Lide com a autenticação de dois fatores
Se o usuário ativou o 2FA, /auth/login não retorna um token de sessão. Em vez disso, retorna requires2FA e um tempToken. Seu app então pede um segundo fator e troca o tempToken por meio de um dos endpoints de verificação /auth/2fa (um código TOTP, um código de backup ou um OTP por e-mail). Somente essa troca produz o token de sessão real, então certifique-se de armazenar esse, e nunca o tempToken.
Depurando tokens com jwt.io
Quando algo não está certo, a forma mais rápida de ver o que um token realmente contém é o jwt.io. Cole um token no depurador dele e ele decodifica o cabeçalho e o payload, para você conferir o algoritmo, a claim sub e o horário de expiração. Isso costuma bastar para identificar um token expirado, o usuário errado ou um tempToken armazenado por engano.
Cabe um alerta, decorrente de tudo o que foi dito: um token é uma credencial. Trate um token de produção ativo como algo sensível, prefira contas de teste ao depurar e evite colar tokens reais em qualquer ferramenta em que você não confie. Decodificar um token não é o mesmo que verificá-lo. A verificação continua acontecendo no seu servidor, por meio de /auth/validate.
Passo 6: Faça logout
Para encerrar uma sessão, chame /auth/logout com o sessionToken e o email e, em seguida, remova o token de onde quer que o tenha armazenado. A troca de senha funciona de modo semelhante, por meio de /auth/changePassword. Registrar eventos de autenticação ao longo do caminho oferece um rastro útil se algo der errado.
Checklist de integração de JWT
- A chave de API fica apenas na configuração do servidor, nunca em código do navegador.
- Todo cadastro e login é precedido por uma nova chamada a
/auth/fooBar. - Nenhuma senha ou segredo é colocado nos payloads dos tokens; identifique os usuários com
sube um papel. - O token de sessão é mantido em um cookie HTTP-only ou em outro armazenamento controlado pelo servidor.
- Toda rota protegida valida o token por meio de
/auth/validateantes de fazer qualquer trabalho. - Tokens expirados ou inválidos (401) enviam o usuário de volta ao login.
- O fluxo de 2FA armazena o token de sessão final, não o
tempToken. - Todo o tráfego usa HTTPS, e os tokens nunca são gravados em logs.
Esse é o ciclo completo: autenticar uma vez, carregar um token assinado, verificá-lo no servidor e deixá-lo expirar. Leia o guia de primeiros passos para a referência completa dos endpoints ou veja como outras plataformas abordam o assunto. Quando um token parecer errado, o jwt.io mostrará o que há dentro dele.