10.9. Services web

Administration → Extensions → 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.

10.9.1. Configuration

Administration → Extensions → Services web → Configuration

Sur cette page, vous pouvez paramétrer les différents services web que vous activez ou désactivez.

10.9.1.1. Activer les fonctionnalités des services web

Vous pouvez activer globalement les services web et configurer individuellement chaque protocole en fonction de vos besoins. Une fois qu’un protocole est activé, toutes ses fonctions, jetons et utilisateurs, peuvent être utilisés.

Switch web services and individual protocols on and off

Activez les services web puis chacun des protocoles

  1. Permettre les requêtes externes des services web : Si le sélecteur est placé sur « Oui », les services web peuvent effectuer des appels externes à votre site.

  2. Accepter les demande entrantes pour les services web : Si l’option est mise « Oui », les services web peuvent être accédés depuis “extérieur de votre site, par exemple à partir de Mahara Mobile.

  3. SOAP : Activez ce procole si vous désirez pouvoir utiliser les services de Simple Object Access Procol.

  4. XML-RPC : Placez le sélecteur sur « Oui » si vous désirez pouvoir effectuer des accès à du contenu XML distant. Ce protocole est utilisé par MNet.

    Note

    Tant que MNet est supporté par Mahara, vous pouvez l’utiliser pour configurer des échanges de données avec Moodle.

  5. REST: Placez les sélecteur sur « Oui » pour activer le protocole « REpresentational State Transfer protocol ». L’interface REST supporte l’authentification sous JSON.

  6. OAuth: Si vous désirez utiliser OAuth (Open Authentication) protocol, placez le sélecteur 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.

10.9.1.2. Certificats de réseau

Dans cette section, votre certificat de clé publique pour Mahara, créé à partir de Administration → Configurer le site → Réseau, est affiché pour référence.

10.9.1.3. Gérer les groupes de services

Les groupes service sont des unités d’allocation d’accès à un utilisateur unique (authentification simple) ou à jeton-utilisateur. Ils s’agit d’une collection de fonctions. Mahara est livré avec une série de groupes service et de fonctions que vous pouvez configurer.

Overview of the available service groups and their basic settings

Aperçu des groupes de services disponibles et de leurs paramètres de base

  1. Service : Le nom du groupe de services contenant un certain nombre de fonctions que vous pouvez activer ou désactiver.

  2. Composant : Le contexte dans lequel le groupe de services et accessible. Généralement il s’agit de « webservice ».

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. Cliquez sur le bouton Modifier pour effectuer des modifications au groupe de services, comme expliqué ci-dessous.

  8. 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.

  9. 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.

Edit the settings of a service group

Modifier les paramètres d’un groupe de services

  1. Nom : Nom du groupe de services

  2. Nom court : Nom court du service, qui est requis par les applications désirant se connecter à Mahara et accéder au service.

  3. Service : Placez le sélecteur sur « Oui » si vous désirez utiliser ce groupe service. Vous pouvez paramétrer les fonctions individuellement ci-dessous.

  4. Seuls les utilisateurs autorisés : Placez le sélecteur sur « Oui » si vous voulez limiter l’accès à ce groupe service aux utilisateurs authentifiés par leur nom d’utilisateur et leur mot de passe.

  5. Accès par jeton pour l’utilisateur : Placez le sélecteur sur « Oui » si vous désirez que des utilisateurs puissent accéder à ce groupe service seulement s’ils possèdent le bon jeton.

    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.

  6. Le nom de la fonction

  7. Activé : Cette option active ou désactive l’usage de cette fonction.

  8. Nom de la classe : Le nom de la classe qui est membre de la fonction.

  9. 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.

  10. Cliquez sur le bouton Envoyer si vous avez terminé vos modification, ou cliquez sur Retour si vous désirez les annuler.

10.9.1.4. Gérer les jetons du service d’accès

Vous pouvez générer des jetons d’accès pour des utilisateurs individuels et leur associer les groupes de services auxquels vous voulez qu’ils aient accès.

Overview of the access tokens

Aperçu des jetons d’accès

  1. Jeton : Le contenu du jeton qui vient d’être généré pour cet utilisateur en particulier
  2. Institution : Affiche les différentes institutions dans lesquelles cet utilisateur est membre.
  3. Nom d’utilisateur : Le nom d’utilisateur de la personne est affiché et lié à sa page d’administration de ses préférences.
  4. Service : Le groupe de services pour lequel le jeton a été généré.
  5. 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.
  6. 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.
  7. Fonctions : Liste des différentes fonctions que le jeton peut utiliser dans le service sélectionné.
  8. Cliquez sur le bouton Modifier pour modifier les paramètres du jeton.
  9. Cliquez sur le bouton Supprimer pour supprimer le jeton.
  10. Nom d’utilisateur : Entrez le nom d’utilisateur d’un utilisateur auquel vous voulez ajouter un jeton. 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.
  11. Cliquez sur le bouton Générer le jeton pour créer un nouveau jeton pour cet utilisateur. Vous êtes alors dirigé vers un écran où vous pouvez associer un groupe de services au jeton nouvellement créé (voir ci-dessous). Vous ne pouvez entrer qu’un seul nom d’utilisateur à la fois.

