Ferramentas de desenvolvedor · Decodificador JWT
Depurando um 401: o que verificar em um JWT decodificado antes de culpar o API
· Por que é importante
jwt depuração autenticação
A maioria das rejeições de tokens se resume a alguns problemas de reivindicação que você pode identificar lendo a carga útil. Este post traz um checklist, desde o vencimento até o público até os erros de copiar e colar, para verificá-los.
Funcionou ontem — o 401 que aparece sem alteração de código
Um 401 que aparece sem uma alteração no código do cliente pode ter origem na idade do token, na política do emissor, na rotação de chaves, na seleção de público ou em uma cópia danificada. Comece com evidências em vez de presumir que API está inoperante. Preserve os detalhes da resposta e os identificadores de correlação antes de manipular a credencial.
Decodifique apenas uma cópia expirada, sintética ou adequadamente controlada. ToolAcre pode expor pistas estruturais e de reivindicação, mas não pode identificar todas as rejeições do servidor porque não possui chave, política do emissor ou logs API. A lista de verificação restringe as perguntas; isso não substitui o veredicto do servidor de recursos.
Copie os erros primeiro - prefixos 'Bearer', novas linhas finais e tokens truncados
Verifique primeiro o valor copiado. ToolAcre corta os espaços em branco ao redor e remove um prefixo `Bearer ` que não diferencia maiúsculas de minúsculas, que lida com uma pasta de cabeçalho de autorização comum. Em seguida, são necessários exatamente três segmentos separados por pontos. Uma contagem errada aponta para truncamento, forma de token errada ou pontuação extra antes do início da análise da reivindicação.
Um cabeçalho ou carga vazia falha especificamente. Base64url inválido, UTF-8 inválido e JSON inválido têm erros separados. Essas distinções ajudam a determinar se o transporte danificou o token. A assinatura pode estar malformada sem bloquear a inspeção, mas esse aviso continua sendo uma provável falha de verificação, exigindo confirmação do lado do servidor.
exp e nbf: inspecionam valores baseados em segundos sem transformar a exibição em um veredicto de validade
Inspecione os valores numéricos `exp` e `nbf` a seguir. ToolAcre multiplica segundos por 1,000, mostra UTC e rotula uma expiração anterior ou não antes futura em relação ao relógio do navegador. Um valor de treze dígitos pode revelar que milissegundos foram gravados onde segundos eram esperados.
Não promova esses rótulos para fiscalização. Um token forjado pode reivindicar uma expiração futura e o servidor pode usar um relógio ou política de margem de manobra diferente. A exibição identifica aritmética que vale a pena comparar com registros confiáveis; a verificação criptográfica deve ser bem-sucedida antes que as reivindicações possam influenciar a aceitação.
aud e iss — este token é para este API, do emissor em que API confia?
`aud` deve identificar o destinatário pretendido de acordo com a política de API, enquanto `iss` deve corresponder ao relacionamento do emissor confiável. ToolAcre lista ambos como valores decodificados e explica seus significados registrados. Ele não os compara com uma configuração API nem vincula uma string do emissor a um conjunto de chaves.
Um emissor URL plausível e um nome de público podem ser fabricados. Compare os valores exatos decodificados com as expectativas configuradas do servidor somente após preservar o limite de verificação de assinatura. Se vários serviços compartilham infraestrutura de identidade, as verificações de audiência são especialmente importantes para evitar que um token válido para um serviço seja usado em outro.
O tipo de token pode ser sugerido por cabeçalhos e declarações, mas a decodificação não pode autenticar essa classificação
Um token de ID e um token de acesso podem parecer JWTs de três partes. Cabeçalho `typ`, público, escopos e reivindicações específicas do perfil podem sugerir qual você possui. ToolAcre avisa sobre uma string inesperada `typ`, mas não implementa classificação de token OpenID Connect ou OAuth.
Use a documentação do emissor e o fluxo do cliente para estabelecer o tipo de token esperado. O envio de um token de ID para API pode falhar mesmo quando sua assinatura for válida para o provedor de identidade. A decodificação auxilia no diagnóstico; ele não pode autenticar o rótulo de tipo ou conceder autoridade API.
kid após rotação de chave — um token válido que faz referência a uma chave que o servidor não possui mais
Após a rotação da chave, um cabeçalho `kid` pode referir-se a uma chave ausente do conjunto confiável atual do servidor. Leia o identificador e inspecione o cache e os logs de conjunto de chaves no verificador. Não busque um URL fornecido pelo cabeçalho nem aceite material de chave incorporado como uma solução alternativa rápida.
Um token assinado corretamente ainda pode falhar se o verificador não conseguir localizar a chave permitida, enquanto um invasor pode escrever qualquer `kid` em um cabeçalho não verificado. O valor é uma dica de pesquisa limitada pela configuração do emissor confiável, e não uma evidência de que uma chave específica deve ser acreditada.
Exemplo resolvido - executando um token rejeitado por meio da lista de verificação no decodificador ToolAcre JWT
Para uma triagem bem-sucedida, pegue um token rejeitado controlado, confirme três segmentos, inspecione os erros e registre `exp`, `nbf`, `aud`, `iss`, `typ` e `kid` sem editá-lo. Compare cada campo com o destino da solicitação API e a configuração confiável do verificador. Mantenha os logs do servidor abertos para a categoria de falha real.
Se todos os valores visíveis parecerem esperados, não conclua que API está errado. Corrupção de assinatura, material de chave incorreto, estado revogado ou política não mostrada ainda podem explicar o 401. O `signatureVerified` de ToolAcre permanece falso, independentemente de quão organizado o JSON pareça.
O que isso não cobre e a conclusão: um decodificador não pode dizer se a assinatura é válida; a lista de verificação encontra problemas de reivindicação e falhas de assinatura precisam de logs do servidor
Um decodificador não pode dizer se a assinatura é válida. Sua lista de verificação de declarações encontra problemas de cópia e carga útil que são visíveis sem uma chave; falhas de assinatura e decisões políticas autorizadas precisam de evidências do servidor. Trate uma decodificação como uma observação diagnóstica entre várias.
O caminho mais rápido e confiável é ordenado: preservar o contexto da resposta, inspecionar o formato do token, comparar as unidades de tempo e, em seguida, comparar o emissor, o público, o tipo e o identificador de chave com a configuração confiável. Pare de confiar até que o verificador real confirme a criptografia e a política.