Diferencia entre revisiones de «SIU-Arai/usuarios/integracion-inicial-toba»

De SIU
Saltar a: navegación, buscar
(intro integracion)
m
 
(No se muestran 20 ediciones intermedias de 2 usuarios)
Línea 1: Línea 1:
 
[[Archivo:siu-arai_iso.png|derecha|link=SIU-Arai]]
 
[[Archivo:siu-arai_iso.png|derecha|link=SIU-Arai]]
 
= Integrando una aplicación Toba =
 
= Integrando una aplicación Toba =
 +
 +
La integración de una aplicación propia desarrollada en SIU-Toba tiene múltiples facetas. Es posible configurar para disfrutar de:
 +
* '''Single Sign-on''' y '''Single Logout''' por medio de SAML
 +
* Visualizar el ícono de aplicación en el menú de aplicaciones integrado o '''AppLauncher'''
 +
* Proveer autoconfiguración para una api/servicio de la aplicación que de desea sea consumida por otras aplicaciones registradas en la plataforma
 +
* Proveer autoconfiguración para una api/servicio que la aplicación consume de otros registrados en la plataforma.
  
 
== Requisitos previos ==
 
== Requisitos previos ==
  
−
=== Utilizar Composer ===
+
=== Utilizar la plataforma SIU-Arai ===
  
