Saltar al contenido

Implementar un flujo de código de autorización OAuth 2.0 con almacenamiento de tokens en Jitterbit Studio

Introducción

El flujo de código de autorización OAuth 2.0 permite que una operación de Studio acceda a una API de terceros en nombre de un usuario específico, utilizando las credenciales delegadas de ese usuario en lugar de una cuenta de servicio compartida. Esta guía cubre el flujo completo: construir la URL de autorización, recibir el código de autorización en un endpoint de devolución de llamada, intercambiar el código por tokens de acceso y actualización, almacenar el token de actualización en Cloud Datastore, y actualizar el token de acceso en ejecuciones posteriores sin interacción del usuario.

Los ejemplos en esta guía utilizan Google como proveedor de autorización. El mismo patrón se aplica a cualquier proveedor OAuth 2.0 que admita el tipo de concesión de código de autorización: reemplaza las URLs específicas del proveedor, los alcances y los nombres de parámetros con los valores de tu servicio objetivo.

Utiliza este patrón cuando:

  • La API objetivo requiere permisos a nivel de usuario que una cuenta de servicio no puede proporcionar.
  • Necesitas acceso de larga duración utilizando tokens de actualización sin autorización manual repetida.
  • Estás construyendo un agente de IA o un flujo de trabajo automatizado que accede a buzones de correo, calendarios o documentos de usuarios.

Para APIs que utilizan claves de API o credenciales de cliente en lugar de autorización de usuario, consulta Administrar credenciales de endpoint y Llamar a una API REST utilizando el conector HTTP v2.

Esta guía asume:

  • Se configura una API personalizada y se publica en API Manager en el mismo entorno que el proyecto.
  • Existe un almacenamiento de claves de Cloud Datastore o se creará para mantener registros de tokens por usuario. Consulta Almacenar y recuperar estado de sesión utilizando Cloud Datastore para los pasos de configuración.
  • El proyecto tiene una forma de entregar una URL al usuario, como un mensaje de Slack o una interfaz de App Builder.

Patrón de diseño

Tres operaciones implementan el flujo de código de autorización OAuth 2.0:

