Servicios y Authkeys

Servicios

Descripción

Cada instancia de ZofToken puede tener un número ilimitado de servicios configurados.

Todos los tokens que pertenezcan al mismo servicio tendrán la misma configuración por lo cual los servicios pueden usuarse para agrupar a los usuarios de acuerdo a los requerimientos de negocio que correspondan. El acceso a través de la API a los servicios (por ejemplo, poder solicitar el estado de un token o enrolar uno nuevo) es granular y puede ser configurado a través de los authkeys que se describen en la próxima sección.

La configuración mínima tiene un único servicio al cual pertenecen todos los tokens, mientras que una más compleja podría incluir por ejemplo cuatro servicios: uno para usuarios internos normales (usado para su acceso a alguno de los sistemas de la organización), uno para usuarios internos de IT (usado para el acceso administrativo a ciertos activos críticos), uno para la mayoría de usuarios/clientes externos (utilizado para proteger el acceso o las transacciones de una aplicación web como podría ser un sistema de Home Banking) y una para usuarios externos "premium" (utilizado con el mismo fin que el anterior pero con una configuración diferente para permitir la utilización de la función de coacción).

Parámetros

Cada servicio cuenta con los siguientes parámetros:

Parámetro	Descripción
Nombre	Este es el nombre interno del servicio utilizado en la API.
Duración (o ventana) del token	Para que la utilización de tokens sea más amigable, una vez que un usuario abre su token, la instancia de ZofToken lo va a considerar abierto durante el número de segundos definido por este parámetro. Este le permite al usuario abrir su token antes de acceder a una aplicación web y no tener que interactuar con el mismo por un período de tiempo que sea razonable para una sesión normal (por ejemplo, entre 10 y 15 minutos). Configurar este parámetro en 0 elimina esta funcionalidad y cada interacción con los tokens deberá ser manejada a través de un webhook. Dado que esta configuración limita la simplicidad de integración de ZofToken con sistemas existentes, se recomienda que solo se utilice en casos que existan razones de negocio apropiadas.
Webhook	Este parámetro opcional instruye al servidor de ZofToken a llamar a un webhook específico en distintos momentos durante el ciclo de vida del token. Hay tres componentes de la configuración de un webhook: Nombre del servidor: esto tiene que ser un servidor (potencialmente incluyendo un puerto, que por defecto es 443) que acepte conexiones HTTPS dado que ZofToken no ejecutará webhooks no encriptados. Un valor que indica si ZofToken debe verificar o no el certificado presentado por el servidor durante la conexión HTTPS. En la mayoría de los casos esto debería estar activado, pero para webhooks que se ejecuten en redes internas con certificados auto-firmados o en situaciones donde no se cuente con un certificado válido, se debe deshabilitarlo o ZofToken no realizará la conexión. Una cadena de texto que opera como un secreto para que el servidor de ZofToken envíe con cada llamado del webhook, lo cual le permite a la aplicación que esté recibiendo el webhook verificar que el llamado efectivamente llegó desde el servidor de ZofToken. Por lo anterior se recomienda usar un secreto razonablemente seguro (por ejemplo, un conjunto de al menos 20 caracteres elegidos al azar). Una vez que el webhook está configurado, el servidor de ZofToken realizará los llamados utilizando el método GET y con los siguientes parámetros: secret: el secreto descrito previamente. id: el nombre de usuario/identificación del token. service: el nombre del servicio del cual forma parte el token. event: una descripción del evento que ocurrió con el token, tomando de la siguiente lista "enrolled": el token completó el proceso de enrolamiento y ahora se encuenta activo. "blocked": el token ha sido bloqueado. "open": el token ha sido abierto/activado. "closed": el token ha sido cerrado/desactivado (nota: si se configuró una duración/ventana para el token, la expiración de esta duración no llamará a este webhook). "duress": la última operación realizada con el token (apertura o cierre) fue realizada bajo coacción.
Función de coacción	Este parámetro indica si la función de coacción está habilitada para este servicio o no. Dado que esta es una decisión importante con consecuencias posiblemente relevantes (especialmente para usuarios externos), se recomienda leer la sección de la documentación asociada a esta función.
Detalles	Nota: este parámetro es utilizado exclusivamente por ZofToken Universal App y es provisto automáticamente por ZaaS por lo cual la siguiente descripción aplica solamente a instalaciones privadas de ZofToken Server que utilicen la aplicación de referencia. Este parámetro es una URL que debe retornar un objeto JSON que configura como el servicio aparecerá al usuario dentro de ZofToken Universal App. El formato de dicho objeto JSON es el siguiente: { "logo": imagen correspondiente al logo de la organización/servicio, "friendly_name": "Servicio de Ejemplo", "service_description": "Este es un servicio de ejemplo", "error_contact": "Por favor llamar al 111-1111 para solicitar ayuda", "offline_description": "Por favor llamar al 222-2222 para utilizar el modo fuera de línea" } La primer propiedad es una representación en BASE64 de un archivo de imagen PNG que se mostrará como el logo del token dentro de ZofToken Universal App, mientras que el resto de los campos representan un nombre amigable del servicio a mostrar al usuario, una descripción del mismo y las instrucciones para solicitar ayuda y para utilizar el modo fuera de línea. Según se describe en la documentación de instalación, se recomienda crear una cuenta gratuita de ZaaS para experimientación y realización de pruebas, lo cual además permitirá crear en forma automática este objeto a través de una interface de usuario simple.
Conexiones entrantes	Nota: este parámetro es utilizado exclusivamente por ZofToken Universal App y es provisto automáticamente por ZaaS por lo cual la siguiente descripción aplica solamente a instalaciones privadas de ZofToken Server que utilicen la aplicación de referencia. Este parámetro contiene la lista de servidores y números de puertos UDP que se le enviarán a ZofToken Universal App cuando se enrola un token a este servicio. Cada combinación de servidor y puerto debe ser un ZofToken Server que es parte de la misma instancia (es decir, conectado a la misma base de datos) y esto permite generar clusters ya sea para balanceo de carga como para continuidad de las operaciones. Es importante notar que el concepto de "cluster" se implementa enteramente del lado del cliente dado que cada ZofToken Universal App seleccionará un servidor/puerto al azar dentro de la lista que tenga disponible y en el caso de no tener respuesta, reintentará en otro diferente. Cada servicio debe tener como mínimo un servidor configurado para atender las solicitudes de los usuarios y configurar servidores adicionales es opcional.