−
Es recomendable que el proyecto se gestione mediante composer para la instalación y actualización de librerías y dependencias. En la wiki de SIU-Toba [http://toba.siu.edu.ar/trac/toba/wiki/Instalacion/Composer], se encuentra una referencia detallada de como realizar este paso.
+
Es un poco obvio, pero es necesario contar con [http://documentacion.siu.edu.ar/wiki/SIU-Arai/registry Arai-Registry] y [http://documentacion.siu.edu.ar/wiki/SIU-Arai/usuarios Arai-Usuarios] funcionando adecuadamente, para poder registrar una aplicación y hacer uso del IdP e IdM que provee la plataforma.
  
−
=== Integración con toba-usuarios ===
+
=== Dependencias del Sistema Operativo ===
−
Si el proyecto utiliza la gestión de usuarios que proporciona SIU-Toba, este punto es transparente y no requiere de cambios adicionales.  
+
Para poder integrar correctamente una aplicación a la plataforma SIU-Araí en la versión 2, se tiene que instalar y dejar configurado de manera adecuada las versiones de las librerías relacionadas con Sodium. En esta [http://documentacion.siu.edu.ar/wiki/IT/Sodium guía] se describe requerimientos y versiones compatibles. Esto es necesario realizarlo para poder generar adecuadamente las claves de encriptación.
−
----
 
  
−
== Configurar la aplicación ==
+
=== Dependencias con Composer ===
  
−
(flags)
+
Es recomendable que el proyecto se gestione mediante '''''composer''''' para la instalación y actualización de librerías y dependencias. En la [http://toba.siu.edu.ar/trac/toba/wiki/Instalacion/Composer wiki] de SIU-Toba, se encuentra una referencia detallada de como realizar este paso.
−
----
 
  
−
== Aplicaciones con usuarios existentes ==
+
Una vez se tenga el archivo <code>composer.json</code>, se debe editar y agregar una serie de dependencias: 
 +
# [https://github.com/SIU-Toba/framework SIU-Toba] en la versión v3.0.22 o superior 
 +
# La librería [http://documentacion.siu.edu.ar/wiki/SIU-Arai/arai-cli arai-cli] en la versión v2.5.0  o superior 
 +
# La librería [https://github.com/paragonie/halite Halite], en la versión v1.6.0. Es requerida para generar las claves de encriptación   
 +
 
 +
<syntaxhighlight lang="bash" enclose="div" highlight="3">
 +
  ...
 +
  "require": {
 +
    "paragonie/halite": "1.6.0",
 +
    "siu-toba/framework": "^3.0.30",
 +
    "siu/arai-cli": "^2.5.0"
 +
  },
 +
  "autoload": {
 +
    "psr-4": { "": "src" }
 +
  },
 +
  ...
 +
</syntaxhighlight>
  
−
=== Exportar los usuarios ===
+
Luego de realizar el cambio, siempre se debe proceder a actualizar la lista de dependencias:
  
−
Si ya tienen una base de usuarios existente, lo más recomendable es exportarlos desde la aplicación e importarlos en Arai-Usuarios. Para ello, a partir de la versión 2.7.2 de SIU-Toba [http://toba.siu.edu.ar/trac/toba/wiki/Versiones/2.7.0#a2.7.2], se integró un comando que permite exportarlos de dicha aplicación, en un archivo de formato estructurado tipo '''.json'''.
+
<syntaxhighlight lang="bash" enclose="div">
 +
composer update
 +
</syntaxhighlight>
  
−
<syntaxhighlight lang="bash" enclose="div">
+
=== Integración con Toba-Usuarios ===
−
toba proyecto exportar_usuarios_arai
+
Si el proyecto utiliza la gestión de usuarios que proporciona SIU-Toba, este punto es transparente y no requiere de cambios adicionales. 
 +
 
 +
=== Claves para encriptación ===
 +
A partir de la versión 2.0 de la plataforma, todo el intercambio que se produce entre  un módulo y '''SIU-Arai: Registry''', requiere tener generado y configurado una clave que será utilizada para encriptar la información sensible.  La librería arai-cli permite generar manualmente estas claves. Adicionalmente, el [https://gitlab.siu.edu.ar/siu/instalador instalador de proyectos SIU] permite automatizar esta generación y configuración al momento de realizar la instalación del proyecto.
 +
 
 +
=== Configuración para servicios REST ===
 +
Si la aplicación que se intenta sincronizar es consumidor y/o proveedor de servicios de '''api''' tipo REST, será necesario que se tenga correctamente configurado los datos de acceso tanto en el <code>cliente.ini</code> como en el <code>servidor.ini</code> según corresponda.  Remitirse a la [http://toba.siu.edu.ar/trac/toba/wiki/Referencia/Rest documentación] del framework SIU-Toba disponible al respecto.
 +
 
 +
Adicionalmente, en el archivo <code>arai.json</code> tendrán que asegurarse de tener configurado las entradas <code>provide</code> y/o <code>consume</code> con los servicios deseados.
 +
 
 +
=== Configuración para servicios de toba_usuarios ===
 +
Si la aplicación que se intenta sincronizar hace uso de '''toba_usuarios''', será necesario que se tenga correctamente configurado el cliente REST de dicho proyecto. Para ello, tendrán que editar el archivo <code>/ruta/proyecto/instalacion/i__produccion/'''p__toba_usuarios'''/rest/rest_arai_usuarios/cliente.ini</code>.
 +
 
 +
Adicionalmente, en el archivo <code>arai.json</code> tendrán que asegurarse de tener configurado en consume <code>api:siu/arai-usuarios</code>.
 +
 
 +
=== Configuración de la URL global de la instancia ===
 +
Las instalaciones Toba por defecto tienen un atributo <code>full_url</code> en el archivo <code>/ruta/proyecto/instalacion/instancia.ini</code> que debe contener la URL completa y accesible del proyecto. Sirve para sincronizar en Registry e indicar el punto de acceso de la aplicación y de las '''api'''. Es importante que esta URL no termine en <code>/</code>.
 +
 
 +
=== Integrar al menú de aplicaciones ===
 +
SIU-Toba proporciona una implementación de barra o lanzador de apliaciones, desde el cual se puede acceder a todas las aplicaciones integradas a la plataforma SIU-Arai (siempre y cuando tenga permiso de acceder el usuario particular). Esto se activa configurando el archivo <code>proyecto.ini</code> y agregando la siguente entrada:
 +
 
 +
<syntaxhighlight lang="yaml" enclose="div">
 +
[proyecto]
 +
...
 +
;Esta entrada activa el uso del appLauncher
 +
app_launcher = 1
 +
</syntaxhighlight>
 +
 
 +
== Integrar a Arai-Registry la aplicación ==
 +
 
 +
Gracias a la librería [http://documentacion.siu.edu.ar/wiki/SIU-Arai/arai-cli arai-cli], se pueden registrar las aplicaciones a la plataforma SIU-Arai de forma sencilla. En la [[SIU-Arai/registry#Funcionamiento|documentación]] de Arai-Registry se describe mayores detalles al respecto.
 +
 
 +
=== Configurar las necesidades ===
 +
 
 +
Arai-Registry permite indicar que servicios consume y proporciona una aplicación. Para ello lo primero a realizar es crear un archivo llamado <code>arai.json</code> que esté ubicado en la raíz del proyecto con el siguiente contenido:
 +
 
 +
<syntaxhighlight lang="yaml" enclose="div" highlight="2,5">
 +
{
 +
  "name": "institucion/proyecto",
 +
  "description": "UNI-Proyecto, aplicación",
 +
  "scripts": {
 +
    "hooks": "UNI\\Proyecto\\AraiRegistryHooks"
 +
  },
 +
  "provide": [
 +
    {
 +
      "name": "app:institucion/proyecto",
 +
      "alias": "Nombre proyecto",
 +
      "description": "descripción proyecto",
 +
      "version": "0.1.0",
 +
      "icon": "./www/img/logo_iso.png"
 +
    }
 +
  ],
 +
  "consume": [
 +
    {
 +
      "name": "service:siu/sso-saml-idp",
 +
      "version": ">=0.1.0"
 +
    },
 +
    {
 +
      "name": "api:siu/arai-usuarios",
 +
      "version": ">=0.1.0",
 +
      "options": {
 +
        "toba-rest": [
 +
          { "proyecto": "toba_usuarios", "rest-id": "rest_arai_usuarios" }
 +
        ]
 +
      }
 +
    }
 +
  ]
 +
}
 +
</syntaxhighlight>
 +
 
 +
Es muy relevante establecer el atributo '''name''' y '''description''' con los valores deseados. Para el atributo '''hooks''', se debe completar con la ruta o ''namespace'' del proyecto hasta la clase php. Esta se crea en el siguiente paso. 
 +
 
 +
=== Hook de auto-configuración ===
 +
 
 +
El hook de configuración es una clase php que implementa la interfaz [https://hub.siu.edu.ar/siu-arai/arai-cli/blob/master/src/SIU/AraiCli/Services/Registry/HooksInterface.php HooksInterface]. Este archivo tiene una nomenclatura estándar, siempre se denomina ''AraiRegistryHooks'' y para proyectos SIU-Toba, extienden de ''RegistryHooksProyectoToba''. Se deberá crear dicha clase dentro del directorio /src del proyecto, o en algún punto que esté configurado con el autoloader de composer. Suponiendo en este ejemplo, el archivo sería <code>/src/UNI/Proyecto/AraiRegistryHooks.php</code>:
 +
 
 +
<syntaxhighlight lang="php" enclose="div" highlight="2">
 +
<?php
 +
namespace UNI\Proyecto;
 +
 
 +
use SIUToba\Framework\Arai\RegistryHooksProyectoToba;
 +
 
 +
class AraiRegistryHooks extends RegistryHooksProyectoToba
 +
{
 +
 
 +
}
 +
</syntaxhighlight><blockquote>Recordar que la clase tiene que poder ser cargada por el autoloader de Composer. Ver [http://foro.comunidad.siu.edu.ar/index.php?topic=14708.msg63975#msg63975 ejemplo].</blockquote>
 +
 
 +
== Registrar en Arai-Registry la aplicación ==
 +
Una vez hechos todos los pasos previos, y cumpliendo con los requisitos de configuración sobre una instalación existente, el flujo normal para registrar una aplicación en Registry consiste en generarse una clave de  sincronización, para luego agregar y sincronizar las configuraciones.  Ante futuros cambios, ya simplemente es necesario ejecutar la sincronización únicamente.
 +
 
 +
=== 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:<syntaxhighlight lang="bash" enclose="div" highlight="4">
 +
./bin/arai-cli arai:generar-key --destino=/ruta/donde/guardar/arai-sync.key
 +
</syntaxhighlight>También será necesario configurar en el archivo <code>instalacion.ini</code> del proyecto, la entrada  <code>arai_sync_key_file</code> con la ruta donde se aloja la clave previamente creada.<syntaxhighlight lang="bash" enclose="div" highlight="4">
 +
...
 +
arai_sync_key_file=/ruta/donde/guardar/arai-sync.key
 +
 
 +
</syntaxhighlight><blockquote>Estos pasos pueden ser opcionales implementando el instalador de proyectos SIU.</blockquote>
 +
 
 +
=== Registrar el proyecto ===
 +
 
 +
Si todo está en orden, por única vez, el proceso de registración a la plataforma SIU-Arai de la aplicación se concreta haciendo uso de la librería previamente  con el siguiente comando:
 +
 
 +
<syntaxhighlight lang="bash" enclose="div" highlight="4">
 +
./bin/arai-cli registry:add  \
 +
    --maintainer nombre-encargado-admin \
 +
    --maintainer-email email-encargado-admin@uni.edu.ar \
 +
    http://url-arai-registry/arai-registry
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
=== Importar los usuarios ===
+
<blockquote>
 +
Se debe proporcionar la url válida del servicio Arai-Registry, junto con los datos del administrador.
 +
</blockquote>
  
−
En Arai-Usuarios, es posible importar usuarios existentes de otras aplicaciones, de modo que la integración pueda realizarse con sistemas que ya están en operación. Para ello, existe un comando que permite importar el archivo '''.json''' que se exportó en el paso previo.  
+
=== Sincronizar el proyecto ===
 +
Siempre que registremos alguna aplicación a Araí-Registry, es necesario realizar un <code>registr:sync</code> 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 Arai-Registry la ''buena nueva''.
  
 
<syntaxhighlight lang="bash" enclose="div">
 
<syntaxhighlight lang="bash" enclose="div">
−
toba proyecto importar_usuarios_arai
+
./bin/arai-cli registry:sync
 
</syntaxhighlight>
 
</syntaxhighlight>
−
----
 
  
−
== Integrar al menú de aplicaciones ==
+
<blockquote>
 +
Este paso es necesario realizarlo también en Arai-Usuarios, para que este sistema se entere de la presencia de una nueva aplicación.
 +
</blockquote>
  
−
- flag launcher
+
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.
−
- para crear cuenta: crear persona en arai-usuarios, luego vincular desde la app toba-usuarios!
 

Revisión actual del 15:17 13 sep 2018

Siu-arai iso.png

Integrando una aplicación Toba

La integración de una aplicación propia desarrollada en SIU-Toba tiene múltiples facetas. Es posible configurar para disfrutar de:

  • Single Sign-on y Single Logout por medio de SAML
  • Visualizar el ícono de aplicación en el menú de aplicaciones integrado o AppLauncher
  • Proveer autoconfiguración para una api/servicio de la aplicación que de desea sea consumida por otras aplicaciones registradas en la plataforma
  • Proveer autoconfiguración para una api/servicio que la aplicación consume de otros registrados en la plataforma.

Requisitos previos

Utilizar la plataforma SIU-Arai

Es un poco obvio, pero es necesario contar con Arai-Registry y Arai-Usuarios funcionando adecuadamente, para poder registrar una aplicación y hacer uso del IdP e IdM que provee la plataforma.

Dependencias del Sistema Operativo

Para poder integrar correctamente una aplicación a la plataforma SIU-Araí en la versión 2, se tiene que instalar y dejar configurado de manera adecuada las versiones de las librerías relacionadas con Sodium. En esta guía se describe requerimientos y versiones compatibles. Esto es necesario realizarlo para poder generar adecuadamente las claves de encriptación.

Dependencias con Composer

Es recomendable que el proyecto se gestione mediante composer para la instalación y actualización de librerías y dependencias. En la wiki de SIU-Toba, se encuentra una referencia detallada de como realizar este paso.

Una vez se tenga el archivo composer.json, se debe editar y agregar una serie de dependencias:

  1. SIU-Toba en la versión v3.0.22 o superior
  2. La librería arai-cli en la versión v2.5.0 o superior
  3. La librería Halite, en la versión v1.6.0. Es requerida para generar las claves de encriptación
  ...
  "require": {
    "paragonie/halite": "1.6.0",
    "siu-toba/framework": "^3.0.30",
    "siu/arai-cli": "^2.5.0"
  },
  "autoload": {
    "psr-4": { "": "src" }
  },
  ...

Luego de realizar el cambio, siempre se debe proceder a actualizar la lista de dependencias:

composer update

Integración con Toba-Usuarios

Si el proyecto utiliza la gestión de usuarios que proporciona SIU-Toba, este punto es transparente y no requiere de cambios adicionales.

Claves para encriptación

A partir de la versión 2.0 de la plataforma, todo el intercambio que se produce entre un módulo y SIU-Arai: Registry, requiere tener generado y configurado una clave que será utilizada para encriptar la información sensible. La librería arai-cli permite generar manualmente estas claves. Adicionalmente, el instalador de proyectos SIU permite automatizar esta generación y configuración al momento de realizar la instalación del proyecto.

Configuración para servicios REST

Si la aplicación que se intenta sincronizar es consumidor y/o proveedor de servicios de api tipo REST, será necesario que se tenga correctamente configurado los datos de acceso tanto en el cliente.ini como en el servidor.ini según corresponda. Remitirse a la documentación del framework SIU-Toba disponible al respecto.

Adicionalmente, en el archivo arai.json tendrán que asegurarse de tener configurado las entradas provide y/o consume con los servicios deseados.

Configuración para servicios de toba_usuarios

Si la aplicación que se intenta sincronizar hace uso de toba_usuarios, será necesario que se tenga correctamente configurado el cliente REST de dicho proyecto. Para ello, tendrán que editar el archivo /ruta/proyecto/instalacion/i__produccion/p__toba_usuarios/rest/rest_arai_usuarios/cliente.ini.

Adicionalmente, en el archivo arai.json tendrán que asegurarse de tener configurado en consume api:siu/arai-usuarios.

Configuración de la URL global de la instancia

Las instalaciones Toba por defecto tienen un atributo full_url en el archivo /ruta/proyecto/instalacion/instancia.ini que debe contener la URL completa y accesible del proyecto. Sirve para sincronizar en Registry e indicar el punto de acceso de la aplicación y de las api. Es importante que esta URL no termine en /.

Integrar al menú de aplicaciones

SIU-Toba proporciona una implementación de barra o lanzador de apliaciones, desde el cual se puede acceder a todas las aplicaciones integradas a la plataforma SIU-Arai (siempre y cuando tenga permiso de acceder el usuario particular). Esto se activa configurando el archivo proyecto.ini y agregando la siguente entrada:

[proyecto]
...
;Esta entrada activa el uso del appLauncher
app_launcher = 1

Integrar a Arai-Registry la aplicación

Gracias a la librería arai-cli, se pueden registrar las aplicaciones a la plataforma SIU-Arai de forma sencilla. En la documentación de Arai-Registry se describe mayores detalles al respecto.

Configurar las necesidades

Arai-Registry permite indicar que servicios consume y proporciona una aplicación. Para ello lo primero a realizar es crear un archivo llamado arai.json que esté ubicado en la raíz del proyecto con el siguiente contenido:

{
  "name": "institucion/proyecto",
  "description": "UNI-Proyecto, aplicación",
  "scripts": {
    "hooks": "UNI\\Proyecto\\AraiRegistryHooks"
  },
  "provide": [
    {
      "name": "app:institucion/proyecto",
      "alias": "Nombre proyecto",
      "description": "descripción proyecto",
      "version": "0.1.0",
      "icon": "./www/img/logo_iso.png"
    }
  ],
  "consume": [
    {
      "name": "service:siu/sso-saml-idp",
      "version": ">=0.1.0"
    },
    {
      "name": "api:siu/arai-usuarios",
      "version": ">=0.1.0",
      "options": {
        "toba-rest": [
          { "proyecto": "toba_usuarios", "rest-id": "rest_arai_usuarios" }
        ]
      }
    }
  ]
}

Es muy relevante establecer el atributo name y description con los valores deseados. Para el atributo hooks, se debe completar con la ruta o namespace del proyecto hasta la clase php. Esta se crea en el siguiente paso.

Hook de auto-configuración

El hook de configuración es una clase php que implementa la interfaz HooksInterface. Este archivo tiene una nomenclatura estándar, siempre se denomina AraiRegistryHooks y para proyectos SIU-Toba, extienden de RegistryHooksProyectoToba. Se deberá crear dicha clase dentro del directorio /src del proyecto, o en algún punto que esté configurado con el autoloader de composer. Suponiendo en este ejemplo, el archivo sería /src/UNI/Proyecto/AraiRegistryHooks.php:

<?php
namespace UNI\Proyecto;

use SIUToba\Framework\Arai\RegistryHooksProyectoToba;

class AraiRegistryHooks extends RegistryHooksProyectoToba
{

}
Recordar que la clase tiene que poder ser cargada por el autoloader de Composer. Ver ejemplo.

Registrar en Arai-Registry la aplicación

Una vez hechos todos los pasos previos, y cumpliendo con los requisitos de configuración sobre una instalación existente, el flujo normal para registrar una aplicación en Registry consiste en generarse una clave de sincronización, para luego agregar y sincronizar las configuraciones. Ante futuros cambios, ya simplemente es necesario ejecutar la sincronización únicamente.

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:
./bin/arai-cli arai:generar-key --destino=/ruta/donde/guardar/arai-sync.key
También será necesario configurar en el archivo 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
Estos pasos pueden ser opcionales implementando el instalador de proyectos SIU.

Registrar el proyecto

Si todo está en orden, por única vez, el proceso de registración a la plataforma SIU-Arai de la aplicación se concreta haciendo uso de la librería previamente con el siguiente comando:

./bin/arai-cli registry:add  \
    --maintainer nombre-encargado-admin \
    --maintainer-email email-encargado-admin@uni.edu.ar \
    http://url-arai-registry/arai-registry

Se debe proporcionar la url válida del servicio Arai-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 api REST), este comando informará a Arai-Registry la buena nueva.

./bin/arai-cli registry:sync

Este paso es necesario realizarlo también en Arai-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.

Obtenido de «https://documentacion.siu.edu.ar/wiki/index.php?title=SIU-Arai/usuarios/integracion-inicial-toba&oldid=43839»