flowchart TD A["Connect operation
Build auth URL → Deliver to user"] --> B["User browser
Approve access at provider"] B -->|"Redirect with ?code="| C["Callback operation
Extract code → Exchange for tokens → Store refresh token → Serve confirmation page"] D["Check Auth operation
Read refresh token → Exchange for access token"] --> E["API calls using access token"]

La operación Connect construye la URL de autorización y la entrega al usuario. La operación OAuth Callback recibe el código de autorización cuando el proveedor redirige el navegador del usuario, intercambia el código por tokens y almacena el token de actualización para uso futuro. La operación Check Auth se ejecuta antes de cualquier llamada a API: lee el token de actualización almacenado en Cloud Datastore e intercambia por un token de acceso fresco.

Parte 1: Registrar la aplicación OAuth y almacenar credenciales

Antes de escribir cualquier script, registra Studio como una aplicación OAuth con el proveedor de autorización y almacena las credenciales resultantes como variables de proyecto.

Registrar la aplicación

En la consola de desarrollador de tu proveedor OAuth (por ejemplo, Google Cloud Console), crea una credencial OAuth 2.0 de tipo Aplicación web y configura:

  • URIs de redirección autorizados: Agrega la URL completa del endpoint de devolución de llamada que crearás en la Parte 2. Por ejemplo: https://<your-agent-host>/<environment>/<version>/<service-root>/oauth/callback. Debes conocer esta URL antes de completar el registro.

El proveedor emitirá un ID de cliente y una Contraseña de cliente.

Almacenar credenciales como variables de proyecto

En Studio, abre el menú de acciones del proyecto y selecciona Variables de proyecto. Crea las siguientes variables de proyecto con sus valores ocultos:

  • client_id: El ID de cliente de la aplicación OAuth emitido por el proveedor.
  • client_secret: La contraseña de cliente de la aplicación OAuth.
  • redirect_uri: La URL de devolución de llamada completa configurada en la consola del proveedor.

Referencia estas variables en scripts utilizando el prefijo $ (por ejemplo, $client_id, $client_secret, $redirect_uri).

Consejo

Almacenar redirect_uri como una variable de proyecto facilita su actualización al cambiar entre entornos sin editar scripts.

Parte 2: Crear el endpoint de callback

El endpoint de callback recibe el código de autorización del proveedor después de que el usuario aprueba el acceso. Créalo antes de escribir cualquier script para que la URL completa esté disponible y se pueda configurar en la consola del proveedor.

Crear la operación de callback

  1. En Studio, crea una nueva operación. Nómbrala OAuth Callback o un nombre similar.

  2. Agrega un paso de Script como primer paso. Deja el cuerpo del script vacío por ahora. Agregarás la lógica de callback en la Parte 4.

Publicar la operación de callback como un endpoint de API

Sigue Exponer una operación de Studio como una API REST para publicar la operación OAuth Callback. Al configurar el endpoint, establece:

  • Método: GET. Los proveedores de OAuth redirigen el navegador del usuario a la URL de callback usando una solicitud GET con parámetros de consulta.
  • Ruta: /oauth/callback (o cualquier ruta que coincida con el URI de redirección que registrarás con el proveedor).
  • Tipo de respuesta: Variable del sistema. El script de callback establece $jitterbit.api.response.body y $jitterbit.api.response.headers.Content_Type para servir una página de confirmación HTML.

Copia la URL del endpoint publicado. Úsala como valor de la variable de proyecto redirect_uri y regístrala con el proveedor como un URI de redirección autorizado.

Parte 3: Construir la URL de autorización

La operación Connect construye la URL de autorización y la entrega al usuario.

Crear la operación de conexión

Crea una nueva operación. Nómbrala Connect o un nombre similar. Agrega un paso de script con el siguiente script:

<trans>
$authUrl = "https://accounts.google.com/o/oauth2/v2/auth"
    + "?client_id=" + $client_id
    + "&redirect_uri=" + URLEncode($redirect_uri)
    + "&response_type=code"
    + "&scope=" + URLEncode("https://mail.google.com/ openid email")
    + "&access_type=offline"
    + "&prompt=consent";
</trans>

Los parámetros clave:

  • response_type=code: Solicita el tipo de concesión de código de autorización.
  • scope: Los permisos que solicita la aplicación. Separa múltiples alcances con espacios y codifica la cadena combinada usando URLEncode. Ajusta los valores de alcance para que coincidan con lo que requiere tu API de destino.
  • access_type=offline: Instruye al proveedor para emitir un token de actualización además del token de acceso.
  • prompt=consent: Fuerza la pantalla de consentimiento a aparecer incluso si el usuario ha autorizado previamente la aplicación. Esto garantiza que se emita un nuevo token de actualización cada vez.

Reemplaza la URL del endpoint de autorización de Google y los valores de alcance con los de tu proveedor de destino.

Entregar la URL al usuario

Después de construir la URL, entrégala para que el usuario pueda abrirla en un navegador. Para enviar la URL como un mensaje efímero de Slack (por ejemplo, en un agente que usa Slack como su interfaz):

<trans>
$jitterbit.api.response = "{\"response_type\": \"ephemeral\", \"text\": \"Para conectar tu cuenta, abre este enlace: " + $authUrl + "\"}";
</trans>

Alternativamente, devuelve la URL como una respuesta de API simple o inclúyela en el cuerpo de un correo electrónico.

Parte 4: Manejar el callback e intercambiar el código de autorización

La operación OAuth Callback se ejecuta cuando el proveedor redirige el navegador del usuario a la URL de callback registrada. Debe extraer el código de autorización, servir una página de confirmación HTML al navegador, intercambiar el código por tokens y almacenar el token de actualización.

Paso 1: Extraer el código de autorización y servir la página de confirmación

En la operación OAuth Callback, abre el paso de script y agrega:

<trans>
$authCode = $jitterbit.api.request.parameters.code;

$jitterbit.api.response.body = "<html><body><h2>Connected successfully!</h2><p>You can close this window and return to the application.</p></body></html>";
$jitterbit.api.response.headers.Content_Type = "text/html";
$jitterbit.api.response.status_code = "200";

RunOperation("<TAG>Operations/Exchange Token</TAG>");
</trans>

$jitterbit.api.request.parameters.code contiene el código de autorización de la cadena de consulta de la URL de redirección. El cuerpo de la respuesta, el tipo de contenido y el código de estado establecidos aquí se devuelven al navegador cuando se completa la operación. RunOperation llama a la operación Exchange Token de forma sincrónica: el intercambio de tokens ocurre antes de que se devuelva la respuesta, y la variable global authCode está disponible para la operación llamada.

Paso 2: Configurar la conexión del endpoint de token

Crear un endpoint HTTP v2 conectado al endpoint de token del proveedor:

  1. En la pestaña Project endpoints and connectors de la paleta de componentes de diseño, hacer clic en HTTP v2 para abrir una nueva conexión.

  2. Connection Name: Ingresar un nombre (por ejemplo, Google OAuth).

  3. Base URL: Ingresar la URL base del endpoint de token del proveedor (por ejemplo, https://oauth2.googleapis.com).

  4. Authorization: Seleccionar No Auth. Las credenciales del cliente se incluyen en el cuerpo de la solicitud, no en un encabezado de autorización.

  5. Hacer clic en Test y luego en Save Changes.

Paso 3: Construir la operación Exchange Token

Crear una nueva operación llamada Exchange Token. Esta operación envía el código de autorización al endpoint de token y extrae los tokens devueltos.

Paso de script (antes de la actividad POST)

Construir el cuerpo de la solicitud codificado en forma:

<trans>
$tokenRequestBody = "code=" + URLEncode($authCode)
    + "&client_id=" + URLEncode($client_id)
    + "&client_secret=" + URLEncode($client_secret)
    + "&redirect_uri=" + URLEncode($redirect_uri)
    + "&grant_type=authorization_code";
</trans>

Actividad HTTP v2 POST

  1. Arrastrar una actividad POST desde el endpoint Google OAuth al lienzo de operaciones.

  2. Hacer doble clic en la actividad para abrir su configuración.

  3. Name: Ingresar Exchange Token POST o similar.

  4. Path: Ingresar /token.

  5. Request Headers: Agregar Content-Type / application/x-www-form-urlencoded.

  6. En el paso de esquema, proporcionar un esquema de solicitud con un único campo de texto (por ejemplo, body) para contener la cadena codificada en URL. En la transformación ascendente, asignar tokenRequestBody a este campo.

  7. Hacer clic en Finished.

Paso de script (después de la actividad POST)

Analizar la respuesta JSON y extraer los tokens:

<trans>
$refresh_token = TrimChars(GetJSONString($jitterbit.response, "/refresh_token"), "\"");
$access_token = TrimChars(GetJSONString($jitterbit.response, "/access_token"), "\"");
RunOperation("<TAG>Operations/Store Refresh Token</TAG>");
</trans>

$jitterbit.response contiene el cuerpo de respuesta sin procesar de la actividad POST. GetJSONString extrae campos individuales por ruta JSON. TrimChars elimina las comillas circundantes que GetJSONString incluye en su salida.

Paso 4: Almacenar el token de actualización

Crear una nueva operación llamada Store Refresh Token. Utilizar las actividades Insert Items y Update Items de Cloud Datastore con el patrón de consulta y ramificación para persistir el token de actualización con clave de un identificador de usuario único (por ejemplo, la dirección de correo electrónico del usuario o el ID de usuario de Slack). Asignar refresh_token al campo de token de actualización en el almacenamiento de Cloud Datastore.

Consultar Store and retrieve session state using Cloud Datastore para el patrón completo de consulta-inserción-actualización.

Advertencia

Cloud Datastore almacena datos en texto sin formato. No utilizarlo para almacenar el secreto del cliente ni ninguna otra credencial de aplicación. El token de actualización almacenado aquí tiene un alcance de usuario intencional y debe tratarse como información confidencial. Restringir el acceso al almacenamiento de Cloud Datastore a los entornos mínimos necesarios.

Parte 5: Actualizar el token de acceso en ejecuciones posteriores

Después de la autorización inicial, el token de actualización almacenado se puede intercambiar por un nuevo token de acceso sin interacción del usuario. Una operación Check Auth maneja esto y debe ejecutarse al inicio de cualquier cadena de operaciones que llame a la API de destino.

Crear la operación Check Auth

Crear una nueva operación llamada Check Auth. Agregar un paso de script con:

<trans>
RunOperation("<TAG>Operations/Query Token</TAG>");
If(length(trim($refresh_token)) == 0,
    RaiseError("No refresh token found. Run the Connect operation to authorize access.")
);
RunOperation("<TAG>Operations/Refresh Access Token</TAG>");
</trans>

La operación Query Token lee el token de actualización almacenado de Cloud Datastore en refresh_token (utilizando el mismo patrón de consulta por clave descrito en Store and retrieve session state using Cloud Datastore). Si no se encuentra ningún token, RaiseError detiene la cadena antes de que se intente realizar ninguna llamada a la API.

Crear la operación Refresh Access Token

Crear una nueva operación llamada Refresh Access Token. Agregar un paso de script seguido de una actividad HTTP v2 POST.

Paso de script

<trans>
$tokenRequestBody = "refresh_token=" + URLEncode($refresh_token)
    + "&client_id=" + URLEncode($client_id)
    + "&client_secret=" + URLEncode($client_secret)
    + "&grant_type=refresh_token";
</trans>

Actividad HTTP v2 POST: Usa la misma conexión de Google OAuth creada en Parte 4. Establece la ruta en /token y añade el encabezado Content-Type: application/x-www-form-urlencoded. Asigna tokenRequestBody al cuerpo de la solicitud en la transformación ascendente.

Paso de script (después de la actividad POST)

<trans>
$access_token = TrimChars(GetJSONString($jitterbit.response, "/access_token"), "\"");
</trans>

La variable access_token ahora está disponible para cualquier operación posterior en la cadena. Pásala como token Bearer en el encabezado Authorization de las solicitudes de API salientes:

<trans>
$jitterbit.api.request.headers.Authorization = "Bearer " + $access_token;
</trans>

Nota

La mayoría de proveedores de OAuth emiten tokens de acceso con una expiración corta (típicamente una hora). Llama a la operación Check Auth antes de cada llamada de API que requiera un token válido en lugar de almacenar el token de acceso entre ejecuciones.

Verifica la integración

  1. Implementa el proyecto.

  2. Ejecuta la operación Connect y abre la URL de autorización que produce en un navegador.

  3. Sigue el flujo de consentimiento de OAuth en el navegador. Después de aprobar el acceso, el navegador debe mostrar la página de confirmación HTML servida por la operación OAuth Callback.

  4. En Management Console > Cloud Datastore, abre el almacenamiento de claves y confirma que se ha creado un registro con el identificador de usuario esperado y un campo de token de actualización no vacío.

  5. Ejecuta la operación Check Auth manualmente. En el registro de operaciones, confirma que la operación Refresh Access Token se completó y que access_token no está vacío.

  6. Si el navegador muestra una página de error del proveedor en lugar de la página de confirmación:

    • Confirma que la variable de proyecto redirect_uri coincide exactamente con el URI registrado en la consola del proveedor, incluyendo esquema, host y ruta. Los proveedores de OAuth rechazan cualquier discrepancia.
    • Revisa los registros de API en API Manager para confirmar que la solicitud de devolución de llamada llegó al endpoint.

  7. Si la operación Exchange Token falla con una respuesta 400 o 401:

    • Confirma que client_id y client_secret están configurados correctamente.
    • Confirma que authCode no se ha usado ya. Los códigos de autorización son de un solo uso y expiran después de un período corto (típicamente 10 minutos).

  8. Si la operación Refresh Access Token falla con una respuesta 401, el token de actualización almacenado puede ser inválido o revocado. Ejecuta nuevamente la operación Connect para ese usuario a fin de obtener un nuevo token de actualización y actualiza el valor almacenado.