SIU-Guarani/version3.18.0/interfaces/gestion-arai

SIU-Araí

SIU-Araí es la plataforma integradora de servicios del SIU. Cada uno de los sistemas SIU son módulos dentro de la plataforma que interactúan entre sí, consumiendo y ofreciendo servicios. Esté apartado está enfocado en la integración de SIU-Guaraní en la plataforma SIU-Araí, se asume que los sistemas ya están instalados y funcionando. Para ver documentación específica de Araí hágalo desde aquí.

Vinculando SIU-Guaraní Gestión con SIU-Araí

Antes de registrar la aplicación en Araí debemos verificar que en el archivo <path_gestion>/instalacion/i__desarrollo/instancia.ini dentro de la sección [guarani] contenga el entrada full_url

[guarani]
path     = "<path_gestion>"     # Ej: "/usr/local/proyecto"
url      = "<url_gestion>"      # Ej: "/gestion/0318"
url_pers = "<url_gestion_pers>" # Ej: "/gestion/0318_pers/"
full_url = "<full_url_gestion>" # Ej: "http://localhost/gestion/0318"

Nota: Si tiene una versión de araí usuario 3.x debe configurar y registrar el proyecto como indica la documentación de Araí-Usuarios

Generar las claves para encriptar

Llegado a este punto, durante la instalación del proyecto y por única vez, será necesario como pre-requisito generar y configurar la clave para encriptar la sincronización de api REST con Araí . Para hacerlo, se debe correr el siguiente comando parados en <path_gestion>:

bin/arai-cli arai:generar-key --backend sodium_compat --destino=/ruta/donde/guardar/arai-sync.key

También será necesario configurar en el archivo <path_gestion>/instalacion/instalacion.ini del proyecto, la entrada arai_sync_key_file con la ruta donde se aloja la clave previamente creada.

...
arai_sync_key_file=/ruta/donde/guardar/arai-sync.key

Variables de Entorno

Araí-Cli utiliza variables de entorno para acceder a archivos y otras tareas, hay que asegurarse de que las siguientes variables estén instanciadas correctamente de acuerdo al entorno de instalación de la aplicación (archivo <path_gestion>/entorno_toba.env).

export TOBA_INSTANCIA=desarrollo
export TOBA_PROYECTO=guarani
export TOBA_PROYECTO_DIR=<path_gestion>
export TOBA_INSTALACION_DIR=<path_gestion>/instalacion
export ARAI_REGISTRY_USER=<arai_registry_user>
export ARAI_REGISTRY_PASS=<arai_registry_pass>

Nota: <arai_registry_user> y <arai_registry_pass> se obtienen de la instalación de Registry de SIU-Araí.

Registrar el proyecto

Si todo está en orden, por única vez, el proceso de registración a la plataforma SIU-Araí de la aplicación se concreta haciendo uso de la librería previamente con el siguiente comando (ejecutarlo parados en <path_gestion>):

source ./entorno_toba.env # Carga la variables de entorno
bin/arai-cli registry:add --backend sodium_compat --maintainer <nombre_encargado_admin> --maintainer-email <email_encargado_admin> <url_arai_registry>

Nota: Se debe proporcionar la url válida del servicio SIU-Araí Registry, junto con los datos del administrador.

Sincronizar el proyecto

