Actualizar de 3.1 a 3.2

Esta versión de Usuarios, presenta nuevas funciones sobre la versión 3.1.

A continuación se describen los pasos para realizar la actualización de versión.

NO OLVIDE REALIZAR UNA COPIA DE SEGURIDAD DE LA APLICACIÓN Y LAS BASES DE DATOS ANTES DE CONTINUAR

Consideraciones iniciales

Es necesario contar con una instalación de SIU-Araí: Usuarios en la versión 3.1
Se debe tener en cuenta que el proceso de actualización representa migrar la base PostgreSQL (la de LDAP es sólo en caso de requerir soporte a BCRYPT)
Se deberá realizar un despliegue con imágenes Docker
La plataforma consta de múltiples módulos independientes (api, idm e idp). Ver más detalles de la nueva arquitectura.

La versión 3.2 mantiene los requerimientos mínimos respecto a la versión anterior:

Orquestador para contenedores, con soporte a imágenes Docker
PostgreSQL requerido en versión mínima 11 y máxima 14
OpenLDAP requerido en versión 2.4.44 o superior

Procedimiento

Para migrar de una instalación 3.1 a una 3.2 se deben seguir los siguientes pasos:

Preparar accesos y versiones
Resguardo de las bases de datos y assets
Actualizar Bases de datos
Desplegar contenedores

Preparar accesos y versiones

Definir la versión a utilizar

export VERSION=v3.2.0
export VERSION_ANTERIOR=v3.1.12

Autenticarse contra la registry de imágenes Docker del SIU (utiliza credenciales del HUB)
```
docker login hub.siu.edu.ar:5005
```
Donde opere con imágenes Docker del SIU, se requiere este paso

Descargar la imagen de la nueva versión de la aplicación. Asegurarse de tener la versión adecuada

docker pull hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idp:$VERSION
docker pull hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idm:$VERSION
docker pull hub.siu.edu.ar:5005/siu-arai/arai-usuarios/api:$VERSION

Preparar la configuración de conexión a las bases de datos

Para poder realizar la migración, es necesario configurar unas variables de entorno para conectarse a OpenLDAP y PostgreSQL respectivamente. Ajustarlo a los parametros requeridos.

echo \
"#configurar ENV temporal
LDAP_HOST=ip_ldap_host
LDAP_PORT=389
LDAP_TLS=0
LDAP_METHOD=user
LDAP_BINDUSER=cn=admin,dc=siu,dc=cin,dc=edu
LDAP_BINDPASS=adminldappass
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
DB_HOST=ip_pg_host
DB_PORT=5432
DB_DBNAME=dbname
DB_USERNAME=dbuser
DB_PASSWORD=dbpass
DB_SCHEMA=usuarios
IDM_URL=http://url.arai-usuarios
SEGURIDAD_ALGORITMO_SALT=yhWGyAH1KI7jPR75FN8V
SEGURIDAD_ALGORITMO_PASS=crypt
SEGURIDAD_CHECK_PASS=nada
SEGURIDAD_INFO_PASS="La contraseña debe tener al menos 8 caracteres, entre letras mayúsculas, minúsculas, números y símbolos, no pudiendo repetir caracteres adyacentes"
SEGURIDAD_DURACION_DIAS_PASS=0
TOBA_USUARIO=admin
TOBA_PASSWORD=nada" > migrar.env

Backups de las base de datos

Realizar el backup de PostgreSQL de manera preventiva

pg_dump -b -O -x --clean --create --disable-triggers --if-exists -h ${DB_HOST} -p ${DB_PORT} -U ${DB_USERNAME} -d ${DB_DBNAME} -f dump_31.sql

Realizar el backup de LDAP de manera preventiva, ver documentación.

Actualizar OpenLDAP

Si esta usando Docker

Para entender como el proyecto genera la imagen docker ver aquí.
Se han publicado múltiples versiones de la imagen docker. Se requiere la imagen (NUEVA) siudocker/openldap-arai con el tag o versión v1.0.0.
Para personalizar la imagen docker, puede encontrarlo como hacerlo aquí.
Se presupone que se utiliza volúmenes de datos/config para persistir los cambios en la base OpenLDAP

