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 despliege: 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:

1. Resguardo de las bases de datos y assets
2. Actualizar Bases de datos
3. Migrar datos
4. Desplegar contenedores

Backups de las base de datos

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

2. 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. Simplemente cambiando la imágen docker y/o realizando un despliegue de la nueva versión openldap-3 (la que ha personalizado), será más que suficiente.

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.

1. El primer paso es detener el servicio OpenLDAP

   sudo systemctl stop slapd
   

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

3. Opcional. Es posible verificar si los esquemas fueron cargados realmente

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

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

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

6. Crear nuevos indices

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

Actualizar PostgreSQL

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

2. Descargar la imagen de la nueva versión de la aplicación

    docker login hub.siu.edu.ar:5005
    docker pull hub.siu.edu.ar:5005/siu-arai/arai-usuarios/idm:v3.0.1
   

3. 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:v3.0.1 -- \
     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

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

2. 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:v3.0.1 -- \
     idm/bin/instalador migracion:3.0 load-sp /tmp/sp.yml
   

   Si hay algún error el comando informará de la situación

3. 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:v3.0.1 -- \
     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.

4. 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:v3.0.1 \
    --db-migrate --negocio
  

3.0.1 a 3.0.2

• 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:v3.0.2 \
    --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