JWT

1. Visão Geral

O componente JWT (jwt) cria, valida, criptografa e descriptografa tokens JWT (JSON Web Token), usados para autenticação e troca segura de informações entre sistemas.

Use quando o fluxo precisa gerar um token de acesso, verificar se um token recebido é válido, ou trocar informações de forma criptografada com outro sistema. Não use como o próprio mecanismo de login do usuário final — este componente só manipula os tokens, não gerencia sessões ou usuários.

Só funciona como ação de saída dentro do fluxo — não pode ser usado como gatilho de entrada.

2. Pré-requisitos

• Uma chave para assinar/verificar/criptografar/descriptografar, que pode ser: um segredo simétrico (secret), uma chave em formato JWK (jwk) ou uma chave em formato PEM (pem), dependendo do algoritmo escolhido.
• Conhecimento do algoritmo criptográfico desejado (ex.: HS256, RS256, RSA-OAEP-256).

3. Autenticação e Conexão

Não há conexão com sistemas externos — tudo é processado localmente. A "credencial" aqui é a própria chave criptográfica usada.

Campo	Obrigatório	Tipo	Descrição	Exemplo
secret	Depende do algoritmo	Texto	Segredo simétrico, usado em algoritmos HMAC (HS*) ou de chave simétrica em criptografia (A*KW).	"meu-segredo-super-secreto"
jwk	Depende do algoritmo	Texto (JSON)	Chave no formato JWK (JSON Web Key). Alternativa a secret/pem.	Um JSON de chave JWK
pem	Depende do algoritmo	Texto (PEM)	Chave em formato PEM, usada em algoritmos RSA/EC/OKP. Alternativa a jwk.	Um bloco -----BEGIN...

4. Configuração / Operações Suportadas

O campo mode define a operação executada.

Campo	Obrigatório	Tipo	Descrição	Exemplo
mode	Não	Texto: sign, verify, encrypt ou decrypt	Operação a ser executada. Valor padrão: "sign".	"verify"
algorithm	Depende do modo	Texto	Algoritmo criptográfico. Obrigatório em encrypt. Nos demais modos, deve ser informado corretamente para a chave funcionar.	"HS256", "RS256", "RSA-OAEP-256"

Modo sign — assinar um token

Campo	Obrigatório	Tipo	Descrição	Exemplo
claims	Não	Texto (JSON)	Dados a incluir no payload do token. Valor padrão: "{}".	{"userId": 123}
ttlSeconds	Não	Texto (número)	Tempo de vida do token, em segundos. Valor padrão: "3600" (1 hora).	"1800"

Resposta: {"token": "<jwt assinado>"}.

Modo verify — validar um token

Campo	Obrigatório	Tipo	Descrição	Exemplo
token	Sim	Texto	O JWT a validar.	O token recebido de outro sistema

Resposta: {"valid": true/false, "claims": {...} ou null}.

Modo encrypt — criptografar dados em um JWE

Campo	Obrigatório	Tipo	Descrição	Exemplo
claims	Não	Texto (JSON)	Dados a criptografar. Valor padrão: "{}".	{"cpf": "123.456.789-00"}
ttlSeconds	Não	Texto (número)	Tempo de vida, em segundos. Valor padrão: "3600".	"600"
encryptionMethod	Não	Texto	Método de criptografia de conteúdo. Valor padrão: "A256GCM".	"A128CBC-HS256"

Resposta: {"token": "<jwt criptografado>"}.

Modo decrypt — descriptografar um JWE

Campo	Obrigatório	Tipo	Descrição	Exemplo
token	Sim	Texto	O JWT criptografado a decodificar.	O token recebido

Resposta: {"claims": {...}}.

5. Exemplos Práticos

Exemplo simples: gerar um token de acesso assinado com um segredo simétrico, válido por 30 minutos, contendo o ID do usuário.

Entrada:

{
  "usuario": { "id": 123, "nome": "Maria Silva" }
}

Configuração do componente:

{
  "componentName": "jwt",
  "configurations": {
    "mode": "sign",
    "algorithm": "HS256",
    "secret": "{$.secrets.jwtSecret}",
    "claims": "{\"userId\": {$.body.usuario.id}}",
    "ttlSeconds": "1800"
  }
}

Resposta:

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOjEyM30.assinatura..."
}

Exemplo avançado: validar um token recebido em uma requisição, para decidir (com um Choice logo em seguida) se a requisição pode continuar.

Entrada:

{
  "authorizationToken": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOjEyM30.assinatura..."
}

Configuração do componente:

{
  "componentName": "jwt",
  "configurations": {
    "mode": "verify",
    "algorithm": "HS256",
    "secret": "{$.secrets.jwtSecret}",
    "token": "{$.body.authorizationToken}"
  }
}

Resposta (token válido):

{
  "valid": true,
  "claims": { "userId": 123 }
}

6. Erros Comuns e Troubleshooting

Erro / Sintoma	Causa provável	Como resolver
"IN not supported for JWT connector"	Tentativa de usar o JWT como gatilho de entrada.	Usar o componente apenas como ação de saída no fluxo.
"Invalid mode: [valor]"	O campo mode não é sign, verify, encrypt ou decrypt.	Corrigir o valor de mode.
"Token is required"	Os modos verify/decrypt foram usados sem preencher token.	Preencher token com o JWT a validar/decodificar.
"Algorithm is required for encryption"	O modo encrypt foi usado sem preencher algorithm.	Informar o algoritmo de criptografia (ex.: RSA-OAEP-256, A256KW).
"JWT processing error: ..."	Falha ao processar o token (chave incompatível com o algoritmo, token expirado ou corrompido).	Revisar se a chave (secret/jwk/pem) é compatível com o algorithm escolhido.
"...requires 'secret' or JWK with 'oct' key type."	Algoritmo HMAC/simétrico (HS*, A*KW) sem secret nem jwk do tipo oct.	Preencher secret ou usar um jwk do tipo correto.
"Algorithm [alg] requires JWK or PEM key."	Algoritmo assimétrico (RS*, ES*, RSA*) sem jwk nem pem.	Preencher jwk ou pem com a chave correspondente.