Actualizar de 2.3 a 3.0

Esta versión de Usuarios, presenta muchos cambios a nivel estructural y visual. El cambio mas grande también es sobre el esquema de despliegue: ahora es por medio de imagenes Docker.

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 2.3.
Se debe tener en cuenta que el proceso de actualización representa migrar las bases OpenLDAP y PostgreSQL
Se deberá realizar un despliegue con imágenes Docker
La plataforma ahora consta de múltiples módulos independientes (api, idm e idp). Ver más detalles de la nueva arquitectura.

La versión 3.0 actualiza 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 9.6 y máxima 12
OpenLDAP requerido en versión 2.4.44 o superior

Procedimiento

Para migrar de una instalación 2.3 a una 3.0 se deben seguir los siguientes pasos:

Resguardo de las bases de datos y assets
Actualizar Bases de datos
Migrar datos
Desplegar contenedores

Preparar accesos y versiones

Definir la versión a utilizar
```
export VERSION=v3.0.2
```
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 migarción, es neceario 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_LARGO_PASS=8
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_23.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 siutoba/docker-openldap-arai con el tag o versión openldap-3.
Para personalizar la imagen docker, puede encontrarlo como hacerlo aquí.

Se presupone que se ha configurado un volúmen con los datos del LDAP persistentes de manera externa, como así mismo para la configuración. En este caso, además de realizar el despliegue de la nueva versión openldap-3 (la que ha personalizado), deberá copiar los archivos .ldif al directorio de configuración que mapeará al iniciar el contenedor.

