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

Pour pouvoir utiliser les services web, votre site doit utiliser un certificat SSL.

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

9.7.1.1. Le button d’activation général, activant ou désactivant tous les 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.

Activer ou désactiver individuellement chaque service web ou protocole

1. Activation ou désactivation de TOUS les services Web : Si cette option est activée, les services web peuvent être utilisés sur votre site.

   Note

   Si vous désactivez l’interrupteur principal, tous les protocoles préalablement et individuellement activés seront désactivés et vous devrez les réactiver un à une ultérieurement.

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

3. XML-RPC : Activez ce protocole si vous désirez pouvoir effectuer des appels à 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.

4. REST : Activez le protocole REpresentational State Transfer en sélectionnant cette option. L’interface REST permet aussi l’authentification JSON.

5. OAuth : Si vous désirez utiliser le protocole OAuth (Open Authentication), activez cette option.

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

9.7.1.3. Gérer les groupes de services

Les groupes de services sont des unités d’allocation d’accès attribuées à un utilisateur (authentification basique) ou à un jeton. Elles correspondent à une collection de fonctions. Mahara propose en standard une série de groupe de services et fonctions que vous pouvez configurer. D’autres services peuvent ensuite être ajoutés par vos soins.

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.

Modifier les paramètres d’un groupe de services

1. Service : Activez cette option si vous désirez utiliser ce service dans le groupe de services. Vous pouvez alors ajouter ou non les fonctions qui sont listées plus bas.

2. Seuls les utilisateurs autorisés : Activez cette option si vous voulez limiter l’accès à ce groupe de services aux utilisateurs authentifiés par leur nom d’utilisateur et leur mot de passe.

3. Accès par jeton pour l’utilisateur : Activez cette option si vous désirez que des utilisateurs puissent accéder à ce groupe de services 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.

4. Le nom de la fonction

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

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

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

8. Cliquez sur le bouton Enregistrer pour valider les paramètres que vous avez modifiés, ou cliquez sur le bouton Retour pour annuler vos modifications.

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

Aperçu des jetons d’accès

1. Nom d’utilisateur : Entrez ici le nom d’utilisateur auquel vous désirez ajouter un jeton d’accès, puis 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.

   Note

   Vous pouvez commencer à entrer soit le nom ou le nom d’utilisateur d’une personne enregistrée sur votre site. Au fur et à mesure de la saisie, des propositions vous sont faites dans une liste déroulante.

2. Jeton : Le contenu du jeton qui vient d’être généré pour cet utilisateur en particulier

3. Institution : Affiche les différentes institutions dans lesquelles cet utilisateur est membre.

4. Nom d’utilisateur : Le nom d’utilisateur de la personne est affiché et lié à sa page d’administration de ses préférences.

5. Service : Le groupe de services pour lequel le jeton a été généré.

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

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

8. Fonctions : Liste des différentes fonctions que le jeton peut utiliser dans le service sélectionné.

9. Cliquez sur le bouton Modifier pour modifier les paramètres du jeton.

10. Cliquez sur le bouton Supprimer pour supprimer le jeton.

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

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 associé à ce jeton.

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 : Cette boîte à cocher n’est pas active, car dans ce contexte, car ici vous créez un jeton.

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 Enregistrer pour enregistrer vos modifications ou sur le bouton Retour pour les annuler.

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

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

1. Nom d’utilisateur : Entrez un nom d’utilisateur et cliquez sur le bouton Ajouter. Vous êtes alors redirigé vers un écran vous permettant d’associer un groupe de services à cet utilisateur (voir ci-dessous). Vous pouvez entrer qu’un seul utilisateur à la fois.

   Note

   Vous pouvez commencer à entrer soit le nom ou le nom d’utilisateur d’une personne enregistrée sur votre site. Au fur et à mesure de la saisie, des propositions vous sont faites dans une liste déroulante.

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

3. Institution : Affiche les différentes institutions dans lesquelles cet utilisateur est membre.

4. Service : Le groupe de services qui est associé à cet utilisateur.

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 : La liste des fonctions auxquelles cet utilisateur a accès pour 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 cet utilisateur de l’accès au groupe de services associé.

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

Associer un utilisateur à un groupe de services particulier

1. Le nom d’utilisateur est affiché.

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 : Cette boîte à cocher est activée automatiquement quand le groupe de service est configuré pour donner l’accès par le nom 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 Enregistrer pour enregistrer vos modifications ou sur le bouton Retour pour les annuler.

9.7.2. Enregistrement d’un service OAuth

Administration → Extensions → Services web → OAuth

L’accès par service OAuth doit être configuré séparément. Cette fonction permet, dans une institution et une définition de service, de sélectionner l’utilisateur pour lequel une clé et un mot de passe seront générés automatiquement.

Enregistrer un service OAuth

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

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

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 Enregistrer pour enregistrer vos modifications ou sur le bouton Retour pour les annuler.

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

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 soit son nom ou son nom d’utilisateur.

   Note

   Vous pouvez commencer à entrer soit le nom ou le nom d’utilisateur d’une personne enregistrée sur votre site. Au fur et à mesure de la saisie, des propositions vous sont faites dans une liste déroulante.

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. N’afficher que les erreurs : Sélectionnez cette option si vous ne désirez afficher que le journal des erreurs rencontrées par les services web.

6. Cliquez sur le bouton Aller pour lancer votre recherche.

7. Utilisateur : Affiche le nom d’utilisateur pour lequel vous avez fait la recherche.

8. Institution : Affiche le nom de l’institution dans laquelle l’utilisateur est inscrit.

9. Protocole : Affiche le protocole associé à l’utilisateur dans le contexte choisi.

10. Type d’authentification Affiche le type d’authentification associé à l’utilisateur.

11. Fonction : Affiche la focntion que vous avez recherchée

12. Temps utilisé : Le temps utilisé pour créer le journal demandé.

13. Date : Affiche la date à laquelle le journal a été produit. Vous pouvez modifier l’ordre de tri pour cette colonne.

14. Info Les messages d’erreur sont affichés ici.

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

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.
3. Service : Sélectionnez le groupe de services que vous désirez tester.
4. Fonctions : Sélectionnez la fonction que vous désirez inclure dans votre test.
5. wstocken : Indiquez le jeton des services web pour l’utilisateur que vous désirez tester.
6. Cliquez sur le bouton Éxécuter si vous voulez lancer le test, sinon cliquez sur le bouton Annuler pour annuler la configuration du test.

Une fois que le test a été effectué, les résultats sont affichés à l’écran.

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

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. Jeton : Le jeton est affiché ici.
5. 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.
6. Dernier accès : Liste la date et l’heure de la dernière fois que le jeton a été utilisé.
7. Expiration : Affiche la date à laquelle expire le jeton.
8. Cliquez sur le bouton Générer pour créer un nouveau jeton contenant une combinaison aélatoire.
9. Cliquez sur le bouton Suprimer pour supprimer le jeton. Le groupe et les fonctions liées à l’utilisateur restent disponibles. Vous pouvez cliquer sur le bouton Générer pour créer un nouveau jeton.
10. 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.