Desplegar Araí

Desde la raíz del repositorio primeramente procederemos a adaptar los archivos de configuración de Araí a las necesidades de su instalación y luego desplegar los distintos stacks.

Configuración General

Cambiar dominio

En los archivos de configuración se asume el dominio uunn.local, para cambiarlo por el dominio definitivo puede utilizar el siguiente comando (reemplace universidad.edu.ar por el dominio real que utilizará durante el despliegue)

sed -i 's/uunn.local/universidad.edu.ar/g' \
    prod/arai/usuarios.api.env \
    prod/arai/usuarios.idp.env \
    prod/arai/usuarios.env \
    prod/arai/usuarios.yml \
    prod/arai/personas.api.env \
    prod/arai/personas.env \
    prod/arai/personas.yml \
    prod/arai/docs.yml \
    prod/arai/docs.env \
    prod/arai/notificaciones.yml \
    prod/arai/notificaciones.env \
    prod/arai/huarpe.env \
    prod/arai/huarpe.yml

Huarpe es un caso especial pues existe una expresión regular con la URL que deberemos ajustar:

sed -i 's/uunn\\.local/universidad\\.edu\\.ar/g' prod/arai/huarpe.env

Secretos en Docker

Los secretos son blobs de información que deben almacenarse de forma segura y no pueden ser versionados. Ejemplos de esto son: passwords, claves de SSH, certificados SSL, etc. Más información aquí.

Los servicios que conforman esta documentación requieren que ciertos secretos estén definidos antes de comenzar el despliegue.

Esta es la lista de secretos requeridos por Araí durante el despliegue:

• usuarios_db_pass: Password de la conexión con la base de datos.
• usuarios_ldap_admin_pass: Password de bind de admin de ldap.
• usuarios_ldap_config_pass: Password de bind del config de ldap.
• usuarios_pass_salt: Salt de los passwords generados por Araí-Usuarios.
• usuarios_api_users: Json que define pares de usuario/password para la autenticación de la API de usuarios.
• usuarios_idp_simplesaml_admin: Password del panel de control de Administrador provisto con SimpleSAMLPhp.
• personas_db_pass: Password de la conexión con la base de datos de personas.
• personas_api_users: Json que define pares de usuario/password para la autenticación de la API de Personas.
• docs_api_pass: Password de la API de Documentos.
• docs_db_pass: Password de la conexión con Postgres.
• docs_repo_pass: Password de la conexión con Nuxeo.
• docs_conexion_usuarios: Credenciales y endpoint de la conexión con Usuarios.
• docs_conexion_sudocu: Credenciales y endpoint de la conexión con SUDOCU.
• huarpe_secret: Token de 31 caracteres.
• huarpe_conexion_usuarios: Credenciales de la conexión por API con Usuarios.
• huarpe_conexion_docs: Credenciales de la conexión por API con Documentos.
• notificaciones_db_pass: Password de la conexión con la base de datos de notificaciones.
• notificaciones_api_users: Json que define pares de usuario/password para la autenticación de la API de Notificaciones.
• notificaciones_dsn_seguro: String de conexión a un provider de envió de mails

Creación de secretos

La distribucion provee el script de bash prod/arai/secrets.sh.dist para ejemplificar como inicializar todos los valores requeridos. Si desea mantener un archivo propio con las claves de su ambiente ejecute:

cp prod/arai/secrets.sh.dist prod/arai/secrets.sh

y modifique el script prod/arai/secrets.sh con los datos correspondientes a su entorno. Luego ejecutelo para cargar los secretos dentro de Docker.

./prod/arai/secrets.sh

En el caso que se mantenga un repositorio de configuraciones propio, se recomienda ignorar este archivo y evitar subirlo. Tambien es posible no escribir las claves en archivos y configurar los secretos a mano tomando el script prod/arai/secrets.sh.dist como referencia.

Configurar y desplegar Araí-Personas

La especificación del stack de este módulo se encuentra en prod/arai/personas.yml. Existen tambien otros archivos de configuración asociados: prod/arai/personas.api.env y prod/arai/personas.env

Crear la Base de Datos

Crear la base de datos como recurso externo, recordar que la configuración para la misma se debe incluir en el secreto previo y también en archivo prod/arai/personas.env