Lorsque vous créez un jeton pour un utilisateur, vous devez indiquer des informations supplémentaires.

Configure a service access token

Configurer un accès au service par jeton

  1. Véfifiez que vous êtes bien entrain de modifier le bon jeton.

  2. Institution : Sélectionnez l’institution de l’utilisateur.

  3. Nom d’utilisateur : Vérifiez que vous avez le bon nom d’utilisateur auquel vous désirez ajouter un jeton. Le nom d’utilisateur est lié à page d’administration des préférences utilisateur.

  4. Service : Sélectionnez le groupe de services pour lequel vous voulez ajouter un jeton, depuis la liste déroulante. Seuls les services qui permettent l’accès des utilisateurs par jeton peuvent être sélectionnés.

  5. 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.

  6. 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é.

  7. 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.

  8. 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.

  9. Clé publique : Entrez la clé publique pour ajouter la sécurité des services web (seulement disponible lorsque XML-RPC est utilsé pour l’authentification).

  10. 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.

  11. Cliquez sur le bouton Envoyer si vous avez terminé vos modification, ou cliquez sur Retour si vous désirez les annuler.

10.9.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.

  • ont la méthode d’authentification « webservice » pour l’institution dans laquelle ils sont membres.

    Note

    Les utilisateurs disposant de la méthode d’authentification « webservice » ne peuvent accéder à Mahara qu’à l’aide des services web, mais pas à l’aide du formulaire standard de connexion.

Manage service users overview section

Aperçu de la section de gestion des services des utilisateurs

  1. 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.
  2. Institution : Affiche les différentes institutions dans lesquelles cet utilisateur est membre.
  3. Service : Le groupe service qui est associé à l’utilisateur.
  4. 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.
  5. 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.
  6. Fonctions : La liste des fonctions auxquelles cet utilisateur a accès pour le service sélectionné.
  7. Cliquez sur le bouton Modifier pour modifier les paramètres du jeton.
  8. Cliquez sur le bouton Supprimer pour supprimer cet utilisateur de l’accès au groupe de services associé.
  9. Nom d’utilisateur : Entrez le nom d’utilisateur d’un utilisateur auquel vous voulez ajouter un jeton. 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. L’utilisateur doit avoir les services web comme méthode d’authentification.
  10. Cliquez sur le bouton Générer le jeton pour créer un nouveau jeton pour cet utilisateur. Vous êtes alors dirigé vers un écran où vous pouvez associer un groupe de services au jeton nouvellement créé (voir ci-dessous). Vous ne pouvez entrer qu’un seul nom d’utilisateur à la fois.

Lorsque vous ajoutez un utilisateur, vous devez indiquer des informations supplémentaires.

Associate a user with a specific service group

Associer un utilisateur à un groupe de services particulier

  1. Propriétaire du service : Le nom d’utilisateur est affiché. Il doit correspondre au nom d’utilisateur d’en-dessous.

  2. Institution : Véfifiez que l’institution affichée est la bonne. Sinon, vous pouvez modifier l’institution d’appartenance sur la page des préférences de l’utilisateur.

  3. Nom d’utilisateur : Vérifiez que vous avez le bon nom d’utilisateur associé à ce jeton.

  4. Service : Sélectionnez le groupe de services depuis le menu déroulant auquel vous désirez associer l’utilisateur. Seuls les services qui permettent l’accès par l’utilisateur d’un nom d’utilisateur peuvent être sélectionnés.

  5. 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.

  6. Seuls les utilisateurs autorisés : Ce sélecteur est placés sur « Oui » automatiquement lorsqu le groupe de services est paramétré pour accepter l’accès par non d’utilisateur.

  7. Fonctions : La liste des fonctions que cet utilisateur aura 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.

  8. 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.

  9. Clé publique : Entrez la clé publique pour ajouter la sécurité des services web (seulement disponible lorsque XML-RPC est utilsé pour l’authentification).

  10. 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.

  11. Cliquez sur le bouton Envoyer si vous avez terminé vos modification, ou cliquez sur Retour si vous désirez les annuler.

10.9.2. Connexions vers l’application

Administration → Extensions → Services web → Connexions vers l’application

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.

Overview of the application connections

Aperçu des connexions de l’application

  1. La section Jeton d’accès personnel affiche tous les jetons que vous avez générés pour les utilisateurs individuels ainsi que s’ils ont été utilisés ou non.

  2. Accès au service : Cette colonne affiche le groupe de services pour lesquel le jeton a été créé.

  3. 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.

  4. App client : Affiche la manière dont a été créé le jeton d’accès.

  5. Jeton : Le jeton est affiché ici.

  6. 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.

  7. Dernier accès : Liste la date et l’heure de la dernière utilisation du jeton.

  8. Échéance : Affiche la date d’échéance du jeton.

  9. Cliquez sur le bouton Générer pour générer un nouveau jeton aléatoire.

  10. 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éé.

  11. 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.

