API de Moodle: diseñar un servicio con permisos mínimos

Una integración necesita matricular a estudiantes en los cursos de una convocatoria. Para ponerla en marcha, alguien propone crear una cuenta administradora y entregarle un token. La primera llamada funciona, pero esa prueba deja sin responder qué otras operaciones podría realizar la misma credencial.

El servicio debería permitir completar la matrícula acordada y comprobar su resultado, con un alcance que se pueda explicar. Si una petición cambia el curso, el rol o la función solicitada, el servidor tiene que volver a decidir si está autorizada. El cliente que llama a Moodle no puede ser el único lugar donde se impone ese límite.

El ejemplo es hipotético. La pregunta que interesa es cómo diseñar y aceptar una integración limitada, antes de darle acceso a una plataforma real.

Primero hay que identificar qué API se está utilizando

En Moodle 5.3 conviven los servicios web externos y una nueva API REST con su propio sistema de tokens y alcances. Tampoco es equivalente un cliente OAuth 2 que accede a Moodle a la configuración con la que Moodle se conecta a otro servicio.

Aquí me ocupo de los servicios web externos: un servicio reúne funciones, una identidad obtiene acceso y cada operación debe respetar los permisos correspondientes. Esos servicios pueden utilizar el protocolo REST; eso no los convierte en la nueva API REST. Antes de seguir una guía o reutilizar una credencial hay que identificar la interfaz concreta que admite la operación.

Si la instalación utiliza la nueva API REST, habrá que comprobar sus rutas disponibles, alcances y permisos del usuario. No trasladaría sin más la configuración de un servicio externo, ni supondría que ambas interfaces exponen las mismas funciones.

El servicio, la identidad y el contexto ponen límites distintos

Prepararía una lista de operaciones a partir del proceso: qué necesita crear la integración, qué debe consultar para confirmar el resultado y qué cambios quedan fuera de su responsabilidad. Una función se incorpora por esa necesidad, no porque pueda resultar útil algún día.

Después hay que revisar la identidad que ejecutará las llamadas. Una cuenta técnica permite separar este trabajo de la sesión personal de un administrador, pero su nombre no demuestra que tenga pocos permisos. Importan sus asignaciones efectivas, el acceso al servicio y los contextos donde puede actuar.

Por último, la función debe comprobar los parámetros, el contexto y las capacidades necesarias antes de operar. En una función propia, escribir una lista de capacidades en db/services.php no sustituye esas comprobaciones: ese campo orienta a quien configura el servicio. El código de ejecución tiene que exigir los permisos que correspondan.

Controles distintos del recorrido de un servicio externo. Permitir una función no concede autoridad sobre cualquier curso o rol.

Ver a tamaño originalCerrar

La diferencia se ve al cambiar un solo dato de la petición. Una llamada autorizada para el curso A no debería permitir matricular en el B porque ambos estén en el mismo campus. Tampoco debería admitir un rol más amplio porque el cliente pueda enviar otro identificador.

Una matrícula manual permite comprobar el mecanismo

La función enrol_manual_enrol_users ilustra por qué no basta con que aparezca en un servicio. La implementación de la rama Moodle 5.3 consultada valida el contexto del curso, exige la capacidad de matriculación manual y comprueba que quien llama pueda asignar el rol solicitado. También revisa el usuario de destino y la existencia de una instancia de matriculación manual habilitada.

Por tanto, hay varias razones legítimas para rechazar una petición cuya estructura es correcta. Si falta el método de matriculación esperado, añadir permisos globales a la cuenta técnica no resuelve la configuración del curso. Si el rol no es asignable por esa identidad, el contrato de la integración necesita revisarse antes de ampliar su autoridad.

El identificador del rol también pertenece a la instalación. No conviene convertir un número tomado de un ejemplo en el significado universal de «estudiante». La integración debe relacionar el rol académico acordado con la configuración real y evitar que una entrada externa elija libremente otro.

En esta pieza no propongo sustituir el método que ya gobierna la matrícula. Si el acceso procede de una cohorte o de otro mecanismo, la operación y sus condiciones deben corresponder a ese origen. La reconciliación de matrículas desarrolla cómo comparar registros sin apropiarse de los que mantiene otro proceso.

La aceptación necesita llamadas que deban fallar

Probaría la integración con una identidad de ensayo restringida y datos ficticios. El caso permitido debe producir el resultado esperado; los casos que exceden el contrato deben rechazarse y dejar el estado sin cambios.

El contrato descargable y la matriz de aceptación permiten preparar ese ensayo. Son recursos de diseño: no son una configuración importable ni resultados de una instalación auditada.

En la comprobación real se conserva la petición de prueba sin secretos, el motivo del rechazo y la lectura posterior del estado. Un error en la respuesta es insuficiente si una parte del lote ya cambió antes del fallo. También hay que conocer el alcance de la transacción de la función y de cualquier efecto adicional de la integración.

Reducir la credencial no termina el diseño

El token se guarda del lado del servidor y se retira del código cliente, las capturas y las trazas. Hay que saber quién puede sustituirlo, cómo se revoca y qué operaciones pendientes quedan afectadas. Los límites de red o vigencia, cuando se configuren, complementan los permisos; no sustituyen su comprobación.

Si una pasarela atiende a varios consumidores con una credencial común hacia Moodle, debe resolver qué identidad y alcance representa cada petición. El artículo sobre MCP y Moodle desarrolla ese caso con agentes. El servicio externo limitado sigue siendo necesario, pero no demuestra por sí solo que la pasarela separe correctamente a sus consumidores.

La aceptación termina con una afirmación concreta: esta identidad puede realizar estas operaciones sobre estos cursos, y los intentos de salir de ese alcance se han rechazado sin efectos indebidos. Ese resultado es más útil que comprobar que el token funciona y confiar en que el cliente siempre lo utilizará como estaba previsto.