DB_HOST=db-personas
DB_PORT=5432
DB_DBNAME=arai_personas
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_SCHEMA=personas
DB_ENCODING=UTF8

Deberá crear la base de datos con los datos definidos previamente. Si requiere mayor información, en el sitio de documentación de Araí-Personas hay mayor detalle de los parámetros involucrados y la base de Postgres.

https://documentacion.siu.edu.ar/personas

Inicializar la Base de Datos

Nota: Asume que la base de datos especificada en la sección anterior ya está creada.

Este paso se lleva a cabo mediante el despliegue de la tarea

docker stack deploy \
    --with-registry-auth \
    -c prod/arai/util/personas_migrar_base.yml \
    personas_db

Puede verificar el estado de ejecución del mismo de la siguiente manera:

docker service logs personas_db_migrar -f

Una vez finalizado con éxito, puede borrar el stack:

docker stack rm personas_db

Desplegar el stack

Finalmente, puede desplegar el stack:

docker stack deploy --with-registry-auth -c prod/arai/personas.yml personas

Habilitar acceso API de personas

Para acceder a la API de personas desde fuera del cluster se debe descomentar las siguientes líneas en el archivo prod/arai/personas.yml. Tener en cuenta las recomendaciones de seguridad al respecto.

Esto se realiza sólo si se desea agregar un nuevo usuario y contraseña para lograr que un nuevo cliente se autentifique contra la API de Araí-Personas. Para esto se debe modificar prod/arai/secrets.sh y agregar los datos de acceso en el secret personas_api_users.

Primero se debe eliminar el servicio personas_api y el secret personas_api_users de la siguiente forma:

docker service rm personas_api

docker secret rm personas_api_users

Luego, por ejemplo, para agregar el usuario mi_sistema con contraseña mi_sistema a los clientes permitidos de acceder a la api:

printf '[["documentos","documentos123"],["huarpe","huarpe123"],["mi_sistema","mi_sistema"]]' | docker secret create personas_api_users -

Luego se debe volver a crear el secret ejecutando ./prod/arai/secrets.sh y finalmente se debe realizar nuevamente el deploy de personas como se indica aquí.

Opcional. Es posible verificar el funcionamiento de la API consultando un recurso que devuelve información de versión:

curl https://universidad.edu.ar/personas/v1/info -u user:pass

Recuerde reemplazar "user:pass" por las credenciales válidas, junto con la URL válida para conectarse a la API. El resultado de la consulta debe ser un JSON conteniendo "nombre", "version", etc.

Configurar y desplegar Araí-Usuarios

La especificación del stack de este módulo se encuentra en prod/arai/usuarios.yml. Existen tambien otros archivos de configuración asociados: prod/arai/usuarios.api.env, prod/arai/usuarios.env y prod/arai/usuarios.idp.env

Nota sobre la persistencia de datos

Este stack utiliza un volumen llamado usuarios_assets para guardar la imagen de perfil de los usuarios. Es importante que el almacenamiento subyacente sea compartido por todos los nodos del cluster donde este stack se este ejecutando para que mantengan entre ellos un estado consistente de la base de imagenes. Para lograr esto se requiere contar con una tecnología de almacenamiento distribuido (NFS, GlusterFS, etc) montada en cada nodo. Como alternativa al almacenamiento distribuido tambien es posible simplificar el despliegue limitando la ejecución de este stack a un único nodo del cluster conectado al almacenamiento centralizado.

Acceso a Postgres

Los parámetros de conexión los puede encontrar en el archivo prod/arai/usuarios.env, son los siguientes:

DB_HOST=db-siu
DB_PORT=5432
DB_DBNAME=usuarios
DB_USERNAME=postgres
DB_SCHEMA=usuarios

Acceso a LDAP

Los parámetros de conexión los puede encontrar en el archivo prod/arai/usuarios.env, son los siguientes:

LDAP_HOST=ldap
LDAP_PORT=389
LDAP_TLS=0
LDAP_METHOD=user
LDAP_BINDUSER=cn=admin,dc=siu,dc=cin,dc=edu
LDAP_BINDPASS_FILE=/run/secrets/usuarios_ldap_admin_pass
LDAP_SEARCHBASE=dc=siu,dc=cin,dc=edu
LDAP_USERS_OU=usuarios
LDAP_USERS_ATTR=ou
LDAP_ACCOUNTS_OU=usuariosCuentas
LDAP_ACCOUNTS_ATTR=ou
LDAP_GROUPS_OU=groups
LDAP_GROUPS_ATTR=ou
LDAP_NODES=

Creación de Base de Datos

En el sitio de documentación de Araí-Usuarios hay documentación extensa de cómo crear la base de LDAP y Postgres. Para evitar problemas en el uso de Araí-Usuarios, no modifique el encoding por defecto del motor de postgres (UTF-8), ni especifique uno alternativo al momento de crear la base de datos (la env-var DB_ENCODING no debe ser modificado).

https://documentacion.siu.edu.ar/usuarios/docs/cache/instalacion-bases-ldap/ https://documentacion.siu.edu.ar/usuarios/docs/cache/instalacion-bases-postgres/

Generar certificados

Araí-Usuario requiere dos pares de claves para funcionar, una para firmar los tokens SAML y otra para firmar los tokens JWT de OIDC.

Para generar los certificados utilizados para firmar los tokens SAML ejecutar:

mkdir prod/arai/certs
openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out prod/arai/certs/certificado_idp.crt -keyout prod/arai/certs/certificado_idp.key

Para generar los certificados utilizados en OIDC para firmar tokens JWT ejecutar:

openssl genrsa -out prod/arai/certs/oidc_module.pem 2048
openssl rsa -in prod/arai/certs/oidc_module.pem -pubout -out prod/arai/certs/oidc_module.crt

Para finalizar, registre los certificados y claves generadas en Docker.

docker config create usuarios_idp_saml_cert ./prod/arai/certs/certificado_idp.crt
docker secret create usuarios_idp_saml_key ./prod/arai/certs/certificado_idp.key
docker secret create usuarios_idp_oidc_key ./prod/arai/certs/oidc_module.pem
docker config create usuarios_idp_oidc_cert ./prod/arai/certs/oidc_module.crt

Bootstraping del proyecto

La primera vez que se instala este proyecto es necesario realizar dos tareas administrativas para que todo funcione correctamente. Las tareas a realizar son:

• Registrar la UI de Araí-Usuarios como SP
• Crear y setear un password para el usuario admin

Para realizar este paso, es necesario que las bases de datos estén inicializadas

Estas dos tareas se realizan ejecutando el siguiente comando:

ADMIN_PASS=toba1234 docker stack deploy \
    --with-registry-auth \
    -c prod/arai/util/usuarios_crear_admin.yml \
    boot

Setee la variable ADMIN_PASS al password que desee.

Puede verificar el estado de ejecución del mismo de la siguiente manera:

docker service logs boot_idm -f

Una vez finalizado, puede borrar el stack:

docker stack rm boot

Inicializar integración de Arai-Personas

Para realizar este paso, es necesario que el servicio Arai-Personas este inicializada y desplegado.

Este comando genera por cada usuario, una persona y lo deja vinculado.

docker stack deploy \
   --with-registry-auth \
   -c prod/arai/util/usuarios_inicializar_personas.yml \
   usuarios_personas_init

Puede verificar el estado de ejecución del mismo de la siguiente manera:

docker service logs usuarios_personas_init_idm -f

El resultado de la migración debería ser una salida similar a esta:

Resumen de la migración LDAP
--------------------------------------------------------------------
usuarios procesados: 56 en 2 lotes 
usuarios migrados: 56 
usuarios con error en la migración: 0
usuarios reiniciados (poseen idPersona): 0
usuarios ignorados (no poseen idPersona): 56

Una vez finalizado, puede borrar el stack:

docker stack rm usuarios_personas_init

Nota: la inicialización es un proceso idempotente, es decir se puede ejecutar sucesivas veces y se encarga de procesar solo los usuarios pendientes (tanto sea usuarios nuevos, como los no procesados por algún error previo).

Para mayores detalles sobre la vinculación con Arai-Personas, ver la documentación de inicialización y gestión disponibles.

Desplegar el stack

