🔧 Sincronización de suscriptores por LDAP o AzureAD

Sincronización de Suscriptores desde un directorio activo

Si tu organización cuenta con un directorio activo puedes instalar el agente de sincronización de mensajería para poder registrar, actualizar y eliminar suscriptores de manera masiva sin necesidad de tener que realizar este proceso manualmente desde tu cuenta.

Actualmente se soportan dos fuentes de información:

1. Directorio Activo que soporte el protocolo LDAP

2. Azure AD utilizando el Graph API de Microsoft

El agente de sincronización puede ser desplegado de tres maneras:

1. Puedes crear una tarea programada y ejecutar el agente según la frecuencia deseada. Este proceso lo puedes realizar en sistemas operativos Windows y Linux

2. Puedes desplegar el agente cómo una función lambda en AWS y ejecutar la función según la frecuencia deseada desde un evento programado en CloudWatch.

3. Puedes desplegar el agente cómo una función en Azure (Azure Function) y configurar un trigger de lanzamiento.

Sincronización LDAP

1. El administrador debe configurar su cuenta para que se puedan registrar suscriptores utilizando LDAP.

2. Se debe configurar un cliente de sincronización para que revise la información de los suscriptores de manera periódica. Este componente puede ser desplegado en una función Lambda en AWS o en un servidor.

3. Los suscriptores se pueden registrar sin necesidad de ingresar un código de activación.

Sincronización AzureAD

1. El administrador debe configurar su cuenta para que se puedan registrar suscriptores utilizando AzureAD

2. Se debe configurar un cliente de sincronización para que revise la información de los suscriptores de manera periódica. Este componente puede ser desplegado en una función Lambda en AWS, una función en Azure o en un servidor (Programa de línea de comandos).

3. Los suscriptores se pueden registrar sin necesidad de ingresar un código de activación.

En las siguientes secciones puedes encontrar instrucciones detalladas para la descarga y ejecución de este componente.

Prerequisitos generales

Debes tener presente los siguientes puntos para proceder con la instalación, configuración y ejecución del agente de sincronización:

1. Debes tener una cuenta existente en nuestra plataforma Arkbox.

Se te solicitará en un paso que indiques la url(enlace) que utilizas para acceder a la consola de administración (Ej: example.arkbox.co )

2. El agente requiere de un usuario que ya esté registrado en tu cuenta Arkbox, por lo que te sugerimos crear uno exclusivamente para esto que cuente con un nombre de usuario o correo electrónico y la contraseña. Dicho usuario debe tener asignados todos los permisos del módulo suscriptores.

3. Si deseas realizar la sincronización utilizando LDAP debes contar con un usuario de lectura del directorio, así como con la información del servidor y la estructura de la organización.

4. Si deseas realizar la sincronización utilizando AzureAD debes registrar una aplicación de tipo ‘Service/Daemon’ en la consola de administración de Azure con permisos de lectura sobre los usuarios. Para esto, debes generar una clave secreta.
Puedes encontrar mas información en enlace a continuación:
Registrar una aplicación para el uso de Microsoft Graph

Instalación y configuración del agente en AWS - Lambda Function

1. Debes descargar el agente haciendo clic en el siguiente enlace:
   Agente de Sincronizacón de Mensajería - AWS Lambda Function

2. Es necesario que configures las variables de la función siguiendo la estructura definida en la sección Configuraciones del agente de sincronización

3. Debes crear un evento en CloudWatch que ejecute de manera periódica la función.

Instalación y configuración del agente en Azure - Azure Function

1. Debes descargar el agente haciendo clic en el siguiente enlace:
   Agente de Sincronizacón de Mensajería - Azure Function

2. La manera más ágil de publicar una función utilizando un paquete zip es utilizando la consola de Azure Cloud. Debes seguir las instrucciones indicadas en el enlace a continuación:
   Implementación con la CLI de Azure.

Recuerda que deberá subir el paquete descargado en el paso 1 a un fileshare para que lo puedas referenciar desde la consola.

3. Debes dirigirte a la sección Settings > Configuration > Application settings y configurar las variables de la función siguiendo la estructura definida en la sección Configuraciones del agente de sincronización

4. Debes validar que la función haya sido creada en la sección Functions y que el disparador de la función corresponda a un trigger con la siguiente regla de ejecución:
0 0 5 * * *
Esto hará que se ejecute dicha función todos los días a las 5:00 a.m.

Puedes cambiar esta cofiguración según tus necesidades.

Instalación y configuración del agente en Sistema Operativo Windows

El agenge de sincronización se ejecuta cómo un programa de consola y a través de una tarea programada del sistema se programa su lanzamiento según la frecuencia deseada. Recomendamos realizar la sincronización al menos una vez cada día para garantizar que los usuarios modificados, registrados o eliminados se vean reflejados en nuestra plataforma.
Realice los siguientes pasos para configurar el agente:

1. Descargar el agente en el siguiente enlace: Agente de Sincronizacón de Mensajería (x86) ó desde el enlace Agente de Sincronizacón de Mensajería (x64) si su sistema operativo es de 64Bits

2. Descomprimir el agente en una carpeta del sistema. Este agente se deberá ejecutar por fuera de sesión por lo que sugerimos descomprimirlo en una carpeta que no pertenezca al usuario logueado. Mas adelante se le indicará realizar una tarea con el archivo Arkbox.Messaging.Synchronizer.Runner.exe. Tenga presente la ubicación de este archivo.

