Autenticar puntos finales de API usando JWT en Jitterbit Studio

Introducción

Los puntos finales de API Manager aceptan solicitudes de cualquier llamante que conozca la URL. Para restringir el acceso, puedes requerir que los llamantes se autentiquen con un JSON Web Token (JWT) firmado: un token compacto y seguro para URL que codifica la identidad del llamante y un tiempo de vencimiento.

Esta guía cubre el ciclo de autenticación completo usando el conector JWT:

Una operación de inicio de sesión acepta la identidad del llamante, genera un JWT firmado y lo devuelve al llamante.
Las operaciones protegidas validan el token en cada solicitud antes de que comience el procesamiento.

El conector JWT maneja la generación y validación de tokens localmente. No se conecta a ningún servicio externo.

Esta guía asume lo siguiente:

Se configura una API personalizada y se publica en API Manager en el mismo entorno que el proyecto.
Estás familiarizado con crear puntos finales de API personalizados en API Manager.

Parte 1: Crear la conexión JWT

Una conexión JWT es un punto final nombrado que te da acceso a los tipos de actividad Generar Token, Decodificar Token y Validar Token.

En Studio, abre la paleta de componentes de diseño y selecciona la pestaña Puntos finales y conectores del proyecto.
Localiza el conector JWT y configura una nueva conexión.
Nombre de conexión: Ingresa un nombre (por ejemplo, JWT).
Haz clic en Guardar cambios.

El punto final JWT aparece en la pestaña Puntos finales y conectores del proyecto. Para más información, consulta Conexión JWT.

Parte 2: Crear el punto final de inicio de sesión

El punto final de inicio de sesión acepta una solicitud POST y devuelve un JWT firmado. Los llamantes presentan este token en el encabezado Authorization de todas las solicitudes posteriores a puntos finales protegidos.

Paso 1: Almacenar el secreto de firma

Tanto la actividad Generar Token como Validar Token utilizan el mismo secreto de firma. Almacénalo como una variable de proyecto para que su valor no esté codificado y no aparezca en los registros de operaciones. Para los pasos completos y las mejores prácticas para gestionar credenciales como variables de proyecto ocultas, consulta Gestionar credenciales de puntos finales.

En Studio, abre el menú de acciones del proyecto y selecciona Variables de proyecto.
Agrega una variable llamada jwt.secret e ingresa una cadena fuerte y generada aleatoriamente como su valor.
Habilita Ocultar valor.
Haz clic en Guardar.

Paso 2: Configurar la actividad Generar Token

En la paleta de componentes de diseño, expande el punto final JWT y arrastra el tipo de actividad Generar Token al lienzo de diseño.
Nombre: Ingresa un nombre (por ejemplo, Generar Token de Inicio de Sesión).
Tipo JWT: Selecciona JWS.
Tipo de firma: Selecciona Simétrica.
Algoritmos de firma: Selecciona HS256.
Clave secreta: Ingresa [jwt.secret].
Expande Configuración opcional y agrega las siguientes Propiedades de carga útil. Estas hacen referencia a variables de proyecto que el script de operación de inicio de sesión establece en tiempo de ejecución:

Clave Valor Tipo de datos

sub [jwt.sub] string

iat [jwt.iat] number

exp [jwt.exp] number
Haz clic en Finalizado.

Para descripciones de todas las configuraciones de actividad, consulta Actividad JWT Generar Token.

En API Manager, haz clic en Nueva API y selecciona API personalizada.
Ingresa un Nombre de API (por ejemplo, Auth API), un Prefijo de URL (por ejemplo, auth) y una cadena de Versión.
Habilita SSL.
Haz clic en Save, luego haz clic en Add Service.
Method: Selecciona POST.
Path: Ingresa /token.
Operation: Selecciona la operación de inicio de sesión. Si la operación aún no existe, crea un marcador de posición y regresa para actualizar este campo después de completar el Paso 4.
Response Type: Selecciona System Variable.
Haz clic en Save, luego haz clic en Publish.

La operación de inicio de sesión consta de un script de preparación y una transformación que ejecuta la actividad Generate Token.

Crea las variables de proyecto para las reclamaciones de token agregándolas en el cajón Project Variables junto a jwt.secret:

Nombre	Descripción
`jwt.sub`	La identidad del llamador (reclamación de asunto)
`jwt.iat`	Hora de emisión como marca de tiempo de época Unix
`jwt.exp`	Hora de vencimiento como marca de tiempo de época Unix

