Criar um JSON Web Token (JWT) assinado

O que é o JWT Builder?

O JWT Builder é uma ferramenta online que produz um JSON Web Token assinado (JWT) a partir de um payload JSON e de um segredo HMAC. Destina-se aos programadores que precisam de gerar rapidamente um token de teste para verificar o comportamento de uma API, simular uma sessão autenticada no Postman, ou reproduzir um bug ligado à expiração ou ao âmbito de um token.

Ao contrário do nosso JWT decoder, que se limita a ler um token existente, o JWT Builder fabrica um token completo: constrói o header, codifica o payload, calcula a assinatura HMAC e monta tudo no formato compacto header.payload.signature esperado por todas as bibliotecas JWT do mercado.

Porquê gerar um JWT?

Um builder de JWT não tem vocação para emitir tokens de produção. É antes de mais uma ferramenta de desenvolvimento e testes. Eis os cenários mais comuns:

• Testes de integração: produzir JWT previsíveis para conduzir testes E2E que atingem endpoints protegidos sem depender do verdadeiro fornecedor de identidade.
• Mocks de API: substituir temporariamente uma chamada ao IdP por um JWT assinado localmente com o mesmo segredo de teste.
• Desenvolvimento local: ligar-se ao seu próprio backend gerando à mão um token que contenha as claims pretendidas, sem ter de passar por todo o fluxo OAuth2.
• Demos: ilustrar um percurso de autenticação ou um workflow baseado em permissões sem ter um IdP real à mão.
• Reprodução de bugs: forjar um token expirado, um token com um aud incorreto, um token sem certas claims, para testar os caminhos de erro da sua API.
• Debugging de um parser custom: injetar JWTs especialmente construídos para testar um parser caseiro.

Composição de um JWT

