Na primavera passada, os usuários começaram a sair do Toolz.dev. Às vezes não - constantemente. Faça login, clique em uma ferramenta, boom: de volta à tela de login. O backend emite tokens de acesso de 15 minutos e tokens de atualização de 7 dias, e I' e testei esse fluxo cem vezes. Então, naturalmente, presumi que o endpoint de atualização estava quebrado e passei uma hora e quarenta minutos lendo middleware Express que não tinha nada de errado com ele.
Então eu finalmente fiz a coisa óbvia. Peguei um token de acesso ao vivo no cabeçalho de autorização, colei-o em um decodificador e examinei as reivindicações. o exp estava bem. o iat estava bem O token era válido por mais 14 minutos O que significava que o servidor estava bem - e o bug tinha que estar no cliente Com certeza: meu frontend estava verificando payload.exp < Date.now(). exp é segundos desde a época. Date.now() é milissegundos. Cada token recém-cunhado parecia ter expirado em algum lugar por volta de 1970, então o cliente & quot; helpfully" desconectou todos antes que o servidor tivesse uma palavra a dizer. Três caracteres de correção - /1000- depois de quase duas horas de caça.
Isso & #39; é todo o pitch para ter um decodificador JWT em sua caixa de ferramentas Um JWT parece ruído de linha - três pedaços de gibberish base64url colados com pontos - mas ele & #39; é apenas JSON vestindo um trench coat No momento em que você pode ler as reivindicações, metade dos seus bugs auth deixar de ser mistérios Público errado, token expirado, papel ausente, inclinação do relógio, milissegundos-vs-segundos - eles & #39; estão todos sentados bem ali em texto simples, uma vez que você decodificar.
Mas - e isso importa - onde você decodifica não é uma escolha neutra Um token de acesso real é uma credencial ao vivo Cole-o em um site decodificador que envia tokens para um servidor, e você & #39; acabei de depositar uma chave de trabalho para sua API em um estranho & #39; s registros de solicitação That & #39; s a razão específica que EU construí o Decodificador Toolz.dev JWT para ser executado inteiramente no seu navegador. Mais sobre isso abaixo.
tl;dr: Para decodificar um JWT online, cole-o no Decodificador Toolz.dev JWT- ele divide cabeçalho, carga útil e assinatura instantaneamente, traduz
exp/iatem datas humanas, e executa 100% client-side para que o token nunca saia da sua máquina Uma coisa para gravar na memória: decodificação NÃO é verificar Um JWT é apenas JSON codificado por base64url que qualquer um pode ler - apenas a verificação de assinatura com a chave prova isso' s confiável.
Principais características
Cabeçalho instantâneo, carga útil e divisão de assinatura
Cole um token e o decodificador imediatamente o quebra em suas três partes: o cabeçalho (tipo de algoritmo e token), a carga útil (suas reivindicações) e a assinatura (codificada à esquerda, porque ele & #39; s é um MAC bruto ou assinatura - lá & #39; s nada legível por humanos lá).Nenhum botão de envio, nenhuma recarga de página Isso espelha exatamente o que sua biblioteca de autenticação faz internamente antes da verificação: dividir em ., base64url-decodificar os dois primeiros segmentos, analisar como JSON. ver as partes dispostas lado a lado é a maneira mais rápida de construir intuição para o formato Depois de algumas dezenas de tokens, você & #39; vou começar a reconhecer um token RS256 Auth0 versus um token HS256 Laravel em um relance - o cabeçalho dá-lo sempre.
Selo de horas EXP, IAT e NBF legíveis por humanos
O recurso mais útil, ponto final. exp, iat, e nbf os valores NumericDate - segundos desde a época do Unix - e ninguém, inclusive eu, consegue ler 1783430700 E diga se é na próxima terça-feira ou na morte por calor do universo. O decodificador converte todas as reivindicações de timestamp em uma data e hora reais, em seu fuso horário local e UTC. É aqui que o bug clássico de milissegundos em relação ao segundo se torna visível instantaneamente: se você decodificou exp Renders como uma data no ano 56.000 e algo, alguém colocou um JavaScript Date.now() em um campo que espera segundos. Eu enviei esse bug. Ver a data absurda é o diagnóstico. Para uma arqueologia mais profunda do carimbo de data/hora, o conversor de carimbo de data/hora está a uma guia de distância.
Contagem regressiva e status de expiração
Além de apenas renderizar a data, o decodificador informa o estado atual do token: válido, expirado ou ainda não-ativo (quando nbf está no futuro).Se o token' s ainda vivo, você obtém uma contagem regressiva para expirar Isso soa como uma pequena conveniência até que você' está depurando um 401 intermitente e precisa responder & quot; foi este token específico morto quando o pedido disparou?" mais e mais. Comparando a contagem regressiva contra o seu servidor' s TTL configurado também pega configuração incorreta rapidamente - se seus tokens de acesso devem viver 15 minutos e a contagem regressiva diz 6 dias, seu código emissor está lendo o valor de configuração errado.
Inspeção de algoritmo e cabeçalho
O cabeçalho decodificado mostra alg e typ (mais kid e amigos quando presentes), que respondem a perguntas que são importantes para a segurança, não apenas para depuração. Este é o token HS256 ou RS256? faz o kid Corresponder a uma chave que seu endpoint JWKS realmente serve? E o grande: é alg algo que nunca deveria ser, como none? Tokens reivindicando "alg": "none" são dispositivos de teste ou alguém sondando seu verificador - de qualquer forma, você deseja vê-lo imediatamente. Verifico o cabeçalho primeiro em cada token desconhecido, antes de ler uma única reivindicação.
Reivindicações JSON formatadas e destacadas por sintaxe
As cargas úteis decodificadas brutas são blobs JSON de linha única e os provedores de identidade adoram embalá-los: objetos aninhados, reivindicações personalizadas com names, arrays de escopos. O decodificador imprime tudo com realce de sintaxe, então roles, scope, aud Arrays e objetos de permissão aninhados são realmente escaneados. É o mesmo tratamento que o formatador json dá JSON arbitrário, aplicado automaticamente às suas reivindicações Quando você & #39;re comparando dois tokens - digamos, um de um usuário que pode acessar um endpoint e um de um usuário que pode & #39; t - saída formatada transforma um exercício de apertar os olhos em uma diferença de dez segundos.
100% do lado do cliente - seu token nunca sai do navegador
Este é o recurso pelo qual I' d luta. Um token de acesso colado não são dados de amostra - it' s uma credencial ao vivo que se autentica como um usuário real até exp. Qualquer decodificador que poste seu token em um back-end acabou de escrever uma chave de trabalho em logs do servidor, análises, talvez um rastreador de erros de terceiros. O decodificador Toolz.dev faz toda a decodificação em JavaScript, em sua guia. Nada é transmitido, nada é armazenado. Não acredite na minha palavra: abra o DevTools, observe a guia Rede, cole um token. zero solicitações. Eu escrevi por que essa arquitetura é importante para todas as ferramentas de entrada sensível em Minha peça sobre privacidade de dados em ferramentas online.
Funciona com qualquer JWT, de qualquer pilha
JWTs são um padrão - RFC 7519- então o decodificador não & #39; t importa quem cunhou o seu Auth0 e Firebase tokens com seus namespaced reivindicações personalizadas, Laravel Sanctum-adjacente configurações, Keycloak, Supabase, AWS Cognito, ou os tokens HS256 enrolados à mão meu próprio Express back-end sinais para Toolz.dev - se ele & #39; s três segmentos base64url unidos por pontos, ele decodifica Isso inclui malformado quase-JWTs: se segmento dois won & #39; t analisar como JSON, o decodificador diz-lhe qual parte é quebrada em vez de falhar silenciosamente, que é em si diagnóstico tokens truncados-on-copy são mais comuns do que você & #39; d pensar.
Como usar o decodificador JWT
Passo 1: Pegue o token
Encontre o token onde quer que seu aplicativo o guarde. Mais comumente: DevTools → Guia de rede → Clique em uma solicitação → Copiar o Authorization: Bearer eyJ... valor do cabeçalho (sem a palavra & quot; Bearer").Ou verifique Application → Local Storage / Cookies, uma vez que muitos aplicativos guardam tokens lá No backend, registre-o ou puxe-o de sua suíte de testes Copie toda a string - um JWT que perde seus últimos caracteres ainda decodifica, mas nunca verificará, e isso ' é uma hora confusa que você não & #39; precisa.
Passo 2: Cole-o
abra o decodificador jwt e colar. A decodificação acontece enquanto você digita - sem botão. Se você & #39; estiver nervoso em colar um token de produção em qualquer lugar (bom instinto), abra primeiro a guia Rede e confirme se nada é transmitido. É & #39; t. Essa verificação de paranóia leva dez segundos e é & #39; é exatamente o que eu e #39; d fazem em outra pessoa & #39; s ferramenta.
Passo 3: leia as três partes
Cabeçalho primeiro: confirme alg é o que seu sistema espera e typ é JWT. Em seguida, a carga útil: iss (que o cunhou), aud (para quem é) sub (qual usuário), além de quaisquer funções, escopos ou reivindicações personalizadas que sua pilha adiciona A assinatura permanece codificada - saída criptográfica it' s, não dados Se o cabeçalho disser none, pare e vá verificar a lista de permissões do seu verificador antes de qualquer outra coisa.
Etapa 4: verifique a EXP e as alegações que mordem
Olhe para o decodificado exp Data e o status de expiração. expirou? Aqui está o seu 401. Válido, mas rejeitado de qualquer maneira? agora compare aud e iss contra o seu verificador & #39; s config - incompatibilidades, há a segunda causa mais comum após o vencimento. E se algum carimbo de data/hora for traduzido como um ano de cinco dígitos, parabéns: você e #39; encontrei um bug de milissegundos contra segundos e, por meio deste, recebo você em um clube muito grande.
O que está realmente dentro de um JWT? Anatomia das três partes
Um token da Web JSON, definido no RFC 7519, é três segmentos codificados em base64URL unidos por pontos: header.payload.signature. (Estritamente, a variedade assinada é um JWS de acordo com a RFC 7515 - there' s um primo criptografado, JWE, mas quase todos os tokens que você e #39; se encontrarão na natureza são JWS assinados.)
A palavra-chave é codificado. Base64url é uma codificação de transporte - uma maneira reversível de tornar os bytes seguros para URL - não criptografia Qualquer pessoa que possua um JWT pode ler tudo no cabeçalho e na carga útil com zero chaves, zero segredos, zero esforço Jogue com a codificação bruta no conversor de base64 E você verá que é o alfabeto padrão com + e / trocado por - e _, o preenchimento caiu. Eu escrevi mais sobre a codificação em si no Guia de codificação de base64.
Decodifique um cabeçalho típico e você terá:
{ "alg": "HS256", "typ": "JWT" }
E uma carga útil construída a partir das reivindicações registradas RFC 7519 define:
{
"iss": "https://toolz.dev",
"sub": "user_8f3a2c",
"aud": "toolz-api",
"exp": 1783431600,
"nbf": 1783430700,
"iat": 1783430700,
"jti": "b4d1f0e2"
}
iss é o emissor, sub O assunto (geralmente seu ID de usuário), aud O público-alvo, jti Um ID de token exclusivo. exp, nbf, e iat são valores numéricosData: segundos Desde a época do Unix. Não milissegundos. JavaScript Date.now() Retorna milissegundos e confundindo os dois produz tokens que expiram instantaneamente (meu bug do logout do Toolz.dev) ou tokens com exp datas no ano 56.000 que efetivamente nunca expiram - o que é silenciosamente o fracasso mais perigoso.
HS256 vs RS256. HS256 assina com um HMAC sobre um segredo compartilhado - rápido, simples, mas cada serviço que verifica tokens também mantém o segredo, e qualquer pessoa que tenha o segredo pode cunhar moedas fichas. Tudo bem para um monolito como meu back-end, onde o emissor e o verificador são o mesmo processo. RS256 assina com uma chave privada e verifica com uma pública, para que você possa publicar a chave pública (via JWKS) e deixe uma dúzia de microsserviços verificar sem que nenhum deles seja capaz de falsificar. Os sistemas distribuídos e os deslocados internos de terceiros devem estar em RS256 ou em seus irmãos ECDSA/EDDSA.
o alg: none ataque. RFC 7519 permite JWTs não seguros onde alg é none E a assinatura está vazia. As primeiras bibliotecas confiavam no cabeçalho alg Cegamente, os atacantes despojaram a assinatura, set alg até none, e navegou por meio de verificação com reivindicações totalmente controladas pelo invasor. Um truque relacionado troca RS256 por HS256, portanto, o verificador usa o público chave como um segredo HMAC. é por isso que RFC 8725 - JSON Web Token Melhores Práticas Atuais - é contundente: o verificador deve fixar seus algoritmos permitidos no código e nunca deixar o token escolher Se sua chamada de biblioteca does' t incluir um explícito algorithms lista, corrija isso hoje.
Decodificação vs verificação - a linha que importa. Decodificar é ler; verificar é confiar. A diferença de código:
// Decoding: no secret, no trust. Anyone can do this.
const payload = JSON.parse(
Buffer.from(token.split('.')[1], 'base64url').toString()
);
// Verifying: proves the signature AND pins the algorithm.
const verified = jwt.verify(token, secret, { algorithms: ['HS256'] });
Um decodificador online faz a primeira coisa Ele pode mostrar-lhe as reivindicações; ele não pode - e não deve fingir - dizer-lhe o token é autêntico Apenas verify, com a chave, faz isso. Nunca tome decisões de autorização de reivindicações descodificadas, mas não verificadas.
O que leva à última regra: Nunca coloque segredos em uma carga útil JWT. Sem senhas, sem chaves de API, sem dados você' d mente um invasor lendo A carga útil é pública por construção - assinada contra adulteração, aberta à leitura Se ele' s no token, suponha que toda a internet possa vê-lo.
Casos de uso comuns
Depuração de 401s durante o desenvolvimento da API
O 401 é o código de status menos informativo em HTTP O servidor disse que não - mas o token expirou? público errado? assinado com uma chave obsoleta? faltando inteiramente porque seu interceptador não & #39; t disparar? decodificar o token real da solicitação com falha colapsa o espaço de busca em segundos Metade do tempo exp responde sozinho. A outra metade comparando iss e aud Contra o ambiente, a configuração do verificador encontra um token dev sendo reproduzido no teste de teste ou vice-versa. Eu mantenho o decodificador fixado ao lado do meu cliente HTTP exatamente para esse loop; é uma entrada principal no meu Kit de ferramentas de depuração de API. Decodifique primeiro, leia o middleware em segundo lugar - a ordem inversa me custou uma hora e quarenta minutos uma vez, e pretendo continuar coletando interesse nessa lição.
Explicando os logouts surpresa
Quando os usuários relatam, ele continua me desconectando," os timestamps do token são sua declaração de testemunha. Decodifique um novo token de acesso e verifique o intervalo entre iat e exp- são realmente os 15 minutos que você configurou, ou fez um env var sobrepô-lo para 60 segundos? em seguida, verifique se o token de atualização' s janela de 7 dias é o que você acha que é A distorção do relógio aparece aqui também: se o seu servidor emissor' s relógio corre um par de minutos rápido, tokens chegam já antigos pelo cliente' s acerto de contas E, claro, o bug de comparação segundos-vs-milissegundos - aquele que bit Toolz.dev - anuncia-se o momento em que você vê um perfeitamente válido exp Em um token, seu cliente jura expirou.
Auditando o que seu provedor de identidade coloca em tokens
A maioria das equipes nunca leu os tokens de suas casas da moeda IdP, e vale a pena fazer isso e #39; Decodifique um e você poderá encontrar endereços de e-mail, nomes completos, URLs de imagens, identificadores de inquilinos - PII acompanhando cada solicitação de API, armazenados no armazenamento local e legíveis por qualquer coisa que coloque as mãos no token. Aqui e #39; minha postura opinativa e eu e #39; discutirei com qualquer pessoa: don' coloque e-mails de usuários nas cargas úteis do JWT. O sub A afirmação existe precisamente para que você possa carregar um identificador opaco e procurar o lado do servidor de detalhes humanos. Cada reivindicação extra é dados que você está transmitindo e bytes que você está pagando em cada solicitação. Decodifique, faça uma auditoria e vá aparar os mapeamentos de reivindicações do seu IDP.
Verificando funções e escopos durante a depuração da autorização
A autenticação diz quem você é; a autorização diz o que você pode fazer - e quando a autorização se comporta mal, a resposta está nas reivindicações O usuário jura que eles' são um administrador, mas recebe 403 s? decodifique seu token Se role afirma user, o token foi cunhado antes da promoção e eles precisam fazer o login novamente - uma consequência clássica de tokens sem estado carregando instantâneos obsoletos Se o papel estiver presente, mas o acesso ainda falhar, verifique o nome e a forma exatos da reivindicação: roles VS role, matriz vs string, scope Como uma string delimitada por espaço VS scp como uma matriz. Verificação de middleware payload.roles.includes('admin') contra uma carga útil que role: "admin" falha silenciosa e irritantemente Dois tokens decodificados lado a lado - um funcionando, outro não - geralmente o resolvem em menos de um minuto.
Comparando o acesso e atualizando o conteúdo do token
Em uma configuração de dois tokens como a minha, os dois tokens devem ter uma aparência significativamente diferente, e decodificar ambos é a auditoria. O token de acesso: curto exp, além de quaisquer reivindicações que a API precise por solicitação. O token de atualização: longo exp, um jti para o acompanhamento de revogação, e o mais próximo possível de nada mais Se o seu token de atualização estiver carregando funções e dados de perfil, algo' s desligado - it' s só apresentou a um endpoint e deve' t duplicar o token de acesso' s trabalho Este side-by-side check também pega a classe de bug embaraçoso onde ambos os tokens acidentalmente obter o mesmo TTL, que transforma seu " janela de acesso de 15 minutos" em teatro de segurança Pergunte-me como EU sei verificar para que um.
JWT vs Opaco Tokens de Sessão: Uma Comparação Honesta
| JWT | Token de sessão opaco | |
|---|---|---|
| estado de apatridia | Autocontido; qualquer servidor com a chave verifica sem uma pesquisa | O servidor (ou uma loja compartilhada como o Redis) deve pesquisar todas as solicitações |
| revogação | Difícil - válido até exp A menos que você crie uma lista de negação, o que reintroduz o estado |
Trivial - exclua o registro do lado do servidor, o token morre instantaneamente |
| Tamanho por solicitação | Centenas de bytes a mais de um kilobyte, em todos pedido | ~32–64 bytes |
| Onde a validação acontece | Em qualquer lugar que contenha a chave (pública) - ótimo para microsserviços | Onde quer que a loja da sessão viva |
| Reivindicar frescura | Instantâneo na hora do problema; as alterações de função aguardam o reenvio | Sempre atual - lê dados ao vivo |
| depuração | Decodificar e ler reivindicações instantaneamente | Opaco por design; requer acesso à loja |
Eu uso JWTS para Toolz.dev e ainda lhe direi que eles estão prescritos em excesso. A história de revogação é realmente ruim: quando você bani um usuário, o token de acesso deles continua funcionando até exp- é exatamente por isso que meus tokens de acesso vivem 15 minutos e o token de atualização de 7 dias é a coisa que posso matar no lado do servidor Esse híbrido é o padrão honesto: JWTs sem estado de curta duração para verificação barata, um ponto de verificação com estado para controle Se você & #39; estiver executando um monólito com um banco de dados, as sessões simples são mais simples, menores e instantaneamente revogáveis - o superpoder JWT & #39; da verificação distribuída está resolvendo um problema que você não tem & #39; tem.
Enquanto nós 're comparando - HS256 vs RS256 em uma olhada:
| HS256 | rs256 | |
|---|---|---|
| Modelo de chave | Um sinal secreto compartilhado e verifica | Sinais de chave privada, chave pública verifica |
| Quem pode cunhar fichas | Qualquer um segurando o segredo | Apenas o porta-chaves privados |
| melhor ajuste | Serviço único, emissor = verificador | Microsserviços, IdPs de terceiros, JWKs |
| Tamanho/velocidade da assinatura | menor, mais rápido | Maior, mais lento, mais seguro para distribuir |
Perguntas frequentes
É seguro colar um JWT em um decodificador online?
Somente se o decodificador executar client-side Um token real é uma credencial ao vivo - enviando-o para alguém' s server planta uma chave de trabalho em seus logs O Toolz.dev JWT Decoder faz toda a decodificação em seu navegador e não transmite nada; você mesmo pode confirmar isso assistindo a guia Rede enquanto você cola Para decodificadores você pode' t verificar, usar tokens expirados ou de teste apenas.
Você pode decodificar um JWT sem o segredo?
Sim - que & #39; s o ponto que as pessoas mais perdem O cabeçalho e carga útil são base64url-codificado JSON, e codificação não é criptografia Qualquer um pode ler cada reivindicação sem qualquer chave O segredo (ou chave privada) só é necessário para criar ou verificar a assinatura Decodificação não requer nada; confiar requer verificação.
Qual é a diferença entre decodificar e verificar um JWT?
A decodificação lê o conteúdo: dividido em pontos, base64url-decode, parse JSON. Verificar autenticidade prova: recalcule ou verifique a assinatura usando a chave secreta ou pública, confirme o algoritmo, verifique a expiração. Um decodificador mostra o que um token afirma; apenas a verificação, feita do lado do servidor com a chave, informa se deve acreditar. Nunca autorize com base em reivindicações decodificadas, mas não verificadas.
Por que meu JWT mostra como inválido ou expirado?
Na maioria das vezes, o exp foi genuinamente aprovado - decodifique-o e verifique a data. Próximos suspeitos: um token truncado de uma pasta de cópia desleixada, um aud ou iss Isso não corresponde à configuração do verificador, à distorção do relógio entre os servidores ou a uma assinatura de uma tecla girada. Se o decodificado exp Parece bom, mas seu código rejeita o token, verifique se você está comparando segundos com milissegundos.
Os JWTs são criptografados?
JWTs padrão - tecnicamente JWS, por RFC 7515 - são assinados, não criptografados A assinatura detecta adulteração, mas não esconde nada; a carga útil é legível por qualquer pessoa Uma variante criptografada (JWE) existe, mas é rara em autenticação típica da web Regra prática: tratar cada carga JWT como pública e nunca colocar senhas, chaves de API ou dados confidenciais em uma.
Em que formato a reivindicação EXP está?
exp É um número: segundos desde o UNIX EPOCH (1 de janeiro de 1970 UTC), conforme definido na RFC 7519. O mesmo para iat e nbf. O bug clássico está usando o JavaScript Date.now(), que retorna milissegundos - produzindo tokens que parecem expirados instantaneamente ou carregam datas de validade por volta do ano 56.000. Se um carimbo de data/hora decodificado mostrar um ano de cinco dígitos, esse & #39; é o seu bug.
O que é o ataque ALG None?
RFC 7519 permite JWTs não seguros com "alg": "none" E uma assinatura vazia. Bibliotecas antigas confiavam no campo de algoritmo do cabeçalho, então os atacantes tiravam assinaturas, set alg até none, e passou a verificação com reivindicações forjadas. RFC 8725, as melhores práticas atuais do JWT, exige que os verificadores fixem uma lista de permissão explícita de algoritmos no código e ignorem o que o token pedir.
Devo usar HS256 ou RS256?
HS256 usa um segredo compartilhado para assinatura e verificação - simples e rápido, certo para um único serviço que tanto emite e verifica seus próprios tokens RS256 sinais com uma chave privada e verifica com um público, tantos serviços podem verificar sem ser capaz de forjar Regra de ouro: monolith, HS256; microsserviços ou provedor de identidade de terceiros, RS256.
Embrulhando
eu construí o decodificador jwt porque EU continuei precisando dele enquanto construía o próprio Toolz.dev - os mesmos tokens de acesso de 15 minutos e tokens de atualização de 7 dias I & #39; tem sido dissecando ao longo deste guia Ele decodifica instantaneamente, traduz os carimbos de data/hora que causam 90% da confusão, e nunca envia seu token para qualquer lugar Essa última parte é & #39; t uma caixa de seleção de recursos; para uma ferramenta que lida com credenciais ao vivo, ele & #39; s todo o design.
Se os tokens fizerem parte da sua depuração diária, os vizinhos também ganharão seu sustento: o conversor de carimbo de data/hora Para a arqueologia da época, o conversor de base64 Para cutucar os segmentos brutos, o formatador json Para blobs de reivindicação, e o gerador de haxixe Quando você está trabalhando com resumos. Para um fluxo de trabalho mais amplo, meu Guia de ferramentas de depuração de API Cobre onde um decodificador se encaixa no loop.
E mantenha a versão de uma frase gravada no monitor: a decodificação informa o que um token diz, a verificação informa se deve acreditar. Confunda os dois e você enviará o tipo de bug que acaba sendo a anedota de abertura na postagem do blog de alguém. Desta vez foi meu.