Configuración

Para ZaaS, toda la configuración se realiza a través de una interface de usuario simple, por lo cual se puede usar la información en este documento y la ayuda en línea para configurar todos los servicios necesarios.

Para instalaciones privadas de ZofToken Server, existen dos mecanismos para configurar los servicios:

Configuración estática

El archivo config.yaml descrito en la guía de instalación incluye una sección donde se pueden configurar todos los servicios y sus parámetros. Dado que los servicios posiblemente no cambien demasiado, esta es la forma más simple y usual de configurarlos.

Configuración dinámica

Si el archivo config.yaml indica que la configuración debe ser realizada a través de la base de datos, la instalación de ZofToken Server incluye una herramienta ejecutable en la línea de comando para crear, configurar y editar servicios. Si bien editar la base de datos directamente es técnicamente posible (dado que la estructura interna es sencilla), esto no es recomendable en lo más mínimo considerando tanto la posibilidad de introducir errores, como el objetivo de seguridad de prevenir todo acceso a la base de datos de ZofToken Server por fuera de las operaciones normales.

Nombres válidos

Internamente, la solución ZofToken utiliza un hash de la combinación del nombre del usuario y el servicio como la identificación del token, por lo cual no existen restricciones técnicas reales para el nombre de los servicios (incluyendo la utilización de caracteres UTF-8 como es requerido por varios idiomas). No obstante lo anterior, se recomienda que los nombres sean cortos y descriptivos, a efectos de simplificar las interacciones con la API.

Para ZaaS, a efectos de garantizar que cada nombre de servicio sea único, se utiliza como prefijo el nombre de la suscripción. Por lo tanto, para una subscripción con nombre "ejemplo" que tiene servicios con nombres "alfa" y "bravo", los nombres efectivos de los servicios a utilizar contra la API van a ser "ejemplo_alfa" y "ejemplo_bravo".