Finalmente, puede desplegar el stack:

docker stack deploy --with-registry-auth -c prod/arai/usuarios.yml usuarios

Una vez realizados estos pasos, debería poder acceder en https://uunn.local/usuarios (o el dominio que haya definido)

Verificar los servicios

Con el despliegue realizado, es posible verificar la configuración hecha ejecutando:

docker stack deploy --with-registry-auth --compose-file prod/arai/util/usuarios_verificar.yml usuarios_verificar
docker service logs usuarios_verificar_idm -f
docker stack rm usuarios_verificar

La verificación mostrará en la salida de su ejecución el chequeo de:

• la versión de la base de datos PostgreSQL
• los esquemas de la base OpenLDAP
• la versión de la imagen Docker respecto a las bases
• conexiones a servicios varios

El servicio anterior requiere que el nodo que ejecuta los comandos Docker sea el mismo donde se despliega el stack usuarios, agregarle por tanto el labels.cmd=usuarios al nodo para que el servicio usuarios_verificar se inicie:

NODE_NAME=$(docker info --format '{{ .Name }}')
docker node update --label-add cmd=usuarios $NODE_NAME

Configurar logo

Este paso es opcional, pero deseable.

Para configurar el logo debe seguir los siguientes pasos:

1. Ingrese a Araí-Usuarios (user admin y password seteado anteriormente)
2. Dirigirse al item Aplicaciones
3. Ir a la lupa a la derecha de la fila de la aplicación Araí-Usuarios
4. Cargar el ícono. https://hub.siu.edu.ar/siu/expedientes/-/blob/master/var/logos/usuarios.png

Habilitar acceso API de usuarios

Para acceder a la API de usuarios desde fuera del cluster se debe descomentar las siguientes líneas en el archivo prod/arai/usuarios.yml. Tener en cuenta las recomendaciones de seguridad al respecto.

Esto se realiza sólo si se desea agregar un nuevo usuario y contraseña para lograr que un nuevo cliente se autentifique contra la API de Araí-Usuarios. Para esto se debe modificar prod/arai/secrets.sh y agregar los datos de acceso en el secret usuarios_api_users.

Primero se debe eliminar el servicio y el secret de usuarios_api de la siguiente forma:

docker service rm usuarios_api

docker secret rm usuarios_api_users

Luego, por ejemplo, para agregar el usuario mi_sistema con contraseña mi_sistema a los clientes permitidos de acceder a la api:

printf '[["documentos","documentos123"],["huarpe","huarpe123"],["mi_sistema","mi_sistema"]]' | docker secret create usuarios_api_users -

Luego se debe volver a crear el secret ejecutando ./prod/arai/secrets.sh y finalmente se debe realizar nuevamente el deploy de usuarios como se indica aquí.

Opcional. Es posible verificar el funcionamiento de la API consultando un recurso que devuelve información de versión:

curl https://universidad.edu.ar/api-usuarios/v2/info -u user:pass

Recuerde reemplazar "user:pass" por las credenciales válidas, junto con la URL válida para conectarse a la API. El resultado de la consulta debe ser un JSON conteniendo "nombre", "version", etc.

Configurar y desplegar Araí-Documentos

La especificación del stack de este módulo se encuentra en prod/arai/docs.yml. Existen tambien otros archivo de configuración asociado: prod/arai/docs.env

Conexión con Postgres

• ARAI_DOCS_URL: Es la URL base de la API accesible desde fuera
• ARAI_DOCS_DB_HOST: Host de la base de datos
• ARAI_DOCS_DB_PORT: Puerto de la base de datos
• ARAI_DOCS_DB_DBNAME: Nombre de la base de datos
• ARAI_DOCS_DB_USERNAME: Usuario de la base de datos

Conexión con Nuxeo

• ARAI_DOCS_REPO_TIPO: Debe especificar RDI
• ARAI_DOCS_REPO_HOST: Es la url de nuxeo, debe apuntar a la API CMIS < url-host-nuxeo >/nuxeo/atom/cmis/
• ARAI_DOCS_REPO_USUARIO: API User de Nuxeo
• ARAI_DOCS_REPO_CLAVE: Password asociada al User anterior
• ARAI_DOCS_REPO_SISTEMA: Identificador del sistema Ej: uunn
• ARAI_DOCS_REPO_INSTALACION: Identificador de la instalación Ej: arai_docs_uun

