Actualizar de 3.0 a 3.1

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

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.0
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 consta de múltiples módulos independientes (api, idm e idp). Ver más detalles de la nueva arquitectura.

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

Procedimiento

Para migrar de una instalación 3.0 a una 3.1 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.1.0
export VERSION_ANTERIOR=v3.0.5

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
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
IDM_URL=http://url.arai-usuarios
TOBA_USUARIO=nada
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_30.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-4.
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 openldap-4 (o la que ha personalizado), basado en openldap-4.
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.0-to-3.1.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.0-to-3.1.ldif

Nota: Si se personalizó la imagen, se debe cambiar el dn: cn={5}01-arai-usuarios,cn=schema,cn=config al valor que haya generado en la imagen, consultar en LDAP el valor actual y usarlo.

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.1/ldif/3.0-to-3.1.ldif
```

Nota: Si se usó el archivo cn={4}arai-usuarios.ldif, se debe cambiar el dn: cn={5}01-arai-usuarios,cn=schema,cn=config al valor cn={4}arai-usuarios,cn=schema,cn=config. Si genera manualmente los schemas, consultar en LDAP el valor actual y usarlo.

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_0 que será usada como volumen y recibirá los datos exportados

mkdir -p /tmp/instalacion_3_0
docker run --rm -it  \
   --env-file=migrar.env \
   --volume /tmp/instalacion_3_0:/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_0:/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.1.

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.0 a la 3.1 se renombraron algunas variables de entorno.

Variable anterior	Variable nueva	Módulo
IDP_CACHE_BACKEND	CACHE_BACKEND	IDP

Se eliminaron las siguientes variables de entorno:

Variable	Módulo
IDM_USUARIO_TEMPLATE_MAIL	IDM

Así mismo se agregaron las siguientes variables de entorno

Variable	Valores permitidos	Módulo
IDP_MODO_PRODUCCION	true/false	IDP
VINCULACION_MAIL_PPAL	login/independiente	IDP/IDM/API
SEGURIDAD_ACTIVAR_SEGUNDO_FACTOR	true/false	IDP/IDM/API
SECOND_FACTOR_SUBJECT	"Segundo Factor de Autenticación UUNN"	IDP/IDM/API
SECOND_FACTOR_FROM	noreply@institucion.edu.ar	IDP/IDM/API
SECOND_FACTOR_REPLYTO	noreply@institucion.edu.ar	IDP/IDM/API
SECOND_FACTOR_FROMNAME	"Institución"	IDP/IDM/API
SECOND_FACTOR_TOKEN_LIFETIME	3600	IDP/IDM/API
MAIL_VERIFIER_SUBJECT	"Verificación de Email UUNN"	IDP/IDM/API
MAIL_VERIFIER_FROM	noreply@institucion.edu.ar	IDP/IDM/API
MAIL_VERIFIER_REPLYTO	noreply@institucion.edu.ar	IDP/IDM/API
MAIL_VERIFIER_FROMNAME	"Institución"	IDP/IDM/API
MAIL_VERIFIER_TOKEN_LIFETIME	86400	IDP/IDM/API

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.1.0

Protocolos

Bases de datos

Migrar versión

Integrar aplicaciones

IdM

IdP

Varios