¡Esta es una revisión vieja del documento!
−Tabla de Contenidos
Integración mediante servicios web
Siette dispone de un conjunto de servicios web para establecer mediante un protocolo seguro una relación de confianza con otro sistema web. La idea general es que Siette actúe como servidor y el sistema externo como cliente y que el sistema externo pueda pedir a Siette que realice una evaluacion de un usuario y le devuelva los resultados.
Para ello lo primero de todo es establecer entre Siette y el sistema externo un mecanismo de autentificación mediante un par de claves pública y privada. El sistema externo mantiene la clave privada y Siette sólamente necesita la clave pública. Siette debe dar de alta al nuevo sistema incluyendolo como una nueva procedencia en su base de datos, asignandole un identificador (alfanumérico) que debe ser tambien conocido por el sistema externo. (systemIdentifier). Esta tarea que debe realizar exclusivamente el administrador.
Una vez establecida la relación de confianza entre ambos sistemas, Siette juega el rol de servidor al que el otro sistema le envia mensajes a los que Siette responde. En general el sistema externo tendrá sus propios usuarios, y lo primero que debe hacer es llamr a Siette y decirle que cree un usuario en Siette que estará en correspondencia con el usuario del sistema externo. Para ello invocará el servicio web registerUser pasando a Siette una información mínima. De entre todos los campos que debe comunicar a Siette sólo es imprescindible el nombre y apellidos del usaurio, todos los demás campos pueden dejarse en blanco, incluyendo la contraseña.
Los usuarios creados en Siette a través de un sistema externo se identifican mediante el nombre de usuario (userName) y la procedencia (systemIdentifier), y solo pueden acceder a Siette a través del sistema externo, ya que el entorno principal de Siette no admite el acceso directo de estos usuarios.
Una vez creados los usuarios, el siguiente paso consiste en establecer la conexión mediante el servicio authenticateUser, servicio al que se le pasan también como parámetros el nombre de usuario y el identificador del sistema.
Como medida de seguridad todas las conexiones entre el sistema externo y Siette que impliquen acceso a Siette deben estar firmadas. La firma consiste en la codificación mediante RSA SHA-1 usando la clave privatda de la cadena que se obtiene concatenando el nombre de usuario y la procedencia. El sistema externo debe ser capaz de realizar esta codificación, que se añade como parámetro en la llamada al servicio web.
Una vez establecida la conexión de un usuario, Siette devuelve un token temporal o credencial (credentialIdentifier), que puede ser usada en cualquier URL que llame a Siette, ya sea para iniciar un test o para solicitar una pregunta, o los resultados de una sesion. Al recibir este parámetro Siette reconoce la credencial y la asocia al usuario que la solicito, de manera que no es necesario repetir la autentificación mientras la credencial no haya expirado.
Para simplificar la implementación de los clientes de los servicios web se han implementado clases auxiliares en JSP y en PHP, y se han desarrollado aplicaciones de ejemplo que muestran paso a paso el proceso de conexión, autenticación y realización de un test.
Un caso particular del uso de los servicios web en PHP es la integración con Moodle que se ha llevado a cabo mediante la implementación de un plugin que usa los servicios web.
Generación de las claves pública y privada
Para generar la pareja de claves pública y privada puede usarse cualquier sistema de cifrado. A continuación se indican las instrucciones necesarias utilizando la utilidad OpenSSL
Generar una clave privada con RSA en un archivo con formato PEM
openssl genrsa -out /ruta/archivo_priv.pem [-des]
Generar una clave publica a partir de una privada, con RSA en un archivo
openssl rsa -in /ruta/archivo_priv.pem -pubout -out /ruta/archivo_pub.pem
Consultar la clave generada en un archivo con formato PEM:
openssl rsa -in /ruta/archivo.pem -inform PEM -text [-pubin]
Firmar archivo:
openssl rsautl -sign -inkey /ruta/archivo_priv.pem -in /ruta/archivo_a_firmar.txt -out /ruta/archivo_firma.txt
Verificar un archivo firmado:
openssl rsautl -verify -pubin -inkey /ruta/archivo_pub.pem -in /ruta/archivo_firma.txt
Ejemplo:
openssl genrsa -out priv_key.pem
openssl rsa -in priv_key.pem -pubout -out pub_key.pem
openssl rsa -in priv_key.pem -inform PEM -text
openssl rsa -in pub_key.pem -inform PEM -text -pubin
Conexión a los servicios web
Una vez definidas las claves, dependiendo del lenguaje de programación que se vaya a utilizar se implementará el cliente de los sevicios web. Para aplicaciones basadas en JSP y en PHP se han implementado ya algunas clases para facilitar la construcción del cliente. La direccion de os servicios es /services/External, y servicios web disponibles son los siguientes:
| Nombre | Parámetros | Función |
|---|---|---|
| echo | Sirve para comprobar que el mecanismo de comunicación mediante servicios web funciona | |
| getNumberOfUsers | systemIdentifier | Devuelve un entero con el numero de usuarios de esa procedencia registrados actualmente en Siette |
| authenticateUser | userName, systemIdentifier,rsaSha1Signature | Crea un registro del usuario en Siette asignandole un token o credencial que puede usar temporalmente para acceder sin necesidad de volver a conectarse. |
| authenticateExternalUser | user,systemIdentifier,rsaSha1Signature | Igual al anterior, pero usando un bean user como parámetro, en vez de solo nombre de usuario. Si el usuario no está creado en Siette lo crea. |
| authenticateSystem | string,systemIdentifier,rsaSha1Signature | Es un método que sirve solamente para comprobar que el mecanismo de comunicación entre ambos sistemas esta funcionando. El primer parametro es una cadena cualquier a codificar. Devuelve true si el proceso ha tenido exito. |
| registerUser | userData,rsaSha1Signature | Crea un usuario en Siette correspondiente a un uusario remoto en el sistema externo. Devuelve true si el proceso se completa satisfactoriamente. |
| existsExternalUser | userName,systemIdentifier | Devuelve true si el usuario del sistema externo está ya registrado en Siette. |
| getTestListTeacher | userName,systemIdentifier,language | Devuelve la lista de asignaturas y de test accesibles por el profesor en el idioma selecionado |
| getTestListStudent | userName,systemIdentifier,language | Devuelve la lista de asignaturas a las que puede acceder el alumno en el idioma selecionado |
| getSubjectListTeacher | userName,systemIdentifier,language | Devuelve la lista de asignaturas del profesor en el idioma selecionado |
| getSubjectListStudent | userName, systemIdentifier, language | Devuelve la lista de asignaturas a las que puede acceder el alumno en el idioma selecionado |
| getTestQuestions | idTest,colaborative,hostAdress,userName,systemIdentifier,rsaSha1Signature | Devuelve un documento XML en formato SQTI que contiene la lista de todas las posibles preguntas que podrían aparecer en un determinado test. ESte método esta pensado para transmitir a un sistema externo de una sola vez un conjunto de preguntas de Siette, por ejemplo a un dispositivo móvil |
| beginTestSession | idTest,colaborative,hostAdress,userName,systemIdentifier,rsaSha1Signature | Este método crea una sesion de un test en Siette para un determinado alumno, y devuelve el identificador de la sesion. Una vez creada la sesion, el test puede realizarse mediante llamadas HTTP que contengan la cadena de autenticación |
| getSessionScore | idsession | Devuelve en forma de cadena de caracteres la calificación final obtenida en la sesion cuyo identificador se pasa como parámetro. |
| hasExpiredSIETTESession | credentialIdentifier | Devuelve true si la credencial que se obtuvo ha expirado. |
Los parámetros de estas servicios son los siguientes:
| Parámetro | Tipo | Contenido |
|---|---|---|
userName | string | Cadena alfanumerica de menos de 16 caracteres que contiene el identificador del usuario |
systemIdentifier | string | Identificador para Siette del sistema externo. |
rsaSha1Signature | string | Cadena de caracteres correspondiente al cifrado (usando la clave privada del sistema) mediante RSA SHA-1 de la cadena de caracteres obtenida con la concatenacion de userName@rsaSha1Signature. Siette descifrará este mensaje mediante la clave pública y validará que corresponde al usuario que realiza la petición |
language | string | Cadena de idioma, puede ser en (Español); en (Inglés); de (Alemán); o fr (Francés). |
user userData | {
string firstName;
string lastName;
string userName;
string email;
string userPassword;
string systemIdentifier;
boolean isTeacher;
}
| Bean que contiene los datos del usuario para registrar en Siette |
idTest | int | Id del test que se va a realizar. |
colaborative | boolean | true si el test a realizar se hace en modo colaborativo |
hostAdress | string | Direccion del servidor |
idsession | int | Identificador de la sesion del alumno. |
credentialIdentifier | string | Secuencia de caracteres que da acceso a Siette a un usuario externo. |
El servicio echo esta pensado para probar que inicialmente la comunicación funciona:
https://www.siette.org/siette/services/External?method=echo
debe devolver:
<soapenv:Envelope>
<soapenv:Body>
<echoResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<echoReturn xsi:type="soapenc:string" xsi:nil="true"/>
</echoResponse>
</soapenv:Body>
</soapenv:Envelope>
En el siguiente enlace se muestra el fichero WSDL que describe todos los servicios web disponible en Siette, y los parámetros necesarios para la llamada: