11.10. Services web¶
Menu d’administration → Services Web
Note
Les services web ne sont accessibles que par les adminsitrateurs.
Les services web vous permettent d’interconnecter votre site Mahara avec d’autres applications qui elles aussi supportent les services web / API. Cela nécessite de configurer vos sites web ou de développer des fonctions de services web spécifiques à ce que vous désirez accomplir. Les services web de Mahara forment un ensemble de fonctionnalités desquelles il est possible de développer de nouvelles fonctionnalités de manière relativement simple. Il suffit la plupart du temps de configurer une nouvelle fonction qui défini les fontionnalités requises en plus de la défnition d’une interface associée.
Afin de pouvoir utiliser les services web, votre site doit posséder un certificat SSL. Lorsque votre site n’est pas en production, vous pouvez tester les services web sans certificat SSL.
11.10.1. Configuration¶
Menu d’administration → Services Web → Configuration
Sur cette page, vous pouvez paramétrer les différents services web que vous activez ou désactivez.
11.10.1.1. Activer les fonctionnalités des services web¶
Vous pouvez activer les services Web de manière globale, puis configurer les protocoles individuellement en fonction de vos besoins. Une fois qu’un protocole est activé, il peut être utilisé pour toutes les fonctions, comptes et jetons.
Activez les services web puis chacun des protocoles¶
Autoriser les demandes de services Web sortants : Si la valeur est « Oui », les services web peuvent être utilisés sur votre site pour les appels sortants.
Accepter les demandes de services web entrants : Si le paramètre est « Oui », les services web sont disponibles pour être utilisés sur votre site pour les appels entrants, par exemple via Mahara Mobile.
SOAP : Activez ce procole si vous désirez pouvoir utiliser les services de Simple Object Access Procol.
XML-RPC : Placez le sélecteur sur « Oui » si vous souhaitez effectuer des appels de procédure à distance vers le contenu XML. Ce protocole est utilisé par le Réseau .
Note
Tant que MNet est supporté par Mahara, vous pouvez l’utiliser pour configurer des échanges de données avec Moodle.
REST : Autorisez le protocole REpresentational State Transfer en mettant ce paramètre sur « Oui ». L’interface REST prend également en charge l’authentification JSON.
OAuth : Si vous souhaitez utiliser le protocole OAuth (Open Authentication), réglez ce paramètre sur « Oui ».
Note
Si vous désactiver les services web, chaque protocole qui était activé sous la rubrique « Protocole » est désactivé. Vous devrez les réactiver manuellement lorsque vous activez à nouveau les services web.
11.10.1.2. Certificats de réseau¶
Dans cette section, la clé publique de votre certicat Mahara qui est créé sur Menu Administration → Configurer le site → Mise en réseau est affichée pour plus de commodité
11.10.1.3. Gérer les groupes de services¶
Les groupes de services sont les unités d’attribution d’accès à un compte (authentification simple) ou à des jetons d’utilisateur. Ils constituent un ensemble de fonctions. Mahara est déjà livré avec une série de groupes de services et de fonctions que vous pouvez configurer. D’autres groupes de services peuvent être ajoutés.
Aperçu des groupes de services disponibles et de leurs paramètres de base¶
Service : Le nom du groupe de services contenant un certain nombre de fonctions que vous pouvez activer ou désactiver.
Composant : Le domaine par lequel un groupe de services est disponible. Il s’agit généralement du « webservice ».
Activé : Si le groupe de services est activé, l’icône Activé est affichée, dans le cas contraire, c’est l’icône Désactivé qui est affichée.
Seuls les utilisateurs autorisés : Si ce groupe de service peut être utilisé par des utilisateurs qui se sont authentifiés sur la plateforme, l’icône Activé est affichée. Si le service ne peut pas être utilisé par un tel utilisateur, c’est alors l’icône Désactivé qui est affichée.
Accès par jeton pour l’utilisateur : Cette option est activée si l’accès aux fonctions de ce groupe nécessite un jeton. Si l’accès par jeton n’est pas autorisé, l’icône Désactivé est alors affichée.
Fonction : Liste des fonctions associées à un groupe de services.
Note
En cliquant sur le nom d’une fonction, on accède à sa documentation. Des informations complémentaires sur la fonction du service web sont disponibles ici en plus de la description de l’API, les paramètres d’entrée et de sortie et la gestion des erreurs.
Cliquez sur le bouton Modifier pour effectuer des modifications au groupe de services, comme expliqué ci-dessous.
Cliquez sur le bouton Supprimer pour complètement supprimer le groupe de services.
Note
Dans la plupart des cas, il n’est pas souhaitable de supprimer un groupe de services, car, si vous désirez l’utiliser ultérieurement, vous aurez à le recréer à la main et y associer toutes les fonctions qui étaient préalablement présentes. Désactiver le groupe de service est souvent suffisant.
Si vous désirez créer un nouveau groupe de services, ajoutez son nom dans cette rubrique et cliquez sur le bouton Ajouter. Vous verrez alors apparaître votre nouveau groupe de services dans la liste et pourrez le configurer en utilisant le button Modifier .
Lorsque vous sélectionnez le groupe de services que vous voulez modifier, vous accédez à l’écran suivant.
Modifier les paramètres d’un groupe de services¶
Nom : Nom du groupe de services
Nom court : Nom court du service, qui est requis par les applications désirant se connecter à Mahara et accéder au service.
Service : Mettez ce commutateur sur “Oui” si vous voulez utiliser ce groupe de services. Vous pouvez modifier les fonctions individuelles ci-dessous.
Utilisateurs autorisés uniquement : Placez le sélecteur sur « Oui » si seules les personnes possédant un nom d’utilisateur et un mot de passe doivent être affectées par ce groupe de services. .
Accès aux jetons d’utilisateur : Placez le sélecteur sur « Oui » si vous voulez que les utilisateurs aient des jetons individuels pour accéder à certaines fonctionnalités.
Note
L’accès par jeton permet à tout utilisateur présent dans la base de données des utilisateurs d’accéder à l’API. Toutefois et généralement, ce système d’accès par jeton ne devrait être utilisé qu’avec les groupes de services qui ne donnent accès qu’au contenu du portfolio des utilisateurs, avec des fonctions comme mahara_user_get_my_user avec comme référence l’utilisateur courant.
Le nom de la fonction
Activé : Cette option active ou désactive l’usage de cette fonction.
Nom de la classe : Le nom de la classe qui est membre de la fonction.
Nom de la méthode : Le nom de la méthode qui est appelée par l’API. Le lien sur le nom de chaque méthode vous permet d’afficher la documentation concernant cette méthode.
Cliquez sur le bouton Envoyer si vous avez terminé vos modification, ou cliquez sur Retour si vous désirez les annuler.
11.10.1.4. Gérer les jetons du service d’accès¶
Vous pouvez générer des jetons d’accès pour des comptes individuels et associer des groupes de services auxquels ce compte aura accès.
Aperçu des jetons d’accès¶
Token : Le jeton qui a été généré pour un compte particulier.
Institution : Liste l’institution à laquelle le compte appartient.
Nom d’utilisateur : Le nom d’utilisateur de la personne est affiché et lié à sa page d’administration de ses préférences.
Service : Le groupe de services pour lequel le jeton a été généré.
Activé : Si ce groupe de services est activé, l’icône Activé est affichée. Dans le cas contraire, c’est l’icône Désactivé qui est affichée à la place.
Sécurité des services web : Si la sécurité est activée, l’icône Activé est affichée, sinon c’est l’icône Déactivé qui est affichée à la place.
Fonctions : Liste des différentes fonctions que le jeton peut utiliser dans le service sélectionné.
Cliquez sur le bouton Modifier pour modifier les paramètres du jeton.
Cliquez sur le bouton Supprimer pour supprimer le jeton.
Nom d’utilisateur : Tapez un nom d’utilisateur pour lequel vous souhaitez ajouter un jeton. Vous pouvez commencer à taper le nom ou le nom d’utilisateur d’une personne enregistrée sur votre site. Vous recevrez des suggestions de noms au fur et à mesure de votre saisie.
Cliquez sur le bouton Générer un jeton pour qu’un nouveau jeton d’accès soit créé pour ce compte. Vous accédez à un écran où vous pouvez associer un groupe de services à ce jeton (voir ci-dessous). Vous ne pouvez saisir qu’un seul nom d’utilisateur.
Lorsque vous créez un jeton, vous devez fournir quelques informations supplémentaires.
Configurer un accès au service par jeton¶
Véfifiez que vous êtes bien entrain de modifier le bon jeton.
Institution : Sélectionnez l’institution à laquelle le compte appartient.
Nom d’utilisateur : Vérifiez que vous avez le bon nom d’utilisateur pour lequel vous voulez configurer un jeton. Le nom d’utilisateur est lié à la page des paramètres de la personne dans l’administration.
Service : Choisissez dans la liste déroulante le groupe de services pour lequel vous souhaitez activer le jeton. Seuls les services qui autorisent l’accès au jeton peuvent être choisis.
Activé : Le jeton est automatiquement activé quand le groupe de services l’est aussi.
Note
Si vous désirez désactiver un groupe de services, veuillez vous rendre dans la section Gérer les groupes de services.
Seuls les utilisateurs autorisés : Ce sélecteur n’est pas utilisé dans ce contexte car ici vous créez un jeton. C’est pourquoi il a été désactivé.
Fonctions : La liste des fonctions que le jeton permet d’accéder.
Note
Lorsque vous modifiez le service, la liste des fonctions n’est pas automatiquement mise à jour. La mise à jour n’est visible qu’après avoir enregistré la page.
Activer la sécurité des WS (XML-RPC seulement) : Cette fonction de sécurité des services web n’est disponible que pour les authentifications avec XML-RPC.
Clé publique : Entrez la clé publique pour ajouter la sécurité des services web (seulement disponible lorsque XML-RPC est utilsé pour l’authentification).
Date d’échéance de la clé publique : Date à laquelle la clé publique que vous avez entrée échoit. Cette valeur est mise à jour au moment où vous enregistrez le formulaire.
Cliquez sur le bouton Envoyer si vous avez terminé vos modification, ou cliquez sur Retour si vous désirez les annuler.
11.10.1.5. Gérer les utilisateurs dans le service¶
Si vous ne désirez pas utiliser les jetons pour donner accès aux services web à vos utilisateurs, vous pouvez leur donner accès aux fonctions par leur nom d’utilisateur. Cette manière de faire est d’ailleurs plus recommandée que la première. Les utilisateurs doivent :
peuvent n’être configurés qu’une seule fois.
disposent de la méthode d’authentification « webservice » dans une institution dont ils sont membres.
Note
Les comptes avec la méthode d’authentification « webservice » ne peuvent accéder à Mahara que via des services web et ne peuvent pas utiliser le formulaire de connexion standard.
Aperçu de la section de gestion des services des utilisateurs¶
Utilisateur : Le nom d’utilisateur de la personne à laquelle vous voulez donner l’accès un groupe de services apparaît ici. Son nom est lié à sa page d’administration des préférences.
Institution : Liste l’institution à laquelle le compte appartient.
Service : Le groupe de services qui est associé au compte.
Activé : Si ce groupe de services est activé, l’icône Activé est affichée. Dans le cas contraire, c’est l’icône Désactivé qui est affichée à la place.
Sécurité des services web : Si la sécurité est activée, l’icône Activé est affichée, sinon c’est l’icône Déactivé qui est affichée à la place.
Fonctions : La liste des fonctions auxquelles cet utilisateur a accès pour le service sélectionné.
Cliquez sur le bouton Modifier pour modifier les paramètres du jeton.
Cliquez sur le bouton Supprimer pour supprimer le compte de l’accès au groupe de services associé.
Nom d’utilisateur : Saisissez un nom d’utilisateur pour lequel vous souhaitez gérer les services. Vous pouvez commencer à taper le nom ou le nom d’utilisateur d’une personne inscrite sur votre site. Vous recevrez des suggestions de noms au fur et à mesure de votre saisie. Le compte doit avoir des services web comme méthode d’authentification.
Cliquez sur le bouton Générer un jeton pour qu’un nouveau jeton d’accès soit créé pour ce compte. Vous accédez à un écran où vous pouvez associer un groupe de services à ce jeton (voir ci-dessous). Vous ne pouvez saisir qu’un seul nom d’utilisateur.
Lorsque vous ajoutez un compte, vous devez fournir quelques informations supplémentaires.
Associer un utilisateur à un groupe de services particulier¶
Propriétaire du service : Le nom d’utilisateur est affiché. Il doit correspondre au nom d’utilisateur d’en-dessous.
Institution : Vérifiez que l’institution associée au compte est correcte. Si ce n’est pas le cas, vous pouvez modifier l’institution sur la page Paramètres du compte.
Nom d’utilisateur : Vérifiez que vous avez le bon nom d’utilisateur associé à ce jeton.
Service : Choisissez dans le menu déroulant le groupe de services auquel vous voulez donner accès à la personne. Seuls les services qui permettent l’accès via un nom d’utilisateur peuvent être choisis. .
Activé : Cette option est automatiquement activée lorsque le groupe de services l’est aussi.
Note
Si vous désirez désactiver un groupe de services, veuillez vous rendre dans la section Gérer les groupes de services.
Utilisateurs autorisés uniquement : Ce commutateur est automatiquement réglé sur « Oui » lorsque le groupe de services est configuré pour permettre l’accès via un nom d’utilisateur.
Fonctions : Une liste de fonctions auxquelles le compte a accès.
Note
Lorsque vous modifiez le service, la liste des fonctions n’est pas automatiquement mise à jour. La mise à jour n’est visible qu’après avoir enregistré la page.
Activer la sécurité des WS (XML-RPC seulement) : Cette fonction de sécurité des services web n’est disponible que pour les authentifications avec XML-RPC.
Clé publique : Entrez la clé publique pour ajouter la sécurité des services web (seulement disponible lorsque XML-RPC est utilsé pour l’authentification).
Date d’échéance de la clé publique : Date à laquelle la clé publique que vous avez entrée échoit. Cette valeur est mise à jour au moment où vous enregistrez le formulaire.
Cliquez sur le bouton Envoyer si vous avez terminé vos modification, ou cliquez sur Retour si vous désirez les annuler.
11.10.2. Connexions vers l’application¶
Menu d’administration → Services Web → Connexions d’applications
Il s’agit d’un aperçu des toutes les connexions que vous avez autorisées via un jeton d’utilisateur ou par jeton d’accès OAuth.
Aperçu des connexions de l’application¶
La section Jetons d’utilisateur personnel affiche tous les jetons que vous avez générés pour des individus et indique, entre autres, s’ils ont été accédés ou non.
Accès au service : Cette colonne affiche le groupe de services pour lesquel le jeton a été créé.
Activé : Si le groupe de services est activé, l’icône Activé est affichée, sinon c’est l’icône Désactivé qui l’est à la place.
App client : Affiche la manière dont a été créé le jeton d’accès.
Jeton : Le jeton est affiché ici.
Fonctions : Les fonctions qui font partie d’un groupe de services sont affichées et liées à la définition des fonctions. Le lien permet de se rendre vers la documentation concernant la fonction sélectionnée.
Dernier accès : Liste la date et l’heure de la dernière utilisation du jeton.
Échéance : Affiche la date d’échéance du jeton.
Cliquez sur le bouton Générer pour générer un nouveau jeton aléatoire.
Cliquez sur le bouton Supprimer pour supprimer le jeton. Le groupe utilisateur et les fonctions restent disponibles. Vous pouvez alors cliquer sur Générer pour recréer un nouveau jeton.
Note
Le bouton Supprimer n’est disponible que lorsqu’un jeton a été créé.
Dans la section Jeton d’accès pour OAuth vous pouvez voir l’ensemble des jetons générés pour être utilisés avec OAuth.
11.10.3. Gestionnaire des connexions¶
Menu Administration → Services Web → Gestionnaire de connexion
Le gestionnaire de connexion facilite l’utilisation des services web en rendant plus facile le paramétrage des connexions.
Pour plus d’information sur ce sujet, veuillez vous rendre sur le wiki (idée de base) et sur la base de demandes de nouvelles fonctionnalités.
Aperçu du gestionnaire de connexions¶
11.10.4. Enregistrer une app externe¶
Menu d’administration → Services Web → Applications externes
Vous pouvez utiliser cette page pour enregistrer les apps externes qui sont connectées via OAuth. Un exemple est le service LTI (Learning Tool Interoperability). Vous pouvez activer les outils externes pour certaines institutions et autres définitions de services, pour lesquelles un utilisateur recevra une clé et une phrase secrète qui seront générées automatiquement.
Enregistrer une app externe¶
Application : Liste des applications qui sont connectées via OAuth.
Propriétaire : La personne qui a configuré le service OAuth.
Clé client : La clé client pour le service OAuth.
Mot de passe : Le mot de passe pour le service OAuth.
Activé : Si l’application est activée, l’icône Activé est affichée, sinon c’est l’icône Désactivé qui l’est à la place.
Institution : L’institution pour laquelle l’application externe a été créée.
Cliquez sur le bouton Modifier pour modifier les paramètres du jeton.
Cliquez sur le bouton Supprimer pour supprimer l’application. Cette application ne pourra alors plus accéder à Mahara par OAuth.
Cliquez sur le bouton Gérer pour décider d’autres paramètres lorsqu’ils sont disponibles.
Application : Indiquez l’application que vous désirez nommer.
Sélectionnez l’institution qui aura accès par OAuth à l’application choisie.
Sélectionnez le groupe de services que vous désirez associer à cette application.
Cliquez sur le bouton Ajouter pour créer l’authentification par OAuth pour le service sélectionné. Vous être alors redirigé vers un écran où vous pouvez configurer votre application (voir ci-dessous).
Vous pouvez voir les détails de la connexion que vous êtes en train de mettre en place en cliquant sur le bouton Modifier .
Configurer un service OAuth¶
Clé du consommateur : La clé du consommateur pour le service externe.
Secret du consommateur : Le secret du consommateur pour le service externe.
Titre de l’application : Vous pouvez modifier le titre de l’application.
Propriétaire du service : Personne qui a mis en place le service externe.
Vous pouvez changer le propriétaire du service afin qu’il ne soit pas tout lié à un administrateur de site. C’est pratique lorsque vous voulez mettre en place un compte spécifique qui gère tous les appels aux services web.Application URI : URI de l’application. S’il n’est pas nécessaire, il est ignoré.
Rappel URI : L’URI de rappel pour l’application. S’il n’est pas nécessaire, il est ignoré.
Institution : Sélectionnez l’institution pour laquelle vous souhaitez configurer le service externe.
Service : Sélectionnez le groupe de services que vous souhaitez configurer.
Activé : L’application est automatiquement activée quand OAuth l’est aussi.
Fonctions : Liste des fonctions auxquelles l’application a accès.
Note
Lorsque vous modifiez le service, la liste des fonctions n’est pas mise à jour automatiquement. Vous ne verrez les modifications qu’après avoir enregistré la page.
Cliquez sur le bouton Envoyer si vous avez terminé vos modification, ou cliquez sur Retour si vous désirez les annuler.
11.10.5. Journal du service Web¶
Menu Administration → Services Web → Journaux des services Web
Vous pouvez afficher le journal pour l’ensemble des services web puis restreindre l’affichage en effectuant des recherches sur les éléments qui vous intéressent.
Rechercher dans les services web¶
User : Entrez le no d’utilisateur d’une personne pour laquelle vous désirez afficher le journal des services web. Vous pouvez entrer qu’un seul nom d’utilisateur. Vous pouvez soit commencer à taper le nom ou le nom d’utilisateur d’une personne enregistrée sur votre site. Au fur et à mesure de la saisie vous recevrez une liste de suggestion de laquelle vous pouvez directement cliquer sur le nom que vous recherchez.
Protocole : Sélectionnez le protocole de services Web qui est associé au compte. Vous ne pouvez voir que les protocoles qui sont activés.
Type d’authentification : Choisissez le type d’authentification que vous avez sélectionné pour le compte. Les options sont :
Tous : Affiche le journal pour tout type d’authentification.
Jeton : Afficher uniquement les journaux lorsque le compte possède un jeton d’utilisateur.
User : Affiche les logs lorsque le compte utilise le nom d’utilisateur pour le service web.
OAuth : Sélectionnez cette option si vous souhaitez uniquement voir les journaux lorsque la personne se connecte via OAuth.
Fonction : Permet d’affiche que le journal pour une fonction particulière des services web.
Uniquement les erreurs : Placez le sélecteur sur « Oui » si vous voulez seulement voir les informations du journal qui contiennent une erreur.
Cliquez sur le bouton Aller pour lancer votre recherche.
Si votre recherche a des résultats, ils seront affichés dans la zone Résultats.
Résultats de la recherche sur la journalisation des services web¶
Utilisateur : Affiche le nom d’utilisateur du compte pour lequel il y a une entrée de journal.
Institution : Affiche le nom de l’institution à laquelle appartient le compte.
Protocole : Affiche le protocole qui est associé au compte pour le contexte choisi.
Type d’authentification : Affiche le type d’authentification qui est associé au compte.
Fonction : Affiche la fonction pour laquelle il existe des informations de journalisations.
Temps utilisé : Le temps utilisé pour obtenir les informations de journalisation demandées.
Date : Affiche la date à laquelle la journalisation a été effectuée.
Vous pouvez modifier l’ordre de tri pour cette colonne en cliquant sur son en-tête.
Info Les messages d’erreur sont affichés ici.
11.10.6. Client de test pour les services web¶
Menu Administration → Services Web → Client de test des services Web
Le client de test vous permet de tester votre configuration des services web. Soyez attentif au fait que les fonctions exécutées le sont pour de vrai sur le système.
Client de test pour les services web¶
Note
Lorsque vous débutez la configuration, vous ne voyez que le protocole et le type d’authentification, si vous n’avez qu’un seul protocole sélectionné. Les autres rubriques ne sont affichées qu’après que vous ayez décidé ce que vous désirez tester.
Protocole : Vous ne voyez que les protocoles des services web que vous avez activés. Si vous voyez plus d’un protocole, sélectionnez celui que vous désirez tester.
Type d’authentification : Sélectionnez le type d’authentification que vous désirez inclure dans votre test. Cliquez sur le bouton Suivant pour afficher les options suivantes.
Service : Sélectionnez le groupe service que vous désirez utiliser pour le test. Cliquez sur le bouton Suivant pour afficher les options suivantes.
Fonctions : Sélectionnez la fonction que vous désirez utiliser pour le test. Cliquez sur le bouton Suivant pour afficher les options suivantes.
wstoken : Entrez le jeton de services Web pour le compte que vous voulez tester.
Note
Si vous avez sélectionné « Utilisateur » comme type d’authentification, vous verrez également un champ wspassword que vous pouvez remplir.
Cliquez sur le bouton Exécuter si vous désirez lancer le test, ou cliquez sur Annuler si vous désirez interrompre la procédure.
Une fois que le test a été effectué, les résultats sont affichés à l’écran.