Saltar al contenido

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

Introducción

El flujo de autorización de código 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 punto de retorno, intercambiar el código por tokens de acceso y de actualización, almacenar el token de actualización en Cloud Datastore y refrescar el token de acceso en ejecuciones posteriores sin interacción del usuario.

Los ejemplos en esta guía utilizan Google como el proveedor de autorización. El mismo patrón se aplica a cualquier proveedor OAuth 2.0 que soporte el tipo de concesión de código de autorización: reemplaza las URL, los alcances y los nombres de parámetros específicos del proveedor 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 usuario.

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

Esta guía asume:

  • Se ha configurado y publicado una API personalizada en API Manager en el mismo entorno que el proyecto.
  • Existe o se creará un almacenamiento de claves en Cloud Datastore para mantener registros de tokens por usuario. Consulta Almacenar y recuperar el 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 autorización de código 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 su uso futuro. La operación Check Auth se ejecuta antes de cualquier llamada a la API: lee el token de actualización almacenado de Cloud Datastore y lo intercambia por un nuevo token de acceso.

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 del proyecto.

Registrar la aplicación

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

  • URIs de redirección autorizados: Agrega la URL completa del punto final de callback que crearás en Parte 2. Por ejemplo: https://<tu-agente-host>/<entorno>/<versión>/<raíz-del-servicio>/oauth/callback. Debes conocer esta URL antes de completar el registro.

El proveedor emitirá un ID de cliente y un Secreto de cliente.

Almacenar credenciales como variables del proyecto

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

  • client_id: El ID de cliente de la aplicación OAuth emitido por el proveedor.
  • client_secret: El secreto de cliente de la aplicación OAuth.
  • redirect_uri: La URL completa de callback configurada en la consola del proveedor.

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

Consejo

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

Parte 2: Crear el punto final de callback

El punto final 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 para 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 el primer paso. Deja el cuerpo del script vacío por ahora. Agregarás la lógica de callback en Parte 4.

Publicar la operación de callback como un punto final de API

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

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

Copia la URL del punto final publicado. Úsala como el valor de la variable de proyecto redirect_uri y regístrala con el proveedor como una URI de redirección autorizada.

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 la aplicación solicita. Separa múltiples scopes con espacios y codifica la cadena combinada usando URLEncode. Ajusta los valores de scope para que coincidan con lo que tu API de destino requiere.
  • access_type=offline: Indica al proveedor que emita un token de actualización además del token de acceso.
  • prompt=consent: Obliga a que aparezca la pantalla de consentimiento incluso si el usuario ha autorizado previamente la aplicación. Esto asegura que se emita un nuevo token de actualización cada vez.

Reemplace la URL del endpoint de autorización de Google y los valores de alcance con los de su proveedor objetivo.

Entregar la URL al usuario

Después de construir la URL, entréguela 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 utiliza Slack como su interfaz):

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

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

Parte 4: Manejar la devolución de llamada 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 devolución de llamada 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, abra el paso del script y agregue:

<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 la operación se completa. 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

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

  1. En la pestaña Endpoints y conectores del proyecto del paleta de componentes de diseño, haga clic en HTTP v2 para abrir una nueva conexión.

  2. Nombre de la conexión: Ingrese un nombre (por ejemplo, Google OAuth).

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

  4. Autorización: Selecciona Sin autenticación. Las credenciales del cliente se incluyen en el cuerpo de la solicitud, no en un encabezado de autorización.

  5. Haz clic en Probar, luego en Guardar cambios.

Paso 3: Construir la operación de intercambio de token

Crea 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)

Construye el cuerpo de la solicitud codificado en formulario:

<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. Arrastra una actividad POST desde el endpoint de Google OAuth al lienzo de la operación.

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

  3. Nombre: Ingresa Exchange Token POST o similar.

  4. Ruta: Ingresa /token.

  5. Encabezados de solicitud: Agrega Content-Type / application/x-www-form-urlencoded.

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

  7. Haz clic en Terminado.

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

Analiza la respuesta JSON y extrae 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 mediante la ruta JSON. TrimChars elimina las comillas alrededor que GetJSONString incluye en su salida.

Paso 4: Almacenar el token de actualización

Crea una nueva operación llamada Store Refresh Token. Utiliza las actividades de Cloud Datastore Insertar elementos y Actualizar elementos con el patrón de consulta-luego-ramificación para persistir el token de actualización clave por un identificador de usuario único (por ejemplo, la dirección de correo electrónico del usuario o el ID de usuario de Slack). Mapea refresh_token al campo de token de actualización en el almacenamiento de Cloud Datastore.

Consulta Almacenar y recuperar el estado de la sesión usando Cloud Datastore para el patrón completo de consulta-inserción-actualización.

Advertencia

Cloud Datastore almacena datos en texto plano. No lo utilices para almacenar el secreto del cliente ni ninguna otra credencial de la aplicación. El token de actualización almacenado aquí está intencionalmente limitado al usuario y debe ser tratado como sensible. Restringe el acceso al almacenamiento de Cloud Datastore a los entornos mínimos necesarios.

Parte 5: Actualiza el token de acceso en ejecuciones posteriores

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

Crear la operación Check Auth

Crea una nueva operación llamada Check Auth. Agrega 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 desde Cloud Datastore en refresh_token (utilizando el mismo patrón de consulta-por-clave descrito en Almacenar y recuperar el estado de la sesión usando Cloud Datastore). Si no se encuentra ningún token, RaiseError detiene la cadena antes de que se intente cualquier llamada a la API.

Crear la operación Refresh Access Token

Crea una nueva operación llamada Refresh Access Token. Agrega 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: Utiliza la misma conexión de Google OAuth creada en Parte 4. Establece la ruta a /token y agrega el encabezado Content-Type: application/x-www-form-urlencoded. Mapea 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 subsiguiente en la cadena. Pásala como un token Bearer en el encabezado Authorization de las solicitudes API salientes:

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

Nota

La mayoría de los 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 a la API que requiera un token válido en lugar de almacenar el token de acceso entre ejecuciones.

Verificar la integración

  1. Desplegar el proyecto.

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

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

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

  5. Ejecutar manualmente la operación Check Auth. En el registro de operaciones, confirmar 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:

    • Confirmar que la variable del proyecto redirect_uri coincide exactamente con la URI registrada en la consola del proveedor, incluyendo esquema, host y ruta. Los proveedores de OAuth rechazan cualquier discrepancia.
    • Revisar los registros de API en API Manager para confirmar que la solicitud de callback llegó al endpoint.

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

    • Confirmar que client_id y client_secret están configurados correctamente.
    • Confirmar que authCode no se ha utilizado ya. Los códigos de autorización son de un solo uso y expiran después de un corto período (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 haber sido revocado. Vuelve a ejecutar la operación Connect para ese usuario para obtener un nuevo token de actualización y actualizar el valor almacenado.