Autenticacion externa (External Authentication)

Autenticación externa

La autenticación externa permite que tu equipo de desarrollo autentique usuarios de la plataforma usando las credenciales de su propio sistema, antes de instalar la aplicación.

Esta funcionalidad te permite configurar campos de autenticación personalizados según lo que necesites, como:

• apiKey
• username
• password
• oauth 2.0

¿Cómo habilitar la autenticación externa en la aplicación?

Ve a Developer Marketplace > My Apps > selecciona tu app y da clic en la pestaña "External Authentication" del panel de navegacion. Se soportan API Key/Basic Auth y OAuth 2.0.

OAuth 2.0

Agregar autenticación OAuth v2 a apps del Marketplace

Este documento describe el proceso para configurar la autenticación OAuth 2.0 en llamadas externas dentro de apps del Marketplace. Actualmente solo se soporta el tipo de concesion "Authorization Code". La plataforma administra los pares de tokens y los incluye en acciones y disparadores personalizados, habilitando un amplio rango de posibilidades de integración.

1. Configuración

Sigue estos pasos para configurar la autenticación OAuth v2:

1. Detalles de la app y scopes: Ingresa el nombre de tu app externa, el client key y el client secret. Específica los scopes requeridos por tu integración externa, separados por espacios o comas. Incluye solo los scopes necesarios.
2. URL de redireccion: Copia la URL de redireccion provista en la configuración de tu app del Marketplace y pegala en la configuración de tu app externa.
3. Configuración de la URL de autorizacion: Configura la URL de autorizacion. El Marketplace pre-llena algunos campos estandar, que puedes ajustar según la documentación de la app externa. El parametro `state` es una caracteristica de seguridad estandar de OAuth2 que evita que terceros no autorizados inicien solicitudes de autorizacion. El Marketplace usa este parametro para verificar la validez de las respuestas — no lo modifiques para asegurar una integración sin problemas.
4. Configuración de la solicitud de tokens de acceso y actualización: Configura la solicitud de tokens según la documentación de la app externa. El Marketplace pre-llena algunas configuraciones estandar que puedes modificar. Da clic en "More Options" para agregar detalles adicionales de la llamada si los necesitas. Ejemplo de respuesta esperada:

   {
     "access_token": "your_access_token",
     "refresh_token": "your_refresh_token",
     "expires_in": 3600, // Ejemplo de tiempo de expiracion en segundos
   }
   

5. Renovacion automática del token (Auto Refresh Token): Activa esta opción para obtener automáticamente un nuevo par de tokens usando la API de renovacion cuando expiren. Si esta desactivada, la conexión se rompera al expirar el token y el usuario tendra que volver a autorizar la app. **Se recomienda activar esta opción** para una experiencia sin interrupciones.
6. API de prueba (Test API): Configura un endpoint de prueba (idealmente una llamada GET que no requiera configuración especial) para validar el token. La plataforma llamara a esta API para verificar que el token siga siendo valido. Si la prueba falla y la renovacion automática esta activa, el Marketplace intentara renovar el token. El token de acceso se incluye por defecto en todas las llamadas. Si tu API requiere configuración adicional para la llamada de prueba, usa "More Options".

Mecanismo de renovacion: solo se activa cuando un flujo de trabajo con acciones o disparadores personalizados esta por ejecutarse. El token de acceso se pasa a todas las llamadas externas involucradas en la configuración de esas acciones/disparadores.

Glosario

Parametros de OAuth

La siguiente tabla describe los parametros esenciales de OAuth usados en el flujo de autorizacion:

Parametros del token

Estos parametros se usan durante el intercambio de tokens de OAuth:

2. Probar la integración

Tu equipo puede probar la configuración usando la funcionalidad de prueba integrada, que inicia el proceso de OAuth con la app externa. Una vez generado el token, se llama a la API de prueba configurada. Asegurate de guardar toda la configuración antes de probar.

Nota importante: cambiar entre tipos de autenticación externa (por ejemplo, de Basic a OAuth) actualmente no esta soportado. [Proximamente]

API Key o Basic Auth

Hay tres secciones disponibles.

Sección 1: configura tus campos. Aquí defines los campos que tu app le pedira al usuario durante la instalación.

