El mecanismo de autenticación de los servicios web es un poco raro, así que dejenos darle un ejemplo de como haríamos para llamar un servicio que cree un usuario en Chamilo desde otra aplicación en PHP... luego explicaremos las distintas partes.

$url = 'https://chamilo.net/main/webservices/';
$soap = new SoapClient($url.'registration.soap.php?wsdl');

// obtiene su propia IP, tal como la ve el servidor de Chamilo (necesaria
// para elaborar la clave de seguridad)
$myIp = file_get_contents($url.'testip.php');

// usa la security_key como definida en main/inc/conf/configuration.php
$key = '23534f3223a3cb234234324208';

// ahora podemos construir la clave que necesitamos
$finalKey = sha1($myIp.$key);

// prepara los detalles para mandar al servicio (en forma de array)
$params = array(
    'secret_key' => $finalKey,
    'firstname' => 'Yannick',
    'lastname' => 'Warnier',
    'status' => 5,
    'loginname' => 'ywarnier',
    'password' => '243fvsdfvs6dfv657dfvs32dfvs34dfv',
    'encrypt_method' => 'sha1',
    'email' => 'y@chamilo.org',
    'language' => 'spanish',
    'phone' => '',
    'expiration_date' => '2015-01-01',
    'original_user_id_name' => 'external_user_id',
    'original_user_id_value' => 34, 
    'official_code' => 34, 
    'extra' => array()
);

// finalmente, llamamos al servicio
$soap->WSCreateUserPasswordCrypted($params);

Al inicio, hemos formado una URL para acceder al WSDL. La mayoría de los archivos en main/webservices/ (casi todos) pueden ser llamados con un sufijo “?wsdl” para mostrar el WSDL (la presentación estructurada de las funciones disponibles). Esto debería ser suficiente para que cualquier cliente SOAP sepa qué funciones están disponibles para una llamada.

Luego hemos buscado una IP como el contenido del script testip.php. Este script está ahí específicamente para ayudarnos a formar la llave secreta: necesitamos mostrar al servidor que sabemos desde qué IP estamos llamando. Usando file_get_contents(), podemos obtener esta información directamente dentro de una variable.

Luego definimos una clave ($key)… Esta solamente la podemos obtener a través de un acceso directo al servidor web. Actua como una clave compartida (“shared key”) entre los dos servidores. Tenemos que abrir el archivo app/config/configuration.php, buscar la línea con $_configuration['security_key'], y luego copiar su valor dentro de nuestro script para formar nuestra clave secreta final. Esta es la que mandaremos al servicio web.

Finalmente, hemos preparado el array $params y llamado el servicio WSCreateUserPasswordCrypted(). Este servicio es una versión especial de WSCreateUser() que solo funciona si usamos el mismo método de cifrado de contraseñas de ambos lados (se tiene que mencionar en el parámetro encrypt_method que por ahora solo acepta 'md5' y 'sha1').

El parámetro original_user_id_name es lo que permite hacer el enlace entre Chamilo y nuestro servicio externo. Basta con darle un nombre constante que represente nuestro sistema y el hecho que se trata de un ID de usuario (por ejemplo joomla_uid sería un buen nombre para una conexión con un sistema Joomla, si es que este es el único sistema Joomla con el cual lo conectamos).Luego podemos darle el valor del ID del usuario en nuestro sistema externo dentro del parámetro original_user_id_value. Con este par de valores, podrá volver a editar o borrar cualquier usuario anteriormente creado via el servicio web : Chamilo mantendrá una relación entre el mismo y su sistema externo gracias al almacenamiento de estos datos.

La misma lógica funciona con los cursos y las sesiones: mantenemos, dentro de la base de datos de Chamilo, el dato del ID externo de esta entidad.

Algunos de los otros métodos disponiblies, con una explicación corta en cada caso:

function WSCreateUsers($params)

Crea usuarios por paquetes. Se espera una contraseña sin cifrado (lo cual es aceptable sobre HTTPS pero noen otros casos).