10.9.3. Gestionnaire des connexions

Administration → Extensions → 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.

Overview page for the connection manager

Aperçu du gestionnaire de connexions

10.9.4. Enregistrer une app externe

Administration → Extensions → Services Web → Apps externes

new in Mahara 17.04 La page « OAuth » a été déplacée dans « App externes » afin de rendre plus clair ce que vous devez faire à son sujet.

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.

Register an external application

Enregistrer une app externe

  1. Application : Liste des applications qui sont connectées via OAuth.
  2. Propriétaire : Utilisateur qui a configuré le service OAuth.
  3. Clé client : La clé client pour le service OAuth.
  4. Mot de passe : Le mot de passe pour le service OAuth.
  5. 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.
  6. new in Mahara 17.04 Institution : L” institution pour laquelle l’app a été configurée.
  7. Cliquez sur le bouton Modifier pour modifier les paramètres du jeton.
  8. Cliquez sur le bouton Supprimer pour supprimer l’application. Cette application ne pourra alors plus accéder à Mahara par OAuth.
  9. new in Mahara 17.04 Cliquez sur le bouton Paramètres pour fixer les différents paramètres qui sont disponibles.
  10. Application : Indiquez l’application que vous désirez nommer.
  11. Sélectionnez l’institution qui aura accès par OAuth à l’application choisie.
  12. Sélectionnez le groupe de services que vous désirez associer à cette application.
  13. 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).

Lorsque vous désirez qu’une application puisse se connecter à Mahara par OAuth, vous devez entrer des informations supplémentaires.

Configure an OAuth service

Configurer un service OAuth

  1. Clé du serveur : La clé client pour le service OAuth.

  2. Mot de passe : Le mot de passe pour le service OAuth.

  3. Titre de l’application : Indiquez l’application que vous désirez nommer.

  4. Propriétaire du service : Utilisateur qui a configuré le service OAuth.

  5. URI de l’application : URI de l’application.

  6. URI de rapple : L’URI de rappel pour l’application.

  7. Institution : Sélectionnez l’institution pour laquelle vous désirez configurer OAuth.

  8. Service : Sélectionnez le groupe de services pour lequel vous désirez configurer un accès par OAuth.

  9. Activé : L’application est automatiquement activée quand OAuth l’est aussi.

  10. 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.

  11. Cliquez sur le bouton Envoyer si vous avez terminé vos modification, ou cliquez sur Retour si vous désirez les annuler.

10.9.5. Journal du service Web

Administration → Extensions → Services web → Journal 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.

Search the web services logs

Rechercher dans les services web

  1. 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.
  2. Protocole : Sélectionner le protocole du service web associé à un utilisateur. Vous ne voyez que les protocoles que vous avez activés.
  3. Type d’authentification : Sélectionnez le type d’authentification que vous avez activé pour cet utilisateur. Les options sont :
    • Tous : Affiche le journal pour tout type d’authentification.
    • Jeton : N’affiche que le journal des utilisations des jetons liés à l’utilisateur.
    • Utilisateur : N’affiche que le journal des utilisations de services web par nom d’utilisateur.
    • OAuth : Sélectionnez cette option si vous ne désirez afficher que le journal des accès des utilisateurs par OAuth.
  4. Fonction : Permet d’affiche que le journal pour une fonction particulière des services web.
  5. Seulement les erreurs : Placez le sélecteur sur « Oui » si vous ne désirez voir que les informations qui se rapportent à une erreur.
  6. 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.

Results for the search of the web services logs

Résultats de la recherche sur la journalisation des services web

  1. User : Affiche le nom d’utilisateur d’un utilisateur pour lequel il existe des informations de journalisation.
  2. Institution : Affiche le nom de l’institution dans laquelle l’utilisateur est inscrit.
  3. Protocole : Affiche le protocole associé à l’utilisateur dans le contexte choisi.
  4. Type d’authentification Affiche le type d’authentification associé à l’utilisateur.
  5. Fonction : Affiche la fonction pour laquelle il existe des informations de journalisations.
  6. Temps utilisé : Le temps utilisé pour obtenir les informations de journalisation demandées.
  7. Date : Affiche la date à laquelle la journalisation a été effectuée.
  8. Vous pouvez modifier l’ordre de tri pour cette colonne en cliquant sur son en-tête.
  9. Info Les messages d’erreur sont affichés ici.

10.9.6. Client de test pour les services web

Administration → Extensions → Services web → Clients de test pour les 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.

Web services test client

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.

  1. 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.

  2. 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.

  3. Service : Sélectionnez le groupe service que vous désirez utiliser pour le test. Cliquez sur le bouton Suivant pour afficher les options suivantes.

  4. Fonctions : Sélectionnez la fonction que vous désirez utiliser pour le test. Cliquez sur le bouton Suivant pour afficher les options suivantes.

  5. wstocken : Indiquez le jeton des services web pour l’utilisateur que vous désirez tester.

    Note

    Si vous avez sélectionné Utilisateur comme type d’authentification, vous aurez alors aussi la rubrique wspassword que vous pourrez saisir.

  6. 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.