A continuación se describe en forma genérica los pasos para actualizar un ambiente con Docker.

En este caso, se debe realizar el despliegue de la nueva versión v1.0.0 (o la que ha personalizado), basado en v1.0.0.
Desde el repositorio HUB del proyecto, obtener los archivos (se encuentran dentro del directorio idm/templates/ldap/$VERSION/ldif/ del proyecto) y realizar:
```
docker cp idm/templates/ldap/$VERSION/ldif/3.1-to-3.2.ldif ID-CONTENEDOR-LDAP:/tmp
```

Se deben actualizar los esquemas con los cambios requeridos, ejecutando dentro del contenedor de LDAP:

docker exec -it ID-CONTENEDOR-LDAP ldapmodify -c -Y EXTERNAL -Q -H ldapi:/// -f /tmp/3.1-to-3.2.ldif

Si esta usando instalación manual

A continuación se describe la actualización basado en OpenLDAP con Debian 10 Buster. Se asume un DN base dc=unx,dc=edu,dc=ar.

Se deben actualizar los esquemas requeridos por SIU-Araí: Usuarios (se encuentran dentro del directorio idm/templates/ldap/$VERSION/ldif/ del proyecto).
```
 sudo ldapmodify -Y EXTERNAL -H ldapi:///  -f idm/templates/ldap/3.2/ldif/3.1-to-3.2.ldif
```

Actualizar PostgreSQL

Antes de actualizar, hay que exportar la configuración de la aplicación y descargarla, para ello se crea un directorio temporal instalacion_3_1 que será usada como volumen y recibirá los datos exportados

mkdir -p /tmp/instalacion_3_1
docker run --rm -it  \
   --env-file=migrar.env \
   --volume /tmp/instalacion_3_1:/tmp/mapeo_interno \
   hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idm:$VERSION_ANTERIOR -- \
   sed -i 's/\[arai_usuarios\]/\[arai_usuarios\]\nusar_perfiles_propios="1"/g' /usr/local/app/idm/instalacion/i__produccion/instancia.ini \
   && idm/bin/instalador instalacion:exportar -d /tmp/mapeo_interno --no-interaction --no-progress

Con los datos de configuración exportados, se migra la estructura de la base de datos en PostgreSQL

docker run --rm -it  \
   --env-file=migrar.env \
   --volume /tmp/instalacion_3_1:/tmp/mapeo_interno \
   hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idm:$VERSION -- \
   idm/bin/instalador docker:db-actualizar -p /tmp/mapeo_interno --no-interaction --no-progress

Nota: El proceso de actualización aún NO TERMINO. La siguiente sección es crucial para finalizar la actualización a la versión 3.2.

Migrar datos

Nota: El migrador opera sobre la totalidad de los usuarios, pero los cambios los realiza de a un usuario por vez. Esto permite realizar la migración y que finalice a pesar de existir algún inconveniente. Si por algún motivo es necesario volver a ejecutar la migración, simplemente el migrador está preparado para ignorar los usuarios que fueron procesados previamente.

Migrar identificador de aplicación IDM

En la versión 3.2 se actualiza la forma de identificar la aplicación IDM, que permite gestionar los usuarios del IDP. También se introducen cambios varios (ver aquí para más detalles).

Ahora ejecutamos la migración propiamente del identificacdor de la aplicación IDM.
```
docker run --rm \
  --env-file migrar.env \
  hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idm:$VERSION -- \
  idm/bin/instalador migracion idm
```
Migrar claves para ser compatible con la autenticación BIND de LDAP

En la versión 3.2 se mejora la el formato en que se almacenan las claves de los usuarios en LDAP: se pasa de un prefijo identificador {CRYPT} al más estándar {BCRYPT}. Esto permite que, dado un servidor OpenLDAP correctamente configurado, pueda autenticar los usuarios desde otra aplicación externa utilizando el mecanismo "BIND" de LDAP.