Suponiendo que nuestro directorio de configuración se encuentra en /etc/ldap/slapd.d/ realizamos entonces:

     sudo cp -f idm/templates/ldap/3.0/ldif/cn\=\{* "/etc/ldap/slapd.d/cn=config/cn=schema"

Luego de lo cual reiniciaremos el contenedor correspondiente indicando los volumenes mapeados correspondientes tanto para configuración como datos.

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.

El primer paso es detener el servicio OpenLDAP
```
sudo systemctl stop slapd
```

Se deben cargar los NUEVOS esquemas requeridos por SIU-Araí: Usuarios (se encuentran dentro del directorio idm/templates/ldap/3.0/ldif del proyecto).

sudo cp idm/templates/ldap/3.0/ldif/cn\=\{* "/etc/ldap/slapd.d/cn=config/cn=schema"

sudo chown openldap:openldap "/etc/ldap/slapd.d/cn=config/cn=schema" -R

sudo systemctl start slapd

Opcional. Es posible verificar si los esquemas fueron cargados realmente

sudo ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn

Si no se dispone, agregar el esquema memberOf para los grupos

sudo ldapmodify -Y EXTERNAL -H ldapi:///  -f idm/templates/ldap/3.0/optional/memberOf.ldif

Opcional. Para verificar que se cuenta con el esquema memberOf

sudo ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" | grep memberOf

Crear nuevos indices

sudo ldapmodify -Y EXTERNAL -H ldapi:/// -f idm/templates/ldap/3.0/optional/index.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_2_3 que será usada como volumen y recibirá los datos exportados
```
 cd /ruta/usuarios/2.3
 bin/toba instancia exportar_local
 mkdir -p /tmp/instalacion_2_3 
 cp -R instalacion /tmp/instalacion_2_3/instalacion
```

Migrar la estructura de la base de datos

  docker run --rm -it  \
  --env-file=migrar.env \
  --volume /tmp/instalacion_2_3:/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

Recordar que estos sólo con estos pasos no está completa la actualización. La siguiente sección es crucial para finalizar la actualización a la versión 3.0.

Migrar datos

Migrar SPs de SAML

En la versión 3.0 se migra la configuración de SPs de SAML dentro de la base Postgres. Es necesario correr el siguiente script para importar los SPs de una instalación anterior. Es necesario contar con el archivo sp.yml que está en la versión 2.3 en el directorio config. Una vez que se obtuvo el archivo ejecutar el siguiente comando:
```
docker run --rm \
  --env-file migrar.env \
  --volume /ruta/arai-usuarios/2.3.0/sp.yml:/tmp/sp.yml \
  hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idm:$VERSION -- \
  idm/bin/instalador migracion:3.0 load-sp /tmp/sp.yml
```
Si hay algún error el comando informará de la situación
Migrar datos de LDAP

En la versión 3.0 se actualiza el esquema LDAP que se utiliza. También se introducen cambios en el formato lógico de los datos (ver aquí para más detalles). 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.

Ahora ejecutamos la migración propiamente de los datos de OpenLDAP.
```
docker run --rm \
  --env-file migrar.env \
  hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idm:$VERSION -- \
  idm/bin/instalador migracion:3.0 ldap
```
Si hay algún error el comando informará de la situación. En el archivo instalador.log quedará registrado el uid del usuario que presentó inconvenientes, junto con el error sucedido.

Luego de la migración, es necesario realizar un reindexado de la base LDAP. Ver aquí documentación al respecto.
Configurar aplicación del IDM

En la versión 3.0 se migra la configuración de SPs de SAML dentro de la base Postgres. Es necesario correr el siguiente script para configurar los conectores SAML a la aplicación que permite el acceso al IDM.
```
docker run --rm \
  --env-file migrar.env \
  hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idm:$VERSION -- \
  idm/bin/instalador proyecto:bootstrap
```
Se le preguntará para actualizar la contraseña del usuario admin. Si no desea cambiarla, solo responda no.

Configurar

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

No hay una equivalencia directa de la 2.3 a la 3.0. Debe configurar cada archivo y cada variable de entorno.

Rutas locales

Para facilitar el ejemplo del despliegue, se crean dos variables de entorno apuntando a rutas que ya deben existir.

export ASSETS=/ruta/assets
export CERTS=/ruta/certs

En ambas rutas, debe tener lo siguiente:

/ruta/assets debe contener los recursos (imágenes de usuarios y aplicaciones) que fueron generados en la instalación 2.3 (revisar /ruta/2.3/config/idp.yml para determinar donde estan alojadas las imágenes).
/ruta/certs debe contener los certifiados del IDP (revisar /ruta/2.3/config/idp.yml para determinar donde estan alojados los certificados).

Certificados OIDC

A partir de esta versión, se incorpora soporte a OIDC. Para que funcione, se requieren certificados que son usados para firmar el token JWT

openssl genrsa -out $CERTS/oidc_module.pem 2048
openssl rsa -in $CERTS/oidc_module.pem -pubout -out $CERTS/oidc_module.crt

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.

3.0.0 a 3.0.1

Cambió la ruta interna de assets en la imagen, ahora al montar las imágenes la variable ASSETS_DIR debe apuntar a /usr/local/app/resources. Si tiene imágenes de usuarios/aplicaciones existentes, debe modificar la estructura para que siga la forma:
```
/usr/local/app/resources/resources/img/[...]
```

Actualizar la versión de la base PostgreSQL

docker run --rm \
  --env-file migrar.env \
  hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idm:$VERSION \
  --db-migrate --negocio

3.0.1 a 3.0.2

Se agregaron dos nuevas ENV para configurar límites de tamaño de imágenes de usuarios y aplicaciones. Agregar las ENV para los módulos idp, idm y api respectivamente.
```
IMAGE_MAX_SIZE_APLICACION=200000
IMAGE_MAX_SIZE_USUARIO=204800
```
Cambió la ENV que permite configurar el redirect de la api legacy a la API nueva. En el módulo idm hacer disponible la variable IDM_API_URL. Solo es necesario si se accede a la API vía URL del IDM, como era en las versiones 2.x.
```
IDM_API_URL=https://url.api/api/v1
```

Actualizar la versión de la base PostgreSQL

docker run --rm \
  --env-file migrar.env \
  hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idm:$VERSION \
  --db-migrate --negocio

3.0.2 a 3.0.3

Actualizar la versión de la base PostgreSQL

docker run --rm \
  --env-file migrar.env \
  hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idm:v3.0.3 \
  --db-migrate --negocio

SIU-Araí: Usuarios

v3.1.11

Protocolos

Bases de datos

Migrar versión

Integrar aplicaciones

IdM

IdP

Varios

Consideraciones iniciales

Procedimiento

Preparar accesos y versiones

Backups de las base de datos

Actualizar OpenLDAP

Si esta usando Docker

Si esta usando instalación manual

Actualizar PostgreSQL

Migrar datos

Configurar

Rutas locales

Certificados OIDC

Desplegar

Volúmenes

Versiones menores

3.0.0 a 3.0.1

3.0.1 a 3.0.2

3.0.2 a 3.0.3