Siempre que registremos alguna aplicación a Araí-Registry, es necesario realizar un registr:sync para que nuestra aplicación localmente tenga los datos más actualizados acerca de los diferentes servicios, aplicaciones y/o apis que querramos consumir. Además, si nuestra aplicación localmente agregó una nueva característica (ej. una http://toba.siu.edu.ar/trac/toba/wiki/Referencia/Rest api REST]), este comando informará a Araí-Registry las novedades (ejecutarlo parados en <path_gestion>).

bin/arai-cli registry:sync

Este paso es necesario realizarlo también en Araí-Usuarios, para que este sistema se entere de la presencia de una nueva aplicación.

A partir de este momento, al ingresar al proyecto, este debiera de redirigirnos a la página de login centralizado de la plataforma SIU-Araí. Una vez el usuario ha ingresado, nos redirige nuevamente hacia la aplicación. La misma debiera de contar además con el menú de aplicaciones integrado, con las aplicaciones SIU o de terceros que tengamos registrados.

Conectando con SIU-Araí Usuarios

Como el login a partir de este momento solo se hará através de SIU-Araí y no desde la base de negocio deberíamos indicarle a Guaraní donde está la API de SIU-Araí Usuarios para que pueda traernos los usuarios que queremos vincular a la persona existente.

Se debería agregar el siguiente archivo: <path_gestion>/instalacion/i__desarrollo/p__guarani/rest/arai_usuarios/cliente.ini

[conexion]
to = <url_arai_usuarios>/rest/
auth_tipo = basic
auth_usuario = <arai_usuarios_user>
auth_password = <arai_usuarios_pass>

Nota:

<arai_usuarios_user> y <arai_usuarios_pass> son las credenciales de la API REST de SIU-Araí Usuarios.

A partir de ahora cuando queramos asignar un usuario a una persona, aparecerá un combo editable donde podremos buscar los usuarios existentes en SIU-Araí.

Entonces de está forma necesitamos editar la persona en SIU-Guaraní Gestión (operación Administrar Personas solapa Acceso al sistema), y vincularla con el usuario de SIU-Araí.

Conectando con SIU-Araí Documentos

Para la creación de documentos en SIU-Araí necesitamos realizar la siguiente configuración en SIU-Guaraní Gestión.

Se debería agregar el siguiente archivo: <path_gestion>/instalacion/arai_documentos.ini

host_arai = "<url_arai_documentos>"
usr_arai = "<arai_documentos_user>"
pass_arai = "<arai_documentos_pass>"

Nota:

<url_arai_documentos> es la URL base de SIU-Araí Documentos (sin el sufijo "/rest/backend/").

<arai_documentos_user> y <arai_documentos_pass> son las credenciales de la API REST de SIU-Araí Documentos.

Vinculando SIU-Guaraní Autogestión con SIU-Araí

Conectando con SIU-Araí Usuarios

Se debería modificar el siguiente archivo <path_3w>/instalacion/servicios_web_config.php, agregando lo siguiente dentro del array de consumidos:

'consumidos' => [

............

    'arai_usuarios' => [
        'tipo' => 'rest',
            'parametros' => [
                'base_uri' => '<url_arai_usuarios>/rest/',
                'auth' => ['<arai_usuarios_user>', '<arai_usuarios_pass>', 'basic'],
                'verify' => false
            ]
    ],

............

]

Nota:

<arai_usuarios_user> y <arai_usuarios_pass> son las credenciales de la API REST de SIU-Araí Usuarios.

Conectando con SIU-Araí Documentos

Para la creación de documentos en SIU-Araí necesitamos realizar la siguiente configuración en SIU-Guaraní Autogestión.

Se debería agregar el siguiente archivo: <path_3w>/instalacion/arai_documentos.ini

host_arai = "<url_arai_documentos>"
usr_arai = "<arai_documentos_user>"
pass_arai = "<arai_documentos_pass>"

Nota:

<url_arai_documentos> es la URL base de SIU-Araí Documentos (sin el sufijo "/rest/backend/").

<arai_documentos_user> y <arai_documentos_pass> son las credenciales de la API REST de SIU-Araí Documentos.

Configurando autenticación vía SAML entre SIU-Guaraní Autogestión y SIU-Araí

Ir a la aplicación de Araí Usuarios y en la operación Aplicaciones dar de alta una nueva aplicación para 3w, para luego poder vincular los usuarios de tipos de docente con el autogestión y huarpe. Se debe ingresar la url de 3w y también el appUniqueId que luego se utilizará para los siguientes pasos. Un ejemplo podría ser como el siguiente:

En la instalación de Araí Usuarios, que puede ser un docker o una instalación local, pararse sobre la carpeta del mismo y correr el siguiente comando:

bin/toba proyecto configurar_sp -p arai_usuarios --endpoint <url_3w>/acceso --acs <url_3w>/acceso?auth=saml --login <url_3w>/acceso?auth=saml --logout <url_3w>/acceso/logout --app <appUniqueId3w>

Donde:

<url_3w> es la url de autogestión a la cual queremos darle un acceso por el proveedor de indentidad SIU-Araí.

<url_arai_idp> es la url del IDP de SIU-Araí.

<appUniqueId3w> es el identificador que hemos utilizado en el paso anterior cuando dimos de alta la aplicación en el SIU-Araí Usuarios.

<fingerprint> se genera ejecutando: openssl x509 -noout -fingerprint -in "/path/to/idp.crt".

Ir a <path_3w>/instalacion/saml y correr el siguiente comando:

cp settings_example.php settings.php

Abrir el archivo settings.php y dejar el siguiente contenido.

<?php
//settings y advanced_settings de la libreria de saml.
$url_autogestion = '<url_3w>';
$url_idp = '<url_arai_idp>';
return $settings = array (
    // If 'strict' is True, then the PHP Toolkit will reject unsigned
    // or unencrypted messages if it expects them signed or encrypted
    // Also will reject the messages if not strictly follow the SAML
    // standard: Destination, NameId, Conditions ... are validated too.
    'strict' => false,

    // Enable debug mode (to print errors)
    'debug' => true,

    // Service Provider Data that we are deploying
    'sp' => array (
        // Identifier of the SP entity  (must be a URI)
        'entityId' => $url_autogestion.'/acceso',
        // Specifies info about where and how the <AuthnResponse> message MUST be
        // returned to the requester, in this case our SP.
        'assertionConsumerService' => array (
            // URL Location where the <Response> from the IdP will be returned
            'url' => $url_autogestion.'/acceso?auth=saml',
            // SAML protocol binding to be used when returning the <Response>
            // message.  Onelogin Toolkit supports for this endpoint the
            // HTTP-Redirect binding only
            'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
        ),
        // Specifies info about where and how the <Logout Response> message MUST be
        // returned to the requester, in this case our SP.
        'singleLogoutService' => array (
            // URL Location where the <Response> from the IdP will be returned
            'url' => $url_autogestion.'/acceso/logout',
            // SAML protocol binding to be used when returning the <Response>
            // message.  Onelogin Toolkit supports for this endpoint the
            // HTTP-Redirect binding only
            'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
        ),
        // Specifies constraints on the name identifier to be used to
        // represent the requested subject.
        // Take a look on lib/Saml2/Constants.php to see the NameIdFormat supported
        'nameIdFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',

        // Usually x509cert and privateKey of the SP are provided by files placed at
        // the certs folder. But we can also provide them with the following parameters
        // 'x509cert' => file_get_contents(\siu\bootstrap::get_dir_instalacion() . '/saml/saml.crt'),
        // 'privateKey' > file_get_contents(\siu\bootstrap::get_dir_instalacion() . '/saml/saml.pem'),
    ),

    // Identity Provider Data that we want connect with our SP
    'idp' => array (
        // Identifier of the IdP entity  (must be a URI)
        'entityId' => $url_idp.'/saml2/idp/metadata.php',
        // SSO endpoint info of the IdP. (Authentication Request protocol)
        'singleSignOnService' => array (
            // URL Target of the IdP where the SP will send the Authentication Request Message
            'url' => $url_idp.'/saml2/idp/SSOService.php',
            // SAML protocol binding to be used when returning the <Response>
            // message.  Onelogin Toolkit supports for this endpoint the
            // HTTP-POST binding only
            'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
        ),
        // SLO endpoint info of the IdP.
        'singleLogoutService' => array (
            // URL Location of the IdP where the SP will send the SLO Request
            'url' => $url_idp.'/saml2/idp/SingleLogoutService.php',
            // SAML protocol binding to be used when returning the <Response>
            // message.  Onelogin Toolkit supports for this endpoint the
            // HTTP-Redirect binding only
            'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
        ),
        // Public x509 certificate of the IdP
        // 'x509cert' => \siu\bootstrap::get_dir_instalacion() . '/saml/saml.crt',
        /*
         *Instead of use the whole x509cert you can use a fingerprint
         *(openssl x509 -noout -fingerprint -in "idp.crt" to generate it)
         */
         'certFingerprint' => '<fingerprint>',
    ),

    //Advanced settings
    // Security settings
    'security' => array (

            /** signatures and encryptions offered */

            // Indicates that the nameID of the <samlp:logoutRequest> sent by this SP
            // will be encrypted.
            'nameIdEncrypted' => false,

            // Indicates whether the <samlp:AuthnRequest> messages sent by this SP
            // will be signed.              [The Metadata of the SP will offer this info]
            'authnRequestsSigned' => false,

            // Indicates whether the <samlp:logoutRequest> messages sent by this SP
            // will be signed.
            'logoutRequestSigned' => false,

            // Indicates whether the <samlp:logoutResponse> messages sent by this SP
            // will be signed.
            'logoutResponseSigned' => false,

         /* Sign the Metadata
         False || True (use sp certs) || array (
                                                                                                keyFileName => 'metadata.key',
                                                                                                certFileName => 'metadata.crt'
                                                                                        )
        */
         'signMetadata' => false,


            /** signatures and encryptions required **/

            // Indicates a requirement for the <samlp:Response>, <samlp:LogoutRequest> and
            // <samlp:LogoutResponse> elements received by this SP to be signed.
            'wantMessagesSigned' => false,

            // Indicates a requirement for the <saml:Assertion> elements received by
            // this SP to be signed.        [The Metadata of the SP will offer this info]
            'wantAssertionsSigned' => false,

            // Indicates a requirement for the NameID received by
            // this SP to be encrypted.
            'wantNameIdEncrypted' => false,
    ),

    // Contact information template, it is recommended to suply a technical and support contacts
    'contactPerson' => array (
            'technical' => array (
                    'givenName' => 'CAMBIAR',
                    'emailAddress' => 'CAMBIAR'
            ),
            'support' => array (
                    'givenName' => 'CAMBIAR',
                    'emailAddress' => 'CAMBIAR'
            ),
    ),

    // Organization information template, the info in en_US lang is recomended, add more if required
    'organization' => array (
            'en-US' => array(
                    'name' => 'CAMBIAR',
                    'displayname' => 'CAMBIAR',
                    'url' => 'CAMBIAR.com'
            ),
    ),
);

Una vez terminado esto ir al archivo <path_3w>/instalacion/login.php y configurar lo siguiente:

'saml'   => array(
        'activo'     => true,
        'clase'      => 'modelo\\autenticacion\\auth_saml',
        'parametros' => array(
            'settings_file' => \siu\bootstrap::get_dir_instalacion() . '/saml/settings.php',
            'saml_uid' => 'userAccounts',// 'urn:oid:0.9.2342.19200300.100.1.1', //se matchea con local_uid
                        'local_uid' => 'usuario', //puede ser 'persona'
        ),
    ),

Agregar en <path_gestion>/instalacion/instalacion.ini de gestión estas variables según lo que se tiene en araí usuarios para cada aplicación, ej:

appUniqueIdGestion = "<app_unique_id_gestion>"
appUniqueId3w = "<app_unique_id_3w>"

Nota:

<app_unique_id_gestion> y <app_unique_id_3w> son los appUniqueId de SIU-Guaraní Gestión y 3W respectivamente, se obtienen de SIU-Araí Usuarios menú de Aplicaciones.

Migrando usuarios de SIU-Guaraní a SIU-Araí

Exportación de usuarios

Los usuarios actuales que poseemos en gestión los deberíamos tener disponibles en una cuenta de Araí. Para exportarlos deberíamos realizar lo siguiente:

bin/guarani exportar_usuarios_arai

Este comando posee las siguiente opciones:

-d => Path donde se guarda el archivo, por defecto -> $this->get_instalacion()->get_dir()/usersExportFiles/,
-f => Nombre del archivo donde se exportaran los usuarios, por defecto -> usuarios_ . date('YmdHis'),
-m => Nombre del responsable, por defecto -> toba,
-e => Mails del responsable,  por defecto -> toba

Importando usuarios a Araí

Para importar las cuentas, el módulo SIU-Araí: Usuarios proporciona un comando de consola, que nos permite cargar la información de un conjunto de usuarios y/o cuentas, todo a partir de un archivo en formato json. Para ejecutar el comando primero será necesario cargar el entorno, para lo cual podemos ejecutar:

cd /ruta/siu-arai/usuarios
. ./entorno_toba.env

Una vez cargado el entorno, es posible ejecutar la exportación de la siguiente forma:

toba proyecto importar_usuarios_arai -f <path_completo_archivo.json> -m <comparador> [-t cuentas|personas] -p arai_usuarios

Este comando procesará un archivo en la ruta /ruta/modulo/siu/instalacion/usersExportFiles/cuentas-xxx-arai.json importando las definiciones de personas y/o cuentas, teniendo en cuenta las opciones de comparación.

Al momento de importar, es necesario elegir como se comparan los datos de usuarios/personas a importar con los que pueden existir, mediante el argumento <comparador>. Este puede ser uno de los siguientes:

• 0: Género, tipo y número de documento
• 1: Tipo y número de documento
• 2: Email
• 3: atributo UniqueIdentifier
• 4: No intenta matchear, sólo agrega cuentas nuevas para las personas

De forma opcional, se puede indicar con el argumento -t si se desea importar la información de cuentas o solamente la información de personas.

Una vez realizada la importación, el proceso nos mostrará un resumen de las acciones realizadas, así como los posibles inconvenientes que pueden haber surgido al momento de importar y comparar los datos existentes.

Para más información puede consultar la documentación de Araí

Creando documentos de forma asincrónica en SIU-Araí (Novedad a partir de SIU-Guaraní 3.18.1)

A partir de SIU-Guaraní 3.18.1, todas las operaciones de cierre de actas almacenan las mismas en SIU-Araí, pero dicha comunicación entre sistemas es llevada a cabo se forma asincrónica. La ventaja se este mecanismo es que si SIU-Araí no se encuentra operativo o presenta alguna falla, SIU-Guaraní igualmente puede llevar a cabo el cierre de actas.

Esto conlleva lo siguiente:

Creando tabla donde se encolarán los documentos a crear en SIU-Araí

Ejecutar el siguiente comando (por única vez) parados en el directorio raíz de SIU-Guaraní Gestión:

bin/guarani crear_cola_documentos_arai

Dicho comando creará la tabla arai_documentos_cola en la base de datos de SIU-Guaraní, la misma es utilizada para encolar los documentos que luego serán creados en SIU-Araí de forma asincrónica.

Ejecutando worker para procesar los documentos encolados

Ejecutar el siguiente comando parados en el directorio raíz de SIU-Guaraní Gestión:

bin/guarani sincronizar_documentos_arai

Dicho comando ejecutará un worker (proceso demonio) que desencola documentos de la tabla arai_documentos_cola e intentará crearlos en SIU-Araí. Debemos asegurarnos que dicho worker siempre se encuentre ejecutándose.

Resincronizando documentos fallidos

En SIU-Guaraní Gestión disponemos de la operación Sincronizar Masivamente Documentos con Araí. Todos los documentos que fallen al intentar crearse con el worker del punto anterior podrán ser resincronizados en esta operación. También posee información con las causas por las cuales falla la creación del documento en SIU-Araí.

Notificando a los administradores

En el caso de que haya fallado la creación de algún documento en SIU-Araí, se puede notificar a los administradores de SIU-Guaraní via email ejecutando el siguiente comando parados en el directorio raíz de SIU-Guaraní Gestión:

bin/guarani notificar_administradores

Dicho comando le envía un email a todos los administradores de SIU-Guaraní, avisándoles que deben ingresar a la operación Sincronizar Masivamente Documentos con Araí para resincronizar los documentos fallidos.

NOTA: Los administradores deben tener algún email asociado en la operación Administrar Personas para poder recibir dicha notificación.

< Volver