Ahora ejecutamos la migración propiamente del prefijo de las claves en cada usuario
```
docker run --rm \
  --env-file migrar.env \
  hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idm:$VERSION -- \
  idm/bin/instalador migracion bcrypt
```
Preparar atributo para arai-pesronas

En la versión 3.2 se vincula cada usuario con una persona en arai-personas. De tal forma que la aplicación IDM permite gestionar el vínculo entre usuario/persona. También se introducen cambios varios (ver aquí para más detalles).

Ahora ejecutamos la migración propiamente del identificacdor de personas en cada usuario
```
docker run --rm \
  --env-file migrar.env \
  hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idm:$VERSION -- \
  idm/bin/instalador migracion personas
```

Actualizar configuración

Toda la configuración del proyecto se realiza por medio de variables de entorno. Cada módulo cuenta con un conjunto de variables que permiten su parametrización:

el idp/templates/.env.dist del módulo idp
el idm/templates/.env.dist del módulo idm
el api/templates/.env.dist del módulo api

Tabla de equivalencias

En el cambio de la versión 3.1 a la 3.2 se eliminaron las siguientes variables de entorno:

Variable	Módulo
SEGURIDAD_LARGO_PASS	IDP/IDM/API

Así mismo se agregaron las siguientes variables de entorno

Variable	Valores permitidos	Módulo
SEGURIDAD_CHECK_PASS	Exp. Regular validación formato contraseña	IDP/IDM/API
IDP_SESSION_DURACION	Duración máxima de la sesión del lado del IDP. Expresado en segundos	IDP/API
CREDENCIALES_API_BASIC_PERSONAS	Conexión como arreglo de ternas `[["usr", "pwd", "url"]]`	IDM

Verificar cambios

En el IDM, se proporciona un comando para verificar la configuración de la aplicación y las bases de datos, para ello se debe conectar a un contenedor existente IDM y ejecutar de la siguiente manera:

docker exec -it ID-CONTENDOR-IDM /entrypoint.sh --verificar

Otra posibilidad es lanzar un contenedor dedicado, sólo para realizar esta verificación vía entrypoint --verificar:

docker run --rm -it  \
   --env-file=migrar.env \
   hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idm:$VERSION --verificar

Este comando 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

Desplegar

Vea la instalación para tener un ejemplo del despliegue en Docker.

Volúmenes

Normalmente lo que hay que tener en cuenta aquí es que cuando ejecute los contenedores, enlace el contenido local (los recursos y certificados) con sus rutas a donde el contenedor espera que estén.

Por ejemplo, los contenedores idp, idm y api usan los recursos (imágenes de usuarios y aplicaciones), por lo que debe si está ejecutando con docker-compose deberá tener algo asi:

volumes:
  - $ASSETS:/usr/local/app/resources

El contenedor idp es el que requiere los certificados como proveedor de identidad. Deberá agregarlos así:

volumes:
  - $ASSETS:/usr/local/app/resources
  - $CERTS/certificado_idp.key:/usr/local/app/idp/config/simplesamlphp/certificado_idp.key 
  - $CERTS/certificado_idp.crt:/usr/local/app/idp/config/simplesamlphp/certificado_idp.crt 
  - $CERTS/oidc_module.pem:/usr/local/app/idp/config/simplesamlphp/oidc_module.pem 
  - $CERTS/oidc_module.crt:/usr/local/app/idp/config/simplesamlphp/oidc_module.crt

El contenedor idm es un cliente SAML del IdP. Requiere el certificado público del IdP. Deberá agregarlos así:

volumes:
  - $ASSETS:/usr/local/app/resources
  - $CERTS/certificado_idp.crt:/usr/local/app/idm/instalacion/idp.crt

Versiones menores

A continuación se describen cambios internos de la estructura de la imagen y/o en variables de entornos usadas para su configuración.

SIU-Araí: Usuarios

v3.2.0

Protocolos

Bases de datos

Migrar versión

Integrar aplicaciones

IdM

IdP

Personas

Varios