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
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>:<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_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>):
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>).
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
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
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:
............
'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
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:
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:
Abrir el archivo settings.php y dejar el siguiente contenido.
//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:
'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:
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:
Este comando posee las siguiente opciones:
-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:. ./entorno_toba.env
Una vez cargado el entorno, es posible ejecutar la exportación de la siguiente forma:
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:
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:
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:
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.