Para agregar un campo al formulario de autenticación del usuario, puedes configurar:

• Label: texto descriptivo del campo.
• Key: la llave que contiene el valor ingresado por el usuario. Puedes pasar ese valor a tu endpoint de autenticación (en encabezado o cuerpo) usando esta llave.
• Type: tipo de campo mostrado al usuario. Actualmente se soportan "text" y "password".
• Required: si el campo es obligatorio.
• Help Text: breve texto de ayuda mostrado al usuario.
• Default field: valor por defecto a enviar si el usuario deja el campo vacio.

NOTA: actualmente solo se soportan un máximo de tres campos.

Sección 2: configura el endpoint de autenticación. Aquí configuras la plantilla de solicitud HTTP que se ejecutara cuando un usuario intente instalar la aplicación.

Tipo de solicitud: puede ser "GET", "POST", "PUT" o "PATCH" (con GET no podras configurar el cuerpo de la solicitud). URL: la URL a la que se hara la solicitud. URL params: parametros que se enviaran con la solicitud. Encabezados HTTP: encabezados que se enviaran con la solicitud. Cuerpo de la solicitud: el cuerpo que se enviara con la solicitud.

NOTA IMPORTANTE:

1. Puede que necesites pasar el valor ingresado por el usuario (API Key/Username/Password) para la autenticación. Puedes acceder fácilmente a esos datos desde el objeto userData, que contiene la llave de cada campo y su valor, accesible con {{userData.key}}. Por ejemplo, si la llave de tu campo es apiKey, puedes acceder al valor ingresado con {{userData.apiKey}}.
2. Para que la verificación de autenticación externa se complete, la URL de autenticación debe devolver uno de estos códigos de estado: 200, 201, 202, 204.

Sección 3: prueba tu autenticación.
Aquí tu equipo puede probar el flujo de autenticación con valores de ejemplo.

Instalación de la aplicación: al momento de instalar, se le pedira al usuario llenar los campos que configuraste. Este es un ejemplo del formulario de autenticación mostrado al usuario durante la instalación.

Parametros de la solicitud de autenticación externa

Llave	Tipo	Detalle
companyId	string	Es igual al agencyId si la app fue instalada por una agencia. Es null si la app fue instalada por una sede.
{field_key}	string	La llave del parametro es la llave del campo. Puede haber un máximo de tres campos, y por tanto tres llaves. El valor corresponde a lo que respondio el usuario.
approveAllLocations	boolean	True — si se selecciono la casilla "Select all N sub-accounts" durante la instalación. False — si no se selecciono.
locationId	string[]	Si approveAllLocations = false, contiene un arreglo con los locationIds seleccionados durante la instalación. Si approveAllLocations = true, este parametro es null.
excludedLocations	string[]	Si approveAllLocations = false, este parametro es null. Si approveAllLocations = true, contiene un arreglo con los locationIds que NO se seleccionaron durante la instalación.

NOTA:

• En solicitudes POST, PATCH y PUT, estos campos se envian como parte del cuerpo.
• En solicitudes GET, se envian como parametros.

Ejemplos:

• Supongamos que una agencia tiene 5 sedes: A, B, C, D, E.
• La app requiere dos campos: "username" y "password".
• Escenario 1: el usuario selecciona la sede A al instalar la app
  

{
"companyId": "123",
"locationId": {"A"},
"username" : "user1",
"password" : "password123",
"approveAllLocations": false,
"excludedLocations": null
}

• Escenario 2: el usuario selecciona las sedes A y B

{
"companyId": "123",
"locationId": {"A","B"},
"username" : "user1",
"password" : "password123",
"approveAllLocations": false,
"excludedLocations": null
}

• Escenario 3: el usuario selecciona "Seleccionar las 5 sedes"

{
"companyId": "123",
"locationId": null,
"username" : "user1",
"password" : "password123",
"approveAllLocations": true,
"excludedLocations": null
}

• Escenario 4: el usuario selecciona "Seleccionar las 5 sedes", pero desmarca las sedes C y D

{
"companyId": "123",
"locationId": null,
"username" : "user1",
"password" : "password123",
"approveAllLocations": true,
"excludedLocations": {"C","D"}
}