JWT

1. Visión General

El componente JWT (jwt) crea, valida, cifra y descifra tokens JWT (JSON Web Token), usados para autenticación e intercambio seguro de información entre sistemas.

Úsalo cuando el flujo necesita generar un token de acceso, verificar si un token recibido es válido, o intercambiar información de forma cifrada con otro sistema. No lo uses como el mecanismo de login del usuario final en sí — este componente solo manipula los tokens, no gestiona sesiones ni usuarios.

Solo funciona como acción de salida dentro del flujo — no puede usarse como disparador de entrada.

2. Prerrequisitos

• Una clave para firmar/verificar/cifrar/descifrar, que puede ser: un secreto simétrico (secret), una clave en formato JWK (jwk) o una clave en formato PEM (pem), según el algoritmo elegido.
• Conocimiento del algoritmo criptográfico deseado (ej.: HS256, RS256, RSA-OAEP-256).

3. Autenticación y Conexión

No hay conexión con sistemas externos — todo se procesa localmente. La "credencial" aquí es la propia clave criptográfica usada.

Campo	Obligatorio	Tipo	Descripción	Ejemplo
secret	Depende del algoritmo	Texto	Secreto simétrico, usado en algoritmos HMAC (HS*) o de clave simétrica en cifrado (A*KW).	"mi-secreto-super-secreto"
jwk	Depende del algoritmo	Texto (JSON)	Clave en formato JWK (JSON Web Key). Alternativa a secret/pem.	Un JSON de clave JWK
pem	Depende del algoritmo	Texto (PEM)	Clave en formato PEM, usada en algoritmos RSA/EC/OKP. Alternativa a jwk.	Un bloque -----BEGIN...

4. Configuración / Operaciones Soportadas

El campo mode define la operación ejecutada.

Campo	Obligatorio	Tipo	Descripción	Ejemplo
mode	No	Texto: sign, verify, encrypt o decrypt	Operación a ejecutar. Valor por defecto: "sign".	"verify"
algorithm	Depende del modo	Texto	Algoritmo criptográfico. Obligatorio en encrypt. En los demás modos, debe informarse correctamente para que la clave funcione.	"HS256", "RS256", "RSA-OAEP-256"

Modo sign — firmar un token

Campo	Obligatorio	Tipo	Descripción	Ejemplo
claims	No	Texto (JSON)	Datos a incluir en el payload del token. Valor por defecto: "{}".	{"userId": 123}
ttlSeconds	No	Texto (número)	Tiempo de vida del token, en segundos. Valor por defecto: "3600" (1 hora).	"1800"

Respuesta: {"token": "<jwt firmado>"}.

Modo verify — validar un token

Campo	Obligatorio	Tipo	Descripción	Ejemplo
token	Sí	Texto	El JWT a validar.	El token recibido de otro sistema

Respuesta: {"valid": true/false, "claims": {...} o null}.

Modo encrypt — cifrar datos en un JWE

Campo	Obligatorio	Tipo	Descripción	Ejemplo
claims	No	Texto (JSON)	Datos a cifrar. Valor por defecto: "{}".	{"cpf": "123.456.789-00"}
ttlSeconds	No	Texto (número)	Tiempo de vida, en segundos. Valor por defecto: "3600".	"600"
encryptionMethod	No	Texto	Método de cifrado de contenido. Valor por defecto: "A256GCM".	"A128CBC-HS256"

Respuesta: {"token": "<jwt cifrado>"}.

Modo decrypt — descifrar un JWE

Campo	Obligatorio	Tipo	Descripción	Ejemplo
token	Sí	Texto	El JWT cifrado a decodificar.	El token recibido

Respuesta: {"claims": {...}}.

5. Ejemplos Prácticos

Ejemplo simple: generar un token de acceso firmado con un secreto simétrico, válido por 30 minutos, conteniendo el ID del usuario.

Entrada:

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

Configuración del componente:

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

Respuesta:

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

Ejemplo avanzado: validar un token recibido en una solicitud, para decidir (con un Choice justo después) si la solicitud puede continuar.

Entrada:

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

Configuración del componente:

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

Respuesta (token válido):

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

6. Errores Comunes y Troubleshooting

Error / Síntoma	Causa probable	Cómo resolverlo
"IN not supported for JWT connector"	Intento de usar JWT como disparador de entrada.	Usar el componente solo como acción de salida en el flujo.
"Invalid mode: [valor]"	El campo mode no es sign, verify, encrypt ni decrypt.	Corregir el valor de mode.
"Token is required"	Se usaron los modos verify/decrypt sin completar token.	Completar token con el JWT a validar/decodificar.
"Algorithm is required for encryption"	Se usó el modo encrypt sin completar algorithm.	Informar el algoritmo de cifrado (ej.: RSA-OAEP-256, A256KW).
"JWT processing error: ..."	Falla al procesar el token (clave incompatible con el algoritmo, token expirado o corrupto).	Revisar si la clave (secret/jwk/pem) es compatible con el algorithm elegido.
"...requires 'secret' or JWK with 'oct' key type."	Algoritmo HMAC/simétrico (HS*, A*KW) sin secret ni jwk del tipo oct.	Completar secret o usar un jwk del tipo correcto.
"Algorithm [alg] requires JWK or PEM key."	Algoritmo asimétrico (RS*, ES*, RSA*) sin jwk ni pem.	Completar jwk o pem con la clave correspondiente.