Incorporación de OAuth2 al nodo API en flujos de trabajo de DANAconnect

Autenticación en DANAconnect: de Basic Auth a OAuth2

Tradicionalmente, DANAconnect ha utilizado autenticación básica (Basic Auth) en las solicitudes realizadas desde los nodos API dentro de los flujos de trabajo. Sin embargo, a partir de marzo de 2025, se ha agregado también la posibilidad de utilizar OAuth2 en el nodo API Plus, proporcionando una capa adicional de seguridad y control en las integraciones.

Con este cambio, los clientes pueden optar por OAuth2 para autenticarse en las API utilizadas en sus flujos de trabajo, evitando el uso directo de credenciales estáticas y mejorando la seguridad de los accesos.

¿Qué es OAuth2 y por qué es importante?

OAuth2 es un protocolo de autorización ampliamente utilizado para permitir que aplicaciones accedan a recursos protegidos sin necesidad de compartir credenciales de usuario directamente. En DANAconnect, integrar OAuth2 en los nodos API dentro de los flujos de trabajo garantiza:

Mayor seguridad: evita el uso de credenciales en cada solicitud.
Autenticación centralizada: permite gestionar accesos mediante un proveedor de identidad.
Compatibilidad con estándares modernos: facilita la integración con APIs de terceros.

¿Cómo Acceder a la configuración de OAuth2 en el nodo API de Conversaciones?

Para solicitar acceso a la pantalla de configuración de OAuth2 del nodo API de Conversaciones, es necesario ponerse en contacto con tu Account Manager en DANAconnect. El proceso es el siguiente:

Contacte a tu Account Manager designado.
Una vez que recibas confirmación de su Account Manager podrás ver la opción de agregar credenciales OAuth2 en la pestaña de Authorization del Nodo API Plus como se muestra en la imagen a continuación:

Configuración del nodo API con Credenciales OAuth2 en DANAconnect

Para integrar OAuth2 en un nodo API dentro de un flujo de trabajo en DANAconnect, sigue estos pasos:

1. Configurar el nodo API

Dentro del flujo de trabajo, agrega un nuevo nodo API.
Asigna un nombre descriptivo al nodo API.

2. Definir el método y la URL de la API

En la configuración del nodo, selecciona el método HTTP adecuado: POST, GET, PUT, DELETE.
Ingresa la URL del servicio API al cual quieres hacer la petición.

3. Configurar OAuth2 en la autenticación

En la pestaña Config, elige OAuth (client-credentials) como tipo de autenticación y completa los datos de la pantalla de configuración.

3.1 Token URL

3.1.1 Token URL si la API es de DANAconnect:

Si estás consumiendo una API propia de DANAconnect dentro de un flujo de trabajo, entonces el token de acceso debe estar asociado a DANAconnect. Esto significa que:

DANAconnect actúa como el proveedor de autenticación (Authorization Server).
La aplicación o flujo de trabajo solicita un token a DANAconnect.
Ese token luego se usa para autenticar las llamadas a la API de DANAconnect.

Dado que la API es de DANAconnect, el Token URL debe ser el de DANAconnect https://auth.danaconnect.com/oauth2/token En este caso, DANAconnect genera y valida el token.

3.1.2 Token URL si la API es de un tercero (un organismo externo a DANAconnect)

Si el flujo de trabajo de DANAconnect necesita conectarse con una API externa (por ejemplo, una API gubernamental o bancaria), entonces el token debe ser emitido por el organismo que proporciona la API. En este caso:

El organismo externo actúa como el proveedor de autenticación.
Se debe usar el Token URL que ofrece este proveedor para obtener el token de acceso.
Luego, el token se usa para autenticarse en la API externa.

Si la API pertenece a un ente regulador que requiere autenticación OAuth2, entonces el Token URL debe ser el que provea ese organismo, no el de DANAconnect.

3.2. Scopes:

Los scopes en OAuth2 son permisos que definen qué acciones puede realizar un cliente cuando accede a una API. Actúan como restricciones para limitar el acceso a solo ciertas partes de los datos o funciones del servicio.

Cuando un cliente solicita un token de acceso, puede especificar uno o más scopes. Luego, la API evalúa si el cliente tiene permisos para esos scopes y devuelve un token con los permisos otorgados.

Supongamos que una API ofrece acceso a datos de usuarios. Podría definir scopes como:

read_users: Permite leer datos de usuarios, pero no modificarlos ni eliminarlos.
write_users: Permite modificar datos de usuarios.
delete_users: Permite eliminar usuarios.

3.3. Username y Password:

Si está haciendo una solicitud a un API de DANAconnect deberá pedir las credenciales a su Account Manager asignado. En el caso de ser un API de un tercero, deberá solicitar las credenciales a su proveedor externo.

4. Manejo de la respuesta

Marca la opción Save response code para registrar la respuesta de la API en la lista de contacto (se asigna el campo de la lista de contacto en donde se almacena el response en el momento de la Activación de la Conversación)
Define las rutas de éxito y error:

Success Path: Este campo debe configurarse según la estructura de la respuesta JSON de la API. En el ejemplo de la imagen, se usa $.valid, lo que indica que se espera obtener un dato valido ( valid) en la raiz del JSON de respuesta. Sin embargo, este valor puede cambiar según la API utilizada. Se recomienda revisar la documentación de la API que está llamando para definir el campo correcto.

Failure Path: Permite configurar un campo de prioridad en caso de error para manejar adecuadamente las respuestas no esperadas.

5. Agregar Campos a Actualizar (Opcional)

En esta sección es posible agregar códigos de los campos de la lista de contacto en donde se quieran almacenar información proveniente de la respuesta del API.

Haga clic en el botón Agregar Campo a Actualizar
En la columna de la izquierda agregue el FIELDCODE de la lista de contactos
En la columna derecha agregue el JsonPath o XmlPath de la respuesta del API donde se encuentra localizada la data que desea guardar.

6. Guardar y probar

Guarda la configuración y realiza una prueba para validar que el nodo se autentique correctamente y la API responda según lo esperado.

Actualizado el: 05/03/2025