function WSCreateUser($params)

Crea solo un usuario.

function WSCreateUsersPasswordCrypted($params)

Crea usuarios tomando en cuenta que sus contraseñas podrían ser cifradas ya. Este método espera los parámetros siguientes :

$params = array(
    'secret_key' => $finalKey,
    'users' => array(
        0 => array(
            'firstname' => '…',
            'lastname' => '…',
            'status' => 5,
            'email' => '',
            'loginname' => '',
            'password' => '',
            'encrypt_method' => '',
            'language' => '',
            'phone' => '',
            'expiration_date' => '',
            'official_code' => '',
            'original_user_id_name' => '',
            'original_user_id_value'=> '',
            'extra' => ''
        )
    )
);

encrypt_method puede ser md5 o sha1 o none en el caso de pasarlo en claro.

function WSCreateUserPasswordCrypted($params)

Crea un solo usuario tomando en cuenta que su contraseña podría estar cifrada

function WSEditUserCredentials($params)

Edita las credenciales de un usuario (username + password)

function WSEditUsers($params)

Edita varios usuarios en paquete

function WSEditUser($params)

Edita un solo usuario

function WSEditUsersPasswordCrypted($params)

Edita usuarios, enviando contraseñas cifradas

function WSEditUserPasswordCrypted($params)

Edita unu solo usuario, enviando contraseñas cifradas.

Ojo : aunque muy discreto, hay un gran problema en Chamilo LMS 1.9.* ya que WSCreateUserPasswordCrypted espera el nombre de usuario en forma de un campo « loginname », cuando WSEditUserPasswordCrypted espera el nombre de usuario bajo un campo llamado « username ». Asegúrese que no se deje engañar por este, ya que podría tomarle mucho tiempo.

function WSDeleteUsers($params)

Borra usuarios por paquetes

function WSDisableUsers($params)

Desactiva usuarios por paquetes

function WSEnableUsers($params)

Activa usuarios por paquetes

function WSCreateCourse($params)

Crea un curso

function WSCreateCourseByTitle($params)

Crea un curso dando solo un título (en este caso el código del curso se generará automáticamente, lo cual puede ser un inconveniente en casos de estructuración específica)

function WSEditCourse($params)

Edita un curso existente

function WSCourseDescription($params)

Obtiene la descripción de un curso existente

function WSEditCourseDescription($params)

Edita una descripción de curso

function WSDeleteCourse($params)

Borra un curso

function WSCreateSession($params)

Crea una sesión. Este método espera los siguientes parámetros :