3. Proveder las credenciales y configuraciones necesarias para la configuración del cliente. En la sección Configuraciones del agente de sincronización se encuentra la descripción de las configuraciones de la aplicación.

Configuraciones del agente de sincronización

La ejecución del agente requiere proveer un conjunto de configuraciones para garantizar el correcto funcionamiento de este. El archivo de descarga contiene ejemplos de los archivos de configuración. Debes utilizar los archivos que se requieren y renombrarlos retirando la palabra example.

Estas configuraciones pueden ser darse a través de dos mecanismos:

1. Si vas a ejecutar el agente como una función lambda en AWS o una Azure Function debes proporcionar las configuraciones a través de las variables de entorno de dicha función.

2. Si vas a ejecutar el agente como un programa de consola debes proveer dos archivos de configuración en la carpeta Configuration:

   1. application-settings.json Configuraciones generales del agente.

   2. XXXX-reader.json Configuraciones del lector de información.
      El valor XXXX puede corresponder a la implemntación usando LADP > ldap-reader-settings.json o la implementacion usando Azure AD > azuread-reader-settings.json

Configuraciones de aplicación

Estas configuraciones permiten al agente comunicarse con nuestros servidores y realizar las operaciones de sincronización de suscriptores.

La columna Propiedad json hace referencia a los campos del archivo application-settings.json. Este archivo se encuentra en la carpeta Configuration y está definido de la siguiente manera:

{
  "host": "https://example.arkbox.co",
  "username": "username",
  "password": "password",
  "allowRemoval": true,
  "synchronizationFields": "SystemId,Name,Email,CountryCode,PhoneNumber,Area,JobTitle",
  "comparisonFields": "SystemId",
  "subscriptionMethod": "LDAP",
  "enableDetailedLogging": false,
  "tester": false
}

Debes abrir el archivo con tu editor de preferencia y modificarlo siguiendo las indicaciones de la tabla a continuación.
En ella definimos el uso de cada una de las posibles configuraciones:

Las propiedades y valores deben respetar las reglas de mayúsculas y minúsculas sugeridas en la tabla (Case sensitive)

Configuraciones del lector de información

Estas configuraciones permiten al agente obtener la información de los suscriptores desde una fuente externa (LDAP o AzureAD).

Cada tipo de fuente define un conjunto de configuraciones.

Configuraciones del lector LDAP

La columna Propiedad json hace referencia a los campos del archivo ldap-reader-settings.json. Este archivo se encuentra en la carpeta Configuration y está definido de la siguiente forma:

{
  "host": "172.16.0.1",
  "port": "389",
  "path": "cn=Users,dc=contoso,dc=local",
  "username": "CN=username,OU=branch,DC=contoso,DC=local",
  "password": "password",
  "domain": "contoso.local",
  "searchFilter": "(&(objectClass=user)(objectClass=person))",
  "userAttributes": "objectSid,objectGUID,title,mail,displayName,telephoneNumber,sAMAccountName"
}

En la siguiente tabla definimos el uso de cada una de las posibles configuraciones:

Configuraciones del lector AzureAD

La lectura de los usuarios de AzureAD se logra utilizando el Graph de Microsoft. Debes registrar una aplicación y generar las credenciales necesarias para permitir la consulta de los usuarios.

Puedes encontrar mas información en enlace a continuación:
Registrar una aplicación para el uso de Microsoft Graph

La columna Propiedad json hace referencia a los campos del archivo azuread-reader-settings.json. Este archivo se encuentra en la carpeta Configuration y está definido de la siguiente forma:

{
  "tenantId": "guid",
  "clientId": "guid",
  "clientSecret": "secret",
  "groupId": "guid"
}

En la siguiente tabla definimos el uso de cada una de las posibles configuraciones:

Ejecución del agente

Si despliegas el agente en un sistema operativo Windows o Linux debes crear una tarrea recurrente indicando el archivo de ejecución y configurando la frecuencia de lanzamiento deseada.

Configuración de tarea programada en Windows

Para crear una tarea programada debes seguir los siguientes pasos:

1. Debes abrir el programador de tareas seleccionando Menú inicio > Programador de Tareas. Ó puedes abrir una ventana de ejecución (Tecla Windows + R) y ejecutar el comando taskschd.msc

2. Debes ubicar y seleccionar biblioteca de tareas programadas en el panel izquierdo.

3. Luego debes seleccionar la opción Crear tarea básica en el panel derecho.
   Se te abrirá una ventana con un asistente.

4. Ahora debes asignar un nombre para la tarea. Ej: Programa de sincronización de Arkbox Mensajería

5. Debes hacer clic en Siguiente y seleccionar el tipo de frecuencia.
   Sugerimos una frecuencia diaria.

6. En la siguiente ventana debes configurar la fecha de inicio del programa y los paramétros de recurrencia.

7. Ahora debes hacer clic en Siguiente para configurar la acción de lanzamiento.

8. Luego debes seleccionar Lanzar un programa.

9. Debes hacer click en explorar y ubicar el archivo Arkbox.Messaging.Synchronizer.Runner.exe

10. A continuación debes hacer clic en Siguiente y revisar el resumen de la tarea.
    Puedes editar estos parámetros luego de crear la tarea.

11. Si validando ves que todo se encuentra bien debes hacer clic en Finalizar.

12. Para garantizar que la tarea se ejecute cuando se inicia sesión debes ingresar a las propiedades de la tarea y modificar la propiedad Ejecutar tanto si inició sesión como si no.
    Se te va a pedir que ingreses tu usuario y contraseña nuevamente para confirmar esta acción.