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.distcomo 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.
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íneasen el archivoprod/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_assetspara 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
Crear e inicializar la Base de Datos de LDAP
Dirigirse al sitio de documentación de Araí-Usuarios sobre cómo crear la base de LDAP.
https://documentacion.siu.edu.ar/usuarios/docs/cache/instalacion-bases-ldap/
Crear e inicializar la Base de Datos de Postgres
Nota: En este apartado se crea e inicializa la base de datos con la estructura necesaria para Arai-Usuarios. Es requerido que esta base de datos se cree en el cluster usando el encoding UTF-8.
Este paso se lleva a cabo mediante el despliegue de la tarea
docker stack deploy \
--with-registry-auth \
-c prod/arai/util/usuarios_inicializar_base.yml \
usuarios_init_db
Puede verificar el estado de ejecución del mismo de la siguiente manera:
docker service logs usuarios_init_db_idm -f
Una vez finalizado con éxito, puede borrar el stack:
docker stack rm usuarios_init_db
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:
- Ingrese a Araí-Usuarios (user
adminy password seteado anteriormente) - Dirigirse al item Aplicaciones
- Ir a la lupa a la derecha de la fila de la aplicación Araí-Usuarios
- 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íneasen el archivoprod/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 fueraARAI_DOCS_DB_HOST: Host de la base de datosARAI_DOCS_DB_PORT: Puerto de la base de datosARAI_DOCS_DB_DBNAME: Nombre de la base de datosARAI_DOCS_DB_USERNAME: Usuario de la base de datos
Conexión con Nuxeo
ARAI_DOCS_REPO_TIPO: Debe especificarRDIARAI_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 NuxeoARAI_DOCS_REPO_CLAVE: Password asociada al User anteriorARAI_DOCS_REPO_SISTEMA: Identificador del sistema Ej: uunnARAI_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 especificarS3ARAI_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-01olatest.
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
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:
- Ingrese a Araí-Usuarios (user
adminy password seteado anteriormente) - Dirigirse al item Aplicaciones
- Presionar el botón
Agregar + - 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
- 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
- Chequear la opción
- 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)