(Opcional) Conexión con S3

En caso de que opte por utilizar la solución de object storage de S3, debe configurar y agregar de ser necesario las siguientes variables:

• ARAI_DOCS_REPO_TIPO: Debe especificar S3
• ARAI_DOCS_S3_ENDPOINT: Configuracion del endpoint donde se encuentran los buckets.
• ARAI_DOCS_S3_KEY: Key para autenticar contra el bucket.
• ARAI_DOCS_S3_SECRET: Secret para autenticar contra el bucket.
• ARAI_DOCS_S3_REGION: Region donde se encuentra el bucket. Ej: us-west-2.
• ARAI_DOCS_S3_BUCKET: Nombre del bucket. Ejemplo: bucket_test.
• ARAI_DOCS_S3_VERSION: Version del servicio web utilizado. Ejemplo: 2006-03-01 o latest.

Creación de Base de Datos

Se incluye un comando que crea la estructura de la base de datos de Araí-Documentos. Para utilizarlo ejecutar el siguiente comando:

docker stack deploy \
    --with-registry-auth \
    -c prod/arai/util/docs_crear_base.yml \
    crear_db_docs

Se asume que la base de datos especificada en la variable ARAI_DOCS_DB_DBNAME de la sección "Conexión con Postgres" ya está creada.

Stamper

Crear Firma de Sistema

Este servicio se consume y configura desde Araí-Documentos. Provee una forma de agregar una hoja en cada documento que ingresa al sistema de forma tal que se genere espacio para agregar el detalle de las autorizaciones. Cada vez que se genera una autorización se agrega la estampa.

Es un servicio desarrollado en Java y se invoca desde Araí-Documentos a través de una api HTTP. Es distribuido solamente a través de una imagen Docker.

Es muy importante generar un nuevo secret que contenga el keystore. La clave guardada en este secreto será la Firma de Sistema que será utilizada en la firma de todos los PDFs. Puede aprender como generar una firma en esta guia. Luego deberá regresar para finalizar la configuración del Stamper.

ACLARACION: Este ejemplo usa una keystore demo que no es segura. En caso de ser una instalacion para producción, debe reemplazarlo por una keystore generada de forma segura.

Una vez que se tenga posesión de la keystore a utilizar ejecute el siguiente comando para generar el nuevo secreto.

docker secret create docs_stamper_keystore ./var/stamper/certs/keystore_stamper.p12

Nota: el nombre del archivo debe ser "keystore_stamper.p12". Si se modifica, deberá cambiar la respectiva variable

A partir de la versión 1.6 de EEI, el servicio Stamper se distribuye activo de forma predeterminada.

Verificar configuración

Una vez generado el certificado para la Firma de Sistema y keystore, verificar que coinciden los datos incorporados en el archivo prod/arai/docs.stamper.env con aquellos utilizados durante la creación de la Firma: en particular el valor de "--name" y "clave" utilizados en el paso "Exportar PKCS#12 bundle" de la guia.

En particular validar en dicho archivo de ENV las entradas presentes:

ARAI_DOCS_STAMPER_KEYSTORE_PASS=la-clave-del-keystore
ARAI_DOCS_STAMPER_KEYSTORE_ALIAS="KeyStamper"

Desplegar el stack

docker stack deploy --with-registry-auth -c prod/arai/docs.yml docs

Habilitar acceso externo de API Backend de documentos

Al habilitar el acceso externo (desde afuera del cluster) al API Backend hay que tener en cuenta las recomendaciones de seguridad para evitar que otros servicios externos puedan acceder a dicho servicio.

Para habilitar el acceso externo al Backend de la API de Araí-Documentos se debe modificar el archivo prod/arai/docs.yml.

En este archivo se debe agregar las líneas:

- "traefik.http.routers.docs-backend.rule=Host(`uunn.local`) && PathPrefix(`/docs/rest/backend`)"
- "traefik.http.routers.docs-backend.tls=true"

Adicionalmente, como este es un endpoint que no debería quedar publicado se tendrían que adicionar las siguientes lineas (con su correspondiente ajuste):