$params = array ( 'secret_key' => $finalKey, 'sessions' => array ( 'name' => '', 'year_start' => '', 'month_start' => '', 'day_start' => '', 'year_end' => '', 'month_end' => '', 'day_end' => '', 'nb_days_access_before' => '', 'nb_days_access_after' => '', 'nolimit' => '', //not used in session creation 'user_id' => '', //the coach id 'original_session_id_name' => '', 'original_session_id_value'=> '', 'extra' => '', ));

function WSEditSession($params)

Edita una (o más) sesiones existentes basado en el campo original_session_id_value. Este método espera los siguientes parámetros :

$params = array ( 'secret_key' => $finalKey, 'sessions' => array ( 0 => array ( 'name' => '', 'year_start' => '', 'month_start' => '', 'day_start' => '', 'year_end' => '', 'month_end' => '', 'day_end' => '', 'nb_days_access_before' => '', 'nb_days_access_after' => '', 'original_session_id_name' => '', 'original_session_id_value'=> '', 'coach_username' => '', 'nolimit' => '', 'user_id' => '', //the coach id 'extra' => '', ), ));

function WSDeleteSession($params)

Borra una sesión

function WSSubscribeUserToCourse($params)

Inscribe un usuario en un curso

function WSSubscribeUserToCourseSimple($params)

Inscribe un usuario en un curso

function WSGetUser($params)

Obtiene información sobre un usuario en base a su ID externo

function WSGetUserFromUsername($params)

Obtiene información sobre un usuario en base a su nombre de usuario (login)

function WSUnsubscribeUserFromCourse($params)

Desinscribe un usuario de un curso

function WSSuscribeUsersToSession($params)

NOTA: por favor cuide los errores de teclado aquí: el servicio se llama equivocadamente « suscribe » en vez de « subscribe ». Por razones de compatibilidad ascendiente, lo hemos dejado así, pero no se equivoque: tiene que digitarlo en un inglés incorrecto para que funcione! Inscribe un usuario (alumno) en una sesión. Este método espera los siguientes parámetros :

$params = array ( 'secret_key' => $finalKey, 'userssessions' => array ( 0 => array( 'original_user_id_name' => '', 'original_user_id_value'=> '', 'original_session_id_name' => '', 'original_session_id_value'=> '', ) ));

function WSSubscribeUserToSessionSimple($params)

Desinscribe un usuario de una sesión

function WSUnsuscribeUsersFromSession($params)

NOTA : Ver nota sobre WSSuscribeUsersToSession arriba

Desinscribe varios usuarios de una sesión, por paquetes

function WSSuscribeCoursesToSession($params)

NOTA : Ver nota sobre WSSuscribeUsersToSession arriba

Inscribe varios usuarios a una sesión por paquetes. Este método espera los parámetros siguientes:

$params = array ( 'secret_key' => $finalKey, 'coursessessions' => array ( 0 => array( 'original_course_id_name' => '', 'original_course_id_values' => array( 0 => array ( 'course_code' => '', //external course ID (can be int) ), ), 'original_session_id_name'=> '', 'original_session_id_value'=> '', ) ));

function WSUnsuscribeCoursesFromSession($params)

NOTA : Ver nota en WSSuscribeUsersToSession

Elimina un curso de una sesión

function WSListCourses($params)

Obtiene una lista de cursos disponibles en la plataforma

function WSUpdateUserApiKey($params)

Actualiza la llave API de un usuario

function WSListSessions($params)

Recupera una lista de las sesiones disponibles en la plataforma

Si se sumerge un poco en este tema, encontrará que hemos lanzado el desarrollo de distintos tipos de servicios web en SOAP, pero también en REST y XML-RPC.

No obstante, la versión más activa y mantenida hasta la fecha es SOAP (por ninguna razón en particular) y se concentra principalmente en un archivo: main/webservices/registration.soap.php

No todos los scripts de servicios web en main/webservices/ lo respetan, pero registration.soap.php permite definir restricciones sobre la dirección IP que puede llamar a los servicios web que contiene (esto no ha sido probado con IPv6 todavía).

Esta funcionalidad es posible gracias al pedazo de código siguiente dentro de la función WSHelperVerifyKey()

Como lo habrá entendido, necesita crear un archivo llamado « webservice-auth-ip.conf.php » dentro de la misma carpeta que _registration.soap.php_y añadir una lista de las direcciones IP (o los rangos) dentro del archivo mismo. Solo las direcciones IP que correspondan a los rangos o las IP indicadas serán aceptadas.

Cuando se haga uso de este método, el algoritmo que vimos antes para construir una clave de seguridad deberá ser modificado, ya que dejaremos de necesitar una dirección IP dentro de la clave.

Para los portales en los cuales la seguridad es una preocupación mayor, es una buena idea de usar este método.

Una información básica sobre servicios web en Chamilo LMS puede encontrarse aquí : pero la información que se encuentra ahí podría no estar actualizada (aunque tampoco la de este manual) ya que los servicios tienden a aumentar en cantidad en el tiempo.

Obviamente, hacemos lo posible para mantener compatibilidad ascendiente, pero la fuente más confiable siempre será el código (documentado en sí), que puede encontrarse en la carpeta main/webservices/ de Chamilo.