Authkeys

Descripción

Cada interacción con la API de ZofToken requiere la utilización de un authkey que se valida antes de permitir cualquier tipo de consulta o acción. Un authkey administrativo puede realizar todas las operaciones de la API, mientras que un authkey normal está limitado solamente a consultar por el estado de los tokens.

Para ZaaS, se asignan al azar dos authkeys (uno administrativo y el otro no) cuando se crea originalmente el servicio y los mismos no pueden ser modificados. Para instalaciones privadas de ZofToken Server, se puede configurar un número ilimitado de authkeys con un alto grado de granularidad en su nivel de acceso.

Este diseño permite la implementación de distintos escenarios de seguridad, desde una instalación simple con un authkey interno con acceso completo a todos los tokens, hasta variantes muy complejas con diferentes authkeys y diferentes niveles de acceso para distintos servicios y usuarios en particular. Estos authkeys pueden asignarse a activos específicos para implementar buenas prácticas de seguridad, como por ejemplo, dos servicios que administran dos aplicaciones diferentes pueden usar tokens asignados a distintos servicios y tener authkeys que limitan el acceso solo a su servicio correspondiente. De este modo, aunque una de las aplicaciones se viera comprometida, la seguridad de la otra no se vería afectada.

Parámetros

Cada authkey cuanta con los siguientes parámetros:

Parámetro	Descripción
Authkey	El secreto (cadena de caracteres) que se envía a la API para autorizar una operación.
Admin	Un valor que indica si el autheky tendrá acceso a todas las funciones de la API o solamente acceso de lectura al estado de los tokens.
Máscara de servicio	Esto es una expresión regular que indica a cuáles servicios tendrá acceso el authkey. Notar que este parámetro funciona en conjunto con el siguiente.
Máscara de usuarios	Esto es una expresión regular que indica a cuáles identificadores de usuario tendrá acceso el authkey. Notar que este parámetro funciona en conjunto con el anterior.

Configuración

Como se mencionó en la descripción, los authkeys no pueden ser configurados en ZaaS y los mismos se proveen al azar para cada servicio creado.

Para instalaciones privadas de ZofToken Server existen dos formas de configurar los authkeys:

Configuración estática

El archivo config.yaml descrito en la guía de instalación incluye una sección donde se pueden configurar todos los authkeys y sus parámetros. Dado que los authkeys posiblemente no cambien demasiado (a menos de que se vean comprometidos), esta es la forma más simple y usual de configurarlos.

Configuración dinámica

Si el archivo config.yaml indica que la configuración debe ser realizada a través de la base de datos, la instalación de ZofToken Server incluye una herramienta ejecutable en la línea de comando para crear, configurar y editar authkeys. Si bien editar la base de datos directamente es técnicamente posible (dado que la estructura interna es sencilla), esto no es recomendable en lo más mínimo considerando tanto la posibilidad de introducir errores, como el objetivo de seguridad de prevenir todo acceso a la base de datos de ZofToken Server por fuera de las operaciones normales.

Es importante notar que ambas máscaras son validadas por la API antes de permitir el acceso a una operación sobre un token por lo cual se puede configurar una limitación de acceso a un servicio específico y un acceso ilimitado para los nombres de usuario y esto no permitiría el acceso a tokens fuera del servicio (esta es, de hecho, la forma en la que están configurados los authkeys provistos por ZaaS).

Nombres válidos

Si bien los secretos usados como authkeys pueden ser cualquier cadena de caractéres UTF-8 (especialmente cuando los mismos se configuran a través del archivo config.yaml), se recomienda fuertemente no considerar a los authkeys como contraseñas sino utilizar cadenas seguras.

Una buena aproximación a esta recomendación es generar una cadena binaria al azar y luego convertirla a representación hexadecimal o en BASE64. La herramienta de línea de comando incluída como parte de la instalación de ZofToken Server hace esto último con una cadena binaria elegida al azar de 256 bits.