Agrega un script de preparación como el primer paso de la operación de inicio de sesión. Este script lee la identidad del llamador del cuerpo de la solicitud y establece las variables de proyecto de reclamación:
```
<trans>
$body = JSONParser($jitterbit.api.request.body);

// Set the subject claim from the request body
$jwt.sub = Get($body, "userId");

// Set the issue time and expiry as Unix epoch timestamps
// (seconds since 1970-01-01 00:00:00 UTC)
$jwt.iat = Long(Now());
$jwt.exp = $jwt.iat + 3600;  // 1-hour token lifetime
</trans>
```
Long(Now()) convierte la fecha-hora actual a un entero de época Unix (segundos desde 1970-01-01 00:00:00 UTC). Ajusta el desplazamiento de vencimiento (3600) según la duración del token requerida por tu política de seguridad.
Agrega un paso de transformación después del script de preparación, con la actividad Generate Token como su destino. En la transformación, asigna cada variable de proyecto de reclamación al nodo de esquema de carga correspondiente. La actividad Generate Token lee los valores de reclamación de [jwt.sub], [jwt.iat] y [jwt.exp], y escribe el JWT firmado en su esquema de salida.
Establece la respuesta de la API agregando una segunda transformación (usando el patrón de operación de dos transformaciones) para asignar el token generado desde la salida de la actividad a $jitterbit.api.response. La actividad Generate Token escribe el JWT firmado en su esquema de datos de salida, que se muestra en el Paso 2: Revisa los esquemas de datos de la configuración de la actividad:
```
<trans>
$token_response = Dict();
$token_response["token"] = $jwt_generated_token;
$jitterbit.api.response = JSONStringify($token_response);
$jitterbit.api.response.status_code = 200;
</trans>
```
Reemplaza $jwt_generated_token con la variable o ruta que se asigna desde el esquema de salida de la actividad Generate Token. El nombre de campo exacto se muestra en el paso de revisión del esquema de datos de la configuración de la actividad.

Parte 3: Valida el token en puntos finales protegidos

Cada operación protegida debe verificar el JWT del llamador antes de procesar la solicitud. Agrega una operación de validación que se ejecute antes de la operación protegida y devuelva una respuesta 401 si el token falta o no es válido.

Paso 1: Configura la actividad Validate Token

En la paleta de componentes de diseño, expande el punto final JWT y arrastra el tipo de actividad Validate Token al lienzo de diseño.
Name: Ingresa un nombre (por ejemplo, Validate Login Token).
JWT token: Ingresa [jwt.incoming_token]. Esto hace referencia a una variable de proyecto que el script de validación establece desde el encabezado Authorization.
JWT type: Selecciona JWS.
Secret key: Ingresa [jwt.secret].
Haz clic en Finished.

Para obtener descripciones de todas las configuraciones de actividad, consulta JWT Validate Token activity.

Agrega una variable de proyecto denominada jwt.incoming_token en el cajón Project Variables.

Paso 2: Construye la operación de validación

Crea una nueva operación de script que actúe como puerta de entrada para tu punto final protegido. Esta operación extrae el token, ejecuta la actividad Validate Token y pasa el control a la operación protegida si la validación es exitosa.

Agrega un script de extracción como el primer paso de la operación de validación. Este script lee el encabezado Authorization, verifica el prefijo Bearer y establece jwt.incoming_token:

<trans>
$auth_header = $jitterbit.api.request.headers.Authorization;

If(Left($auth_header, 7) != "Bearer ",
  $jitterbit.api.response.status_code = 401;
  $err_response = Dict();
  $err_response["error"] = "Missing or malformed Authorization header";
  $jitterbit.api.response = JSONStringify($err_response);
  RaiseError("Unauthorized");
);

$jwt.incoming_token = Mid($auth_header, 8);
</trans>

Left verifica los primeros siete caracteres del encabezado. Mid extrae todo después del prefijo Bearer. RaiseError detiene la operación inmediatamente y activa la acción de error configurada.

Agrega una transformación de validación con la actividad Validate Token como destino. La actividad lee el token de [jwt.incoming_token] y verifica su firma contra [jwt.secret]. Si el token no es válido, ha expirado o ha sido alterado, la actividad genera un error.

Paso 3: Configura acciones de error y éxito en la operación de validación

Abre la configuración de la operación de validación y selecciona la pestaña Acciones.

En caso de fallo (token inválido):

Condición: Selecciona On Fail.
Acción: Selecciona Run Operation.

Operación: Selecciona o crea una operación de script que devuelva una respuesta 401:

<trans>
$jitterbit.api.response.status_code = 401;
$err_response = Dict();
$err_response["error"] = "Invalid or expired token";
$jitterbit.api.response = JSONStringify($err_response);
</trans>

Haz clic en Add Action.

En caso de éxito (token válido):

Condición: Selecciona On Success.
Acción: Selecciona Run Operation.
Operación: Selecciona la operación protegida.
Haz clic en Add Action.

Guarda la configuración. La operación de validación ahora actúa como una puerta de control: si el token es válido, se encadena a la operación protegida; si no es válido o falta, devuelve 401 y se detiene.

En API Manager, actualiza el campo Operation del endpoint protegido para que apunte a la operación de validación en lugar de la operación protegida directamente. La operación de validación se encadena a la operación protegida en caso de éxito.

Verifica la integración

Implementa el proyecto y confirma que tanto el endpoint de inicio de sesión como el endpoint protegido se publican en API Manager.
Envía una solicitud POST al endpoint /auth/token con un cuerpo JSON que contenga un campo userId:
```
{"userId": "user123"}
```
Confirma que el cuerpo de la respuesta contiene un campo token.
Envía una solicitud al endpoint protegido con el token en el encabezado Authorization:
```
Authorization: Bearer <token>
```
Confirma que la operación se completa correctamente.
Envía una solicitud al endpoint protegido sin un encabezado Authorization. Confirma que el endpoint devuelve una respuesta 401.
Modifica la cadena de token (por ejemplo, cambia el último carácter) y envíala. Confirma que el endpoint devuelve una respuesta 401.
Si algún paso falla, abre los registros de operación en Studio para verificar si hay errores.

Clave	Valor	Tipo de datos
`sub`	`[jwt.sub]`	`string`
`iat`	`[jwt.iat]`	`number`
`exp`	`[jwt.exp]`	`number`