Estrutura e Funcionamento de um JSON Web Token
Um JSON Web Token (JWT) é um padrão aberto (RFC 7519) utilizado para partilhar informações de forma compacta e segura entre duas partes. O token é composto por três partes distintas, separadas por pontos (.): o cabeçalho (header), a carga útil (payload) e a assinatura.
A estrutura visual de um JWT segue o formato cabeçalho.payload.assinatura. Cada uma destas secções é codificada individualmente utilizando o formato Base64URL. Este método de codificação transforma dados binários ou texto JSON numa cadeia de caracteres segura para transmissão em URLs, substituindo caracteres como + e / por - e _, respetivamente, e omitindo o preenchimento com =.
O Descodificador JWT lê esta cadeia de caracteres, identifica as divisões criadas pelos pontos e reverte a codificação Base64URL para apresentar o conteúdo original em formato JSON legível.
O Cabeçalho do JWT e os seus Metadados
O cabeçalho é a primeira parte do token e define os metadados sobre como a assinatura deve ser tratada. Esta secção é um objeto JSON que contém tipicamente duas propriedades principais:
- Algoritmo (
alg): Indica o algoritmo criptográfico utilizado para criar a assinatura, como HS256 (HMAC com SHA-256) ou RS256 (RSA com SHA-256). - Tipo (
typ): Declara o tipo de objeto, que no caso destas estruturas é habitualmente "JWT".
Ao introduzir o token na ferramenta, o cabeçalho é descodificado e formatado como JSON estruturado. O sistema extrai diretamente estes valores para preencher os campos informativos de Algoritmo e Tipo na interface.
A Carga Útil (Payload) e as Claims de Tempo
A carga útil constitui o corpo do token e aloja as declarações (claims) sobre a entidade (geralmente o utilizador) e quaisquer dados adicionais necessários para a aplicação. Estas claims dividem-se em três categorias: registadas, públicas e privadas.
As claims de tempo são fundamentais para a segurança e controlo de acessos. O descodificador analisa especificamente duas destas propriedades numéricas (representadas em formato Unix Timestamp):
- Emitido em (
iat): A propriedade issued at indica o momento exato em que o token foi gerado. A ferramenta traduz este valor num formato de data e hora legível no campo Emitido em. - Expira em (
exp): A propriedade expiration time define o limite de validade do token. O descodificador utiliza esta informação para calcular o estado temporal do JWT.
Estados de Validade Temporal do Token
Com base na presença e no valor da claim exp, a ferramenta avalia o estado do token em relação ao momento atual e atribui um dos seguintes indicadores de estado:
| Estado | Condição de Atribuição |
|---|---|
| Válido | O tempo atual é anterior à data definida na claim exp. |
| Expirado | O tempo atual ultrapassou a data definida na claim exp. |
| Ainda não é válido | O token possui uma restrição temporal ativa que impede a sua utilização imediata. |
| Sem expiração | O payload do token não contém a claim exp. |
Esta validação foca-se exclusivamente no fator tempo. A ferramenta exibe a nota de que esta verificação analisa apenas a claim exp, não validando a assinatura, o emissor ou o destinatário do token.
Descodificação versus Verificação de Assinatura
Existe uma diferença crítica entre descodificar um JWT e verificar a sua assinatura.
A descodificação é um processo puramente matemático de reversão da codificação Base46URL. Qualquer pessoa que intersete um JWT consegue ler o seu cabeçalho e a sua carga útil, uma vez que os dados não estão encriptados, apenas codificados.
A verificação, por outro lado, garante a integridade e a autenticidade do token. Para verificar se um JWT foi alterado por terceiros, é necessário aplicar o algoritmo especificado no cabeçalho sobre o cabeçalho e o payload, utilizando o segredo de assinatura (no caso de algoritmos simétricos) ou a chave pública correspondente (no caso de algoritmos assimétricos).
Esta ferramenta funciona exclusivamente como um descodificador. Ela não verifica a assinatura do JWT e nunca solicita chaves privadas, segredos ou chaves públicas para o efeito.
Tratamento de Erros e Regras de Validação
Durante a análise do texto introduzido no campo Cole o seu JWT, a ferramenta aplica regras estritas para garantir a integridade dos dados. Se o input não cumprir os requisitos de um JWT estruturado, as áreas de descodificação são ocultadas e são apresentadas as seguintes mensagens de erro específicas:
- JWT inválido — são esperadas três partes separadas por pontos. — Ocorre se o texto introduzido não contiver exatamente dois pontos delimitadores.
- Não foi possível descodificar o cabeçalho — Base64URL inválido. — Ocorre se a primeira secção do token contiver caracteres inválidos para o padrão Base64URL.
- Não foi possível descodificar a carga útil — Base64URL inválido. — Ocorre se a segunda secção do token apresentar falhas na estrutura de codificação.
- O cabeçalho não é um JSON válido. — Ocorre se, após a descodificação Base64URL, o conteúdo do cabeçalho não puder ser interpretado como um objeto JSON estruturado.
- A carga útil (payload) não é um JSON válido. — Ocorre se a carga útil descodificada não respeitar a sintaxe JSON.
- O comprimento excede o limite de um JWT real. — Ocorre se o volume de caracteres inserido for excessivo para os padrões operacionais de um token.
Se o campo de entrada estiver vazio, a ferramenta permanece no estado Pronto. Cole um JWT para o descodificar.. Ao acionar a opção Limpar, o input é limpo, o estado muda para Limpo. e o foco do cursor regressa automaticamente ao campo de introdução.
Privacidade e Processamento Local
A segurança dos dados introduzidos é salvaguardada pelo método de processamento da ferramenta. Toda a análise, descodificação Base64URL, validação de sintaxe JSON e leitura das claims de tempo ocorrem localmente, diretamente no navegador do utilizador.
Nenhum dado, token ou fragmento de informação é enviado para os servidores do BroBroGo. O processamento é executado em memória local na sessão ativa do browser.
Perguntas Frequentes
É seguro colar o meu JWT aqui?
Sim. A descodificação ocorre inteiramente no seu navegador — o seu token nunca é enviado para o BroBroGo.
Esta ferramenta verifica a assinatura?
Não. Ele apenas descodifica o cabeçalho (header) e a carga útil (payload) para leitura. A verificação de assinatura exige o segredo de assinatura ou chave pública, informações que esta ferramenta nunca solicita.
Como sei se o meu token expirou?
O descodificador lê a propriedade exp e exibe um indicador de status — válido, expirado, ainda não válido ou sem expiração — ao lado do token descodificado.