- "traefik.http.middlewares.docs-ipwhitelist.ipwhitelist.sourcerange=127.0.0.1/32,172.77.100.0/24"
- "traefik.http.routers.docs-backend.middlewares=security-headers@file,docs-ipwhitelist"

Luego se debe realizar el deploy de documentos para actualizar los servicios como se indica aquí

Configurar y desplegar Arai-Notificaciones (Opcional)

La especificación del stack de este módulo se encuentra en prod/arai/notificaciones.yml. Existe tambien otro archivo de configuración asociado: prod/arai/notificaciones.env

Creación de Base de Datos

Advertencia

Es requisito que el motor de base de datos donde se desplegara la base de notificaciones posea implementada la función gen_random_uuid() (disponible a partir de la versión 13)

Crear la base de datos como recurso externo, recordar que la configuración para la misma se debe incluir en los secretos creados previamente y también en archivo prod/arai/notificaciones.env

DB_HOST=db-notificaciones
DB_PORT=5432
DB_DBNAME=arai_notificaciones
DB_USERNAME=postgres
DB_PASSWORD_FILE=/run/secrets/notificaciones_db_pass
DB_SCHEMA=notificaciones

Inicializar la base de datos

Este paso se lleva a cabo mediante el despliegue de la siguiente tarea que crea la estructura de la base de datos de Araí-Notificaciones.

docker stack deploy \
    --with-registry-auth \
    -c prod/arai/util/notificaciones_migrar_base.yml \
    notificaciones_db

Puede verificar el estado de ejecución del mismo de la siguiente manera:

docker service logs notificaciones_db_migrar -f

Una vez finalizado con éxito, puede borrar el stack:

docker stack rm notificaciones_db

Configuración de Envío de Emails

Para el envío de emails se debe definir el DSN de un servicio de envío mediante el secret notificaciones_dsn_seguro. La creación de este secret se encuentra en el archivo de secretos distibuido prod/arai/secrets.sh.dist.

Desplegar el stack

Luego de realizar los pasos anteriores se puede desplegar el stack::

docker stack deploy --with-registry-auth -c prod/arai/notificaciones.yml notificaciones

Configurar y desplegar SIU-Huarpe

La especificación del stack de este módulo se encuentra en prod/arai/huarpe.yml. Existen tambien otros archivos de configuración asociados: prod/arai/huarpe.env y prod/arai/huarpe_framework.yml

Conexiones con APIs Rest

Como se dijo antes, este sistema sólo consume información a través de endpoints Rest. Estas conexiones están explicitadas en el archivo prod/arai/huarpe.env y no deberían cambiar, salvo que se cambie la ruta interna en el clúster de Sudocu, Usuarios o Documentos.

Registrar Huarpe como Service Provider

Dentro de la solución, Araí-Usuarios es el proveedor de identidad de SIU-Huarpe. Por este motivo es necesario registrar a este último como Service Provider (SP) de SAML.

Via linea de comandos

Debe desplegar un contenedor de tareas administrativas y seguir estos pasos.

Via manejador de usuarios

Debe acceder a manejador de usuarios y seguir estos pasos:

1. Ingrese a Araí-Usuarios (user admin y password seteado anteriormente)
2. Dirigirse al item Aplicaciones
3. Presionar el botón Agregar +
4. Completar de la siguiente manera el tab Datos Generales
   • Url: https://uunn.local
   • Nombre: Huarpe
   • Chequear la opción Acceso Irrestricto
   • Cómo ícono colocar esta imagen: https://hub.siu.edu.ar/siu/expedientes/-/blob/master/var/logos/huarpe.png
5. Completar de la siguiente manera el tab SAML
   • Chequear la opción Activo
   • Entity Id: https://uunn.local/saml/metadata
   • Assertion Consumer Serv.: https://uunn.local/saml/acs
   • Single Logout Serv.: https://uunn.local/saml/logout
6. Presionar el botón Guardar

Desplegar el stack

docker stack deploy --with-registry-auth -c prod/arai/huarpe.yml huarpe

Una vez realizados estos pasos, debería poder acceder a Huarpe en https://uunn.local/ (o el dominio que haya definido)