Um JWT assinado é composto por três segmentos separados por um ponto, cada um codificado em Base64URL (variante de Base64 sem padding e com -/_ em vez de +//):

• Header: um objeto JSON que descreve o algoritmo de assinatura e o tipo do token, por exemplo {"alg":"HS256","typ":"JWT"}. O JWT Builder gera-o automaticamente a partir do algoritmo que escolher.
• Payload: um objeto JSON arbitrário que contém as claims do token (sujeito, permissões, datas de expiração). É a parte que fornece.
• Signature: um HMAC-SHA calculado sobre a concatenação base64url(header) + "." + base64url(payload) com a sua chave secreta. É ela que garante a integridade do token.

Casos de uso em detalhe

• API mock para testes E2E: a sua suite Cypress ou Playwright tem de chamar uma API que exige um Authorization: Bearer .... Em vez de orquestrar um login completo a cada teste, assina-se um JWT em tempo real com o segredo partilhado e injeta-se no cabeçalho.
• Demo de SSO: apresentar um percurso de autenticação federada sem depender de um IdP online.
• Fixture de teste: gerar um JWT determinista a partir de um payload conhecido para servir de fixture estável em testes unitários.
• Diagnóstico de um parser custom: testar um parser JWT caseiro com tokens voluntariamente mínimos ou estranhos (claims em falta, tipos inesperados).
• Aprendizagem: perceber concretamente como se constrói um JWT, modificando o payload e observando a assinatura mudar.

Algoritmos suportados: HS256, HS384, HS512

A nossa ferramenta suporta os três algoritmos HMAC padrão da especificação JWT (RFC 7519):

• HS256: HMAC com SHA-256. Assinatura de 32 octetos. O mais usado na prática, bom compromisso entre rapidez e solidez criptográfica. Recomendado por defeito.
• HS384: HMAC com SHA-384. Assinatura de 48 octetos. Adaptado a contextos que exigem uma margem de segurança superior.
• HS512: HMAC com SHA-512. Assinatura de 64 octetos. O mais robusto, ao custo de um token ligeiramente mais volumoso.

HMAC ou RSA?

Os algoritmos HS* são simétricos: a mesma chave serve para assinar e verificar. É simples e rápido, mas isso significa que qualquer serviço capaz de verificar um token também é capaz de o emitir. Se precisa de separar estes dois papéis (um único emissor, vários consumidores), vire-se para os algoritmos RS256/RS384/RS512 (RSA, assimétricos), que pode verificar com o nosso JWT verifier.

Segurança: proteger o seu segredo

A segurança de um JWT assinado em HMAC assenta inteiramente na confidencialidade do segredo. Algumas regras básicas:

• Utilize um segredo longo e aleatório. A RFC 7518 recomenda no mínimo o tamanho da saída do algoritmo (32 octetos para HS256, 48 para HS384, 64 para HS512). Uma palavra-passe humana como azerty123 é trivialmente atacável por força bruta offline.
• Nunca assine um JWT no lado do cliente. O segredo apareceria no código JavaScript distribuído ao navegador, exposto a qualquer utilizador. A assinatura deve permanecer sempre no servidor.
• Armazene o segredo numa variável de ambiente (ex. JWT_SECRET), nunca num repositório Git. Pense em utilizar um cofre como o HashiCorp Vault, AWS Secrets Manager ou os Symfony Secrets conforme a sua stack.
• Rode o segredo regularmente (key rotation), sobretudo depois de um incidente ou da saída de uma pessoa que teve acesso à configuração.
• O JWT Builder destina-se a testes e à aprendizagem. Para produção, utilize a biblioteca JWT do seu framework (lcobucci/jwt, firebase/php-jwt, jose-php).

Boas práticas de claims

O payload é um objeto JSON livre, mas a RFC 7519 define um conjunto de registered claims que as bibliotecas JWT sabem interpretar. Incluir as claims certas torna o seu token portável e evita bugs subtis:

• iss (issuer): identificador do emissor, por exemplo "https://api.example.com".
• sub (subject): identificador da pessoa ou entidade visada, frequentemente o ID do utilizador.
• aud (audience): a quem o token se destina, para impedir a reutilização de um token noutra API.
• exp (expiration time): timestamp Unix após o qual o token deixa de ser válido. Incluir sempre, mesmo num token de teste: um token sem expiração é um mau hábito difícil de corrigir depois.
• nbf (not before): timestamp antes do qual o token ainda não é válido. Útil para pré-emitir um token ativável mais tarde.
• iat (issued at): timestamp de emissão, útil para registar e revogar.
• jti (JWT ID): identificador único do token, indispensável para a idempotência e para implementar uma lista de revogação.

Exemplo de payload típico

{
  "iss": "https://api.example.com",
  "sub": "user-12345",
  "aud": "mobile-app",
  "iat": 1714723200,
  "exp": 1714726800,
  "jti": "9f2d6b1e-2c4a-4f8a-9c3a-87a2b8a4b7e1",
  "scope": "read:profile write:profile"
}

Como utilizar a ferramenta

1. Introduza o payload sob forma de JSON válido. É um objeto, portanto começa por { e termina por }.
2. Indique o segredo HMAC. Escolha uma cadeia longa e aleatória para os tokens de produção.
3. Selecione o algoritmo: HS256 por defeito, HS384 ou HS512 conforme as suas necessidades.
4. Clique em criar. O JWT assinado aparece, pronto a colar num cabeçalho Authorization: Bearer ....
5. Pode depois verificar o token com o mesmo segredo para confirmar a coerência do round-trip, ou descodificá-lo para reler o seu conteúdo.

Perguntas frequentes

Exemplo de pedido

curl -X POST https://cdrn.fr/api/v1/tools/jwt-builder/execute \
  -H "Content-Type: application/json" \
  -d '{"payload":"...","secret":"...","algorithm":"HS256"}'

Esquema de entrada

Pontos de acesso

• GET https://cdrn.fr/api/v1/tools - lista todas as ferramentas disponíveis
• GET https://cdrn.fr/api/v1/tools/jwt-builder - obtém o esquema desta ferramenta
• POST https://cdrn.fr/api/v1/tools/jwt-builder/execute - executa esta ferramenta com um payload JSON