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

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

Ejecuci贸n como tarea programada

Ejecuci贸n como tarea programada

  1. Debes tener permisos suficientes en el sistema para crear tareas programadas sin la necesidad de una sesi贸n activa.

  2. El equipo donde instales el agente debe tener acceso de red para comunicarse con nuestros servidores.
    Deber谩s revisar el enlace de Puertos y recursos para mayor informaci贸n.

Ejecuci贸n c贸mo funci贸n lambda en AWS

Ejecuci贸n c贸mo funci贸n lambda en AWS

  1. Debes tener una cuenta activa de AWS con unas Credenciales a la consola web

  2. Para realizar el proceso, tu usuario debe contar con los permisos necesarios para administrar los recursos de la funci贸n:

    1. Permisos para crear, actualizar y ejecutar una funci贸n Lambda

    2. Permisos para programar un evento peri贸dico en CloudWatch

    3. Debes asignar un Rol de ejecuci贸n a la funci贸n que le permita acceder a internet o al los recursos del directorio activo que deseas configurar

Ejecuci贸n c贸mo Azure Function

Ejecuci贸n c贸mo Azure Function

  1. Debes tener una cuenta activa de Azure con unas Credenciales a la consola web

  2. Para realizar el proceso, tu usuario debe contar con los permisos necesarios para crear/publicar una funci贸n lambda

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
}
CODE

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)

Nombre

Variable de entorno (AWS Lambda / Azure Function)

Propiedad json (Archivo de configuraci贸n)

Requerido

Valor por defecto

Descripci贸n

Servidor

app_host

host

SI

n/a

Url de la consola de administraci贸n Ej: example.arkbox.co

Usuario

app_username

username

SI

n/a

Usuario para el acceso a la consola de administraci贸n (Plataforma CMS)

Contrase帽a

app_password

password

SI

n/a

Contrase帽a del usuario

M茅todo sincronizaci贸n

app_subscriptionMethod

subscriptionMethod

SI

n/a

Sincronizaci贸n LDAP: LDAP En este caso se proceder谩 a leer las configuraciones definidas en Configuraciones del lector LDAP. Sincronizaci贸n AzureAD: AzureAD En este caso se proceder谩 a leer las configuraciones definidas en Configuraciones del lector AzureAD

Hablitar eliminaci贸n

app_allowRemoval

allowRemoval

NO

false

Si el valor es true se podr谩n eliminar suscriptores no exisentes en la cuenta de Arkbox

Modo pruebas

app_tester

tester

NO

false

Si el valor es true no se realizar谩 ninguna operaci贸n de escritura, actualizaci贸n 贸 eliminaci贸n en el server de Arkbox. S贸lo se mostrar谩 en consola la informaci贸n

Habilitar logging detallado

app_enableDetailedLogging

enableDetailedLogging

NO

false

Si esta opci贸n est谩 habilitada se mostrar谩 una lista en consola de los suscriptores que se procesan

Campos de sincronizaci贸n

app_synchronizationFields

synchronizationFields

NO

SystemId, Name, Email, CountryCode, PhoneNumber, Area, JobTitle

Indica los campos a registrar de un suscriptor

Campos de comparaci贸n

app_comparisonFields

comparisonFields

NO

SystemId

Indica la(s) columan(s) local(es) para identificar un regsitro indiviualmente. S贸lo se permiten los valores SystemId y/o Email

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"
}
CODE

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

Nombre

Variable de entorno (AWS Lambda / Azure Function)

Proopiedad json

Requerido

Valor por defecto

Descripci贸n

Servidor

reader_host

host

SI

n/a

Url o host del servidor LDAP sin indicar el esquema Ej: 172.16.0.1 贸 CompanyServer01

Puerto

reader_port

port

NO

389

Puerto de conexi贸n LDAP. Usualmente se utiliza el puerto 389 para conexiones no seguras y el 636 para conexiones seguras

Path

reader_path

path

SI

n/a

Indica la ruta (Conjunto de RDN) del directorio que se consultar谩. Ej: cn=Users,dc=contoso,dc=local

Usuario

reader_username

username

SI

n/a

Este valor corresponde al nombre distinguido (DN) del usuario registrado en el directorio con permisos de lectura sobre el path definido en la configuraci贸n anterior

Contrase帽a

reader_password

password

SI

n/a

Contrase帽a del usuario

Dominio

reader_domain

domain

SI

n/a

Indicar el dominio base de la organizaci贸n. Ej: contoso.local

Filtro

reader_searchFilter

searchFilter

NO

(&(objectClass=user)(objectClass=person))

Este es el filtro utilizado para realizar la consulta de los usuarios en la ruta definida previamente

Atributos de usuario

reader_userAttributes

userAttributes

NO

objectSid, objectGUID, title, mail, displayName, telephoneNumber, sAMAccountName

Estos ser谩n los atributos que se obtendr谩n del usuario. Si el atributo mail no se encuentra definido se construir谩 as铆: sAMAccountName + @domain

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"
}
CODE

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

Nombre

Variable de entorno (AWS Lambda / Azure Function)

Proopiedad json

Requerido

Valor por defecto

Descripci贸n

Id de cuenta

reader_tenantId

tenantId

SI

n/a

Es un Id tipo GUID utilizado para identificar la cuenta del dominio

Id de cliente

reader_clientId

clientId

SI

n/a

Es un Id tipo GUID utilizado para identificar la aplicaci贸n registrada

Clave secreta

reader_clientSecret

clientSecret

SI

n/a

Permite a la aplicaci贸n generar tokens de autenticaci贸n para las operaciones sobre el Graph

Id de grupo

reader_groupId

groupId

NO

n/a

Si se define este campo se filtrar谩 la consulta de usuarios s贸lo relacionados al grupo indicado

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.