A primeira vez que tive que depurar um fluxo de autenticação quebrado em uma API Laravel, perdi uma tarde porque não consegui produzir um token em que confiasse O middleware continuou retornando 401, e não consegui dizer se o bug estava no meu código de verificação ou no token que EU estava alimentando Eu precisava de um JWT conhecido e bom com um específico sub, uma expiração específica, e um segredo que EU controlava, para que EU pudesse isolar um lado do problema Copiar um token aleatório de uma resposta Stack Overflow fez o oposto de ajuda, porque foi assinado com um segredo que EU não tinha.
Essa é a lacuna que um gerador JWT preenche Não é um serviço de assinatura de produção É uma ferramenta de bancada para o momento em que você está construindo ou testando algo que consome JSON Web Tokens e você precisa de um válido sob demanda, com as reivindicações exatas e o segredo exato que você escolhe Este guia cobre como a ferramenta funciona, como um JWT é montado e assinado e os casos práticos em que gerar um token à mão economiza tempo real.
tl;dr: Um gerador JWT transforma uma carga JSON mais um segredo em um token assinado Cole suas reivindicações, escolha HS256, HS384 ou HS512, insira o segredo e copie o token Gerador JWT assina com o navegador Web Crypto API, para que a carga útil e o segredo nunca saiam da sua máquina Use-o para criar tokens de teste com um conhecido
sub, um vencimento definido ou um expirado deliberadamenteexppara exercitar seus caminhos de erro API' s. Para ler um token de volta, emparelhe-o com o decodificador jwt.
O que é um JWT e o que o gerador produz?
Um Token Web JSON é uma forma compacta e segura para URL de representar um conjunto de reivindicações A estrutura é definida pela RFC 7519, e o formulário assinado, que é o que quase todos querem dizer com & quot; a JWT, & quot; é uma Assinatura Web JSON, conforme definido pela RFC 7515 Um token assinado tem três partes unidas por pontos: header.payload.signature.
O cabeçalho é um pequeno objeto JSON nomeando o algoritmo de assinatura e o tipo de token, algo como { "alg": "HS256", "typ": "JWT" }. A carga útil é um objeto JSON de reivindicações: sobre quem é o token, quando ele expira, e quaisquer campos personalizados que seu aplicativo adicione Tanto o cabeçalho quanto a carga útil são codificados em Base64url, que é base64 comum com duas substituições de caracteres e sem preenchimento, exatamente como especifica a RFC 7515. A assinatura é um hash com chave calculado nas duas primeiras partes.
O gerador monta todos os três Você fornece a carga útil e o segredo, ele constrói o cabeçalho, codifica ambos os segmentos, calcula a assinatura e se junta a eles A saída é uma string que você pode soltar diretamente em um Authorization: Bearer cabeçalho, um dispositivo elétrico de teste ou um curl comando.
Uma coisa que vale a pena ser contundente sobre na frente: um JWT assinado é codificado, não criptografado Qualquer um que detém o token pode Base64url-decodificar a carga útil e ler cada reivindicação nele A assinatura não esconde o conteúdo Ele só prova que o conteúdo não foi alterado por alguém sem a chave Nunca coloque uma senha, uma chave API, ou qualquer outra coisa que você não iria mostrar o usuário dentro de uma carga JWT.
Como funciona a assinatura?
Para a família HMAC, que é o que esta ferramenta assina com, a assinatura é HMAC(secret, header + "." + payload). HMAC é uma construção hash com chave definida pela RFC 2104, e a especificação JWA, RFC 7518, mapeia os três nomes de algoritmos JWT nela: HS256 usa HMAC com SHA-256, HS384 usa SHA-384 e HS512 usa SHA-512.
A propriedade importante é a simetria O mesmo segredo tanto cria e verifica a assinatura Quando o seu servidor recebe um token, ele recalcula HMAC(secret, header + "." + payload) sobre os dois primeiros segmentos recebidos e verifica se o resultado é igual ao segmento de assinatura Se um único byte da carga útil foi alterado, o hash recalculado não corresponderá e a verificação falhará Essa é toda a garantia de integridade.
Porque é simétrico, o segredo é o jogo inteiro Qualquer pessoa com o segredo pode cunhar tokens válidos para o seu sistema, por isso o gerador executa a assinatura no seu navegador através da API Web Crypto e nunca transmite o segredo em qualquer lugar Você pode confirmar isso abrindo o seu navegador' s Network tab enquanto você gera um token: não há solicitação Isso importa mais do que parece, porque colar um segredo de assinatura de produção ao vivo em uma ferramenta web aleatória que telefona para casa estaria entregando as chaves para sua autenticação.
RS256 e ES256, os algoritmos assimétricos, funcionam de forma diferente: um sinal de chave privada e uma chave pública correspondente verifica Essas são a escolha certa quando muitos serviços precisam verificar tokens, mas apenas um deve ser capaz de emiti-los Esta ferramenta deliberadamente não os oferece, porque assinar com eles significa colar uma chave privada em uma página da web, e esse é um hábito que vale a pena nunca começar.
Como usar o Gerador JWT
Passo 1: Escreva a carga útil
Insira suas reivindicações como um objeto JSON. Um exemplo mínimo é { "sub": "1234567890", "role": "admin" }. o sub reivindicação é o assunto, geralmente um ID de usuário Você pode adicionar quaisquer campos personalizados que seu aplicativo lê, tais como role, scope, tenant_id, ou email. A ferramenta mantém tudo o que você coloca aqui exatamente como está escrito.
Passo 2: Adicione as reivindicações de tempo
Deixe emitido e os carimbos de ferramentas iat com o tempo atual do Unix. Defina uma expiração em segundos para adicionar um exp reivindicação computada como agora mais aquele deslocamento Para um token de acesso de quinze minutos, digite 900. para um token de uma hora, digite 3600. Estas são as reivindicações que a maioria dos bugs de autenticação se resume, portanto, tê-los computados corretamente, em segundos desde a época, em vez de milissegundos, remove um erro comum.
Passo 3: Escolha o algoritmo e segredo
Escolha HS256 a menos que você tenha um motivo para usar HS384 ou HS512. insira o segredo de assinatura no campo Em seguida, escolha como o segredo é interpretado: texto simples usa os bytes UTF-8 do que você digita, enquanto base64url e hex decodificam a string primeiro em bytes brutos Essa escolha importa porque muitos sistemas armazenam o segredo já codificado por base64, e se você alimentar a string codificada como texto simples, você produzirá uma assinatura que não corresponde.
Passo 4: Copie o token
O JWT assinado aparece junto com uma visualização decodificada do cabeçalho e da carga útil para que você possa confirmar cada reivindicação antes de usá-lo Copie-o e cole-o onde precisar.
Por que gerar um token manualmente?
Testando seu caminho feliz API's
Quando você escreve middleware que valida JWTs, você precisa de um token que seu código deve aceitar Gere um assinado com o mesmo segredo que seu verificador usa, com um válido exp, e confirmar o retorno de solicitação 200. se não, o bug está na sua lógica de verificação, não o token Esta única etapa de isolamento é por isso que EU alcance a ferramenta com mais frequência.
Testando os caminhos de falha
Uma API robusta rejeita os tokens certos pelos motivos certos. Gere um token com um exp já no passado para confirmar que você retorna o erro correto de token expirado Gere um com a nbf no futuro para testar o caminho ainda não-válido Gere um assinado com o segredo errado para confirmar suas execuções de verificação de assinatura Esses casos negativos são os que são enviados não testados, e um gerador faz deles um trabalho de trinta segundos.
Reproduzindo um bug de um usuário específico
O suporte relata um problema que só acontece para contas com uma função específica Gere um token exatamente com isso role reivindicação e o usuário afetado's sub, e você pode reproduzir a solicitação localmente sem tocar nos dados de produção ou pedir ao usuário seu token de portador real, o que você nunca deve fazer de qualquer maneira.
Semeando o desenvolvimento local
Novos desenvolvedores em uma equipe precisam de um token funcional para atingir os endpoints protegidos enquanto o front end auth ainda está sendo construído Um token gerado assinado com o segredo de desenvolvimento local os desbloqueia imediatamente.
HS256 vs HS384 vs HS512: qual você deve usar?
| algoritmo | Hash | Tamanho da assinatura | Comprimento mínimo da chave | Quando usar |
|---|---|---|---|---|
| HS256 | SHA-256 | 32 bytes | 32 bytes | O padrão. rápido, amplamente suportado, seguro para quase todos os usos |
| HS384 | SHA-384 | 48 bytes | 48 bytes | Quando uma política ou padrão requer SHA-384 |
| HS512 | SHA-512 | 64 bytes | 64 bytes | Contextos de alta segurança, ou quando você já padroniza o SHA-512 |
A resposta prática é HS256 a menos que algo externo exija o contrário A RFC 7518 exige que a chave seja pelo menos tão longa quanto a saída de hash, portanto, 32 bytes para HS256, 48 para HS384 e 64 para HS512 O gerador avisa quando seu segredo decodificado é mais curto que o mínimo, porque uma chave curta enfraquece a assinatura independentemente do nome do algoritmo Um algoritmo mais longo e de número superior não corrige um segredo fraco; um segredo aleatório de comprimento próprio é o que importa.
Erros comuns e como evitá-los
O mais frequente é uma incompatibilidade secreta causada pela codificação Sua estrutura armazena o segredo como base64, você cola a string base64 como texto simples e agora os bytes-chave diferem do que seu verificador usa As assinaturas nunca correspondem e você persegue um bug fantasma Corrigi-lo escolhendo a codificação secreta correta na ferramenta para que os bytes de chave bruta sejam idênticos em ambos os lados.
O segundo é confuso segundos e milissegundos As reivindicações de tempo registradas na RFC 7519 são todas medidas em segundos desde a época Unix JavaScript' s Date.now() retorna milissegundos. Se você calcular exp você mesmo e se esqueça de dividir por 1000, seu token parece expirar daqui a cinquenta mil anos, o que alguns verificadores estritos rejeitarão Deixar o gerador calcular as afirmações evita isso inteiramente.
O terceiro é tratar a carga como privada Não é Se você estiver tentado a armazenar um segredo em uma reivindicação, pare Qualquer pessoa com o token pode lê-lo Armazene apenas o que você está confortável com o titular do token vendo, e mantenha dados genuinamente secretos no servidor.
Onde os JWTs se encaixam ao lado de outras ferramentas
Depois de gerar um token, o próximo passo natural é lê-lo de volta. O decodificador jwt divide qualquer token em seu cabeçalho e carga útil e sinaliza um expirado exp, que é como você confirma o gerador produziu o que você pretendia Se você também está gerando segredos, o gerador de hash calcula hashes SHA do lado do cliente e o gerador de senha produz o tipo de longa cadeia aleatória que faz um bom segredo HMAC em primeiro lugar Se você quiser entender o Base64url passo a passo, o Codificador/decodificador Base64 mostra a mesma transformação reversível que transforma o cabeçalho e a carga útil em sua forma codificada. E quando você precisa de um identificador aleatório para cair em um sub ou jti reivindicação, o gerador de uuid dá-lhe um no formato certo.
Para uma imagem mais ampla de por que as ferramentas baseadas em navegador mantêm material sensível fora de servidores de terceiros, o Privacidade de dados em ferramentas online guia explica o modelo do lado do cliente, e o Kit de ferramentas para desenvolvedores web arredonda os utilitários que combinam bem com o trabalho de token.
Como um servidor verifica o token que você gera?
Ajuda a saber o que acontece do outro lado, porque explica porque o segredo e as reivindicações têm que estar exatamente certos Quando sua API recebe um token, uma biblioteca como jsonwebtoken, jose ou PyJWT faz três coisas em ordem Ele divide o token nos pontos e Base64url-decode o cabeçalho para ler o alg. Recompensa a assinatura header.payload usando o segredo configurado e compara-o, byte por byte, com o segmento de assinatura E verifica as reivindicações registradas: is exp no passado, é nbf no futuro, faz iss e aud corresponder ao que a API espera.
Cada uma dessas verificações mapeia para algo que o gerador permite controlar. Se a verificação falhar na assinatura, o segredo ou sua codificação difere entre os dois lados. Se falhar exp, o token expirou, o que você pode ter causado propositalmente para testar esse caminho Se ele falhar alg, você gerou um token com um algoritmo que o verificador não está configurado para aceitar, o que é em si uma coisa útil para descobrir Gerar tokens com variações deliberadas é como você mapeia exatamente qual verificação sua API impõe e qual ela silenciosamente pula.
Uma palavra sobre o alg cabeçalho especificamente. RFC 7515 define none como um algoritmo válido para um token não assinado, as primeiras bibliotecas confiariam em um token reivindicado alg: none e pule a verificação inteiramente Essa é a vulnerabilidade clássica do JWT As bibliotecas modernas a rejeitam por padrão, mas o gerador oferece o none opção precisamente para que você possa disparar um token não assinado em sua API e confirme que diz não. Se sua API aceitar um, você encontrou um bug sério.
Como você deve lidar com segredos e armazenamento de tokens?
O segredo com o qual você assina merece o mesmo cuidado que uma senha de banco de dados Um bom segredo HMAC é uma string longa e aleatória, não uma frase memorável, porque a segurança HMAC depende da chave ser inadivinhável Gerar uma com uma ferramenta de senha e armazená-la na configuração do seu ambiente, nunca no controle de origem, é a linha de base Quando você a gira, lembre-se de que todo token assinado com o segredo antigo se torna inválido no momento em que o verificador muda, e é por isso que os sistemas de produção geralmente suportam mais de um segredo válido durante uma janela de rotação.
No lado do cliente, onde você armazena o token acabado é importante tanto quanto a forma como você o assina Um token em localStorage é legível por qualquer JavaScript na página, portanto, uma única falha de script entre sites entrega a um invasor uma credencial válida An httpOnly, Secure, SameSite cookie é invisível para scripts, que fecha esse caminho ao custo de precisar de proteção CSRF O padrão comum é um token de acesso de curta duração mantido na memória e um token de atualização de longa duração em um httpOnly cookie. nada disso altera a forma como você gera um token, mas é o contexto que torna um token gerado seguro para uso, em vez de um passivo.
FAQ
Como faço para gerar um JWT?
Cole suas reivindicações como um objeto JSON, escolha um algoritmo de assinatura como HS256 e insira o segredo A ferramenta base64url-codifica o cabeçalho e a carga útil, calcula a assinatura HMAC e retorna o token finalizado para você copiar Tudo é executado em seu navegador.
Quais algoritmos de assinatura são suportados?
HS256, HS384 e HS512, a família HMAC, além de um & quot; none" opção para teste. RS256 e ES256 não são oferecidos deliberadamente porque assinam com uma chave privada, e colar uma chave privada em uma página da web é um risco de segurança melhor evitado.
O meu segredo é enviado para um servidor?
Não. A assinatura é executada inteiramente no seu navegador por meio da API Web Crypto, portanto, o segredo e a carga útil nunca saem do seu dispositivo. Você pode confirmar isso na guia Rede DevTools e a ferramenta continua funcionando offline depois de carregada.
Como defino o token para expirar?
Insira uma expiração em segundos e a ferramenta adiciona um exp reivindicação igual ao tempo atual mais que muitos segundos Para um token de quinze minutos digite 900. deixe o campo vazio para omitir exp inteiramente.
Por que o segredo deveria ter pelo menos 32 bytes?
RFC 7518 requer uma chave HMAC pelo menos tão longa quanto a saída hash, que é de 32 bytes para HS256, 48 para HS384 e 64 para HS512. um segredo mais curto enfraquece a assinatura, então a ferramenta avisa quando o segredo decodificado é muito curto.
Posso criar um token não assinado?
Sim. Selecione alg none e a ferramenta produz um cabeçalho.payload. token com uma assinatura vazia Isso é apenas para testar como sua API lida com tokens não assinados; a maioria das bibliotecas rejeita alg: none por padrão, e você também deve.
Um JWT gerado é criptografado?
No. Um JWT assinado é codificado, não criptografado: qualquer um pode base64url-decodificar o cabeçalho e carga útil e ler cada reivindicação A assinatura só prova que o conteúdo não foi alterado Nunca coloque senhas ou segredos dentro da carga útil.
