Travail avec l'API du serveur

Vous pouvez étendre les fonctionnalités de TrueConf Server en utilisant l'API RESTful, disponible dans toutes les versions, y compris la version gratuite.

Principes de fonctionnement de l'API et OAuth 2.0

La section API → OAuth2 est conçue pour gérer les applications ou services utilisant l'API TrueConf Server. La gestion des accès est effectuée conformément au protocole d'autorisation OAuth 2.0, dont vous pouvez lire plus en détail dans la documentation officielle du RFC 6749, ainsi que dans l'encadré ci-dessous.

L'idée principale du protocole OAuth 2.0 est d'accorder des droits d'accès à l'API à des applications spécifiques (client dans la terminologie OAuth) avec un champ d'application et des droits limités. Cette approche permet de révoquer à tout moment l'accès d'une application ou d'un utilisateur spécifique aux ressources du serveur. Le protocole permet également d'autoriser en toute sécurité des applications tierces et d'effectuer des actions sur le serveur via l'API au nom de l'utilisateur. Ainsi, l'utilisateur n'a pas besoin de fournir son identifiant ou son mot de passe à l'application tierce (méthode Authorization Code).

Chaque application tierce doit obtenir un jeton d'accès (access token) suite au processus d'autorisation sur TrueConf Server via le protocole OAuth 2.0. Les applications disposant d'un jeton d'accès valide peuvent à tout moment accéder à l'API de TrueConf Server, dont la liste des appels est décrite dans la documentation. À travers cette section du panneau de contrôle, l'administrateur TrueConf Server a non seulement le contrôle sur les accès des applications tierces, mais également sur les jetons obtenus via ces applications.

Des exemples d'utilisation de l'TrueConfAPI sont présentés sur notre blog.

Après l'autorisation, l'application reçoit un jeton d'accès (access token) avec une durée de vie limitée et une portée soit serveur soit utilisateur. Par exemple, la portée serveur permet d'accéder aux données de toutes les conférences, tandis que la portée utilisateur se limite aux conférences où l'utilisateur est participant ou propriétaire. La portée est déterminée par le type d'autorisation choisi par le développeur de l'application tierce, tandis que l'ensemble des droits d'accès aux ressources du serveur est défini par l'administrateur du serveur.

Chaque demande de création d'une clé d'accès nécessite la spécification de l'ID de l'application (Application ID) et du secret de l'application (Secret), que vous pouvez obtenir et mettre à jour en créant ou en modifiant l'application dans cette section. L'ID de l'application est généré automatiquement et ne peut pas être modifié par la suite, contrairement au secret de l'application, qui peut être régénéré.

Méthode d'autorisation OAuth 2.0	Portée de la clé d'accès	Résultat de l'autorisation
Client Credentials L'application obtient une clé d'accès dont la portée n'est pas limitée par les données d'un utilisateur spécifique. Aucune autorisation de l'utilisateur n'est requise. Il est recommandé de l'utiliser uniquement pour les applications de confiance.	Non limitée.	Un jeton d'accès (access token) est délivré avec une durée de vie de 1 heure.
Identifiants de l'utilisateur (également appelé Resource Owner Password Credentials Grant) Pour obtenir la clé d'accès, vous devez transmettre le nom d'utilisateur et le mot de passe obtenus du côté de l'application.	Limitée à la zone de visibilité de l'utilisateur autorisé.	Une clé d'accès est délivrée pour 1 heure, ainsi qu'une clé de renouvellement (refresh token) pour 7 jours.
Code d'autorisation Un jeton d'accès (access token) est délivré après l'autorisation autonome de l'utilisateur sur le côté. Le login et le mot de passe de l'utilisateur ne sont pas accessibles à l'application.	Limitée à la zone de visibilité de l'utilisateur autorisé.	Une clé d'accès est émise pour 1 heure, ainsi qu'une clé de prolongation d'accès pour 7 jours.
Refresh Token Cette méthode d'autorisation permet d'obtenir un nouveau jeton d'accès (access token) sur la base d'un jeton de rafraîchissement existant (refresh token).	Elle est limitée au domaine de visibilité de l'utilisateur auquel la clé de prolongation d'accès a été délivrée.	Une nouvelle clé d'accès est émise pour une durée d'une heure. Il n'est pas possible de la renouveler avec cette méthode.

Description des autorisations

Les fonctionnalités d'une application tierce utilisant l'API dépendent des autorisations qui lui ont été accordées.

La liste des autorisations s'allonge à chaque version de l'API avec l'augmentation des fonctionnalités du serveur de visioconférence. Vous pouvez consulter la liste de correspondance entre l'API et la version du serveur dans la documentation de l'API.

La documentation de l'API TrueConf Server indique pour chaque méthode l'ensemble des autorisations nécessaires pour l'appeler avec succès.

Si une application OAuth nécessite un accès en lecture et en écriture à un certain paramètre, au lieu de spécifier les permissions <permission>:read et <permission>:write, vous pouvez indiquer la permission générale <permission> si celle-ci est disponible. Par exemple, pour que l'application puisse lire et modifier les comptes utilisateurs du serveur, au lieu de cocher les deux cases users:read et users:write, vous pouvez simplement indiquer users.

Formulaire de création d'une nouvelle application OAuth 2.0

Pour ajouter une application OAuth 2.0 :

1. Cliquez sur Create a new application.

2. Indiquez son identifiant dans le champ Name. Il est utilisé uniquement pour l'affichage dans la liste des applications.

3. Pour l'autorisation via la méthode Authorization Code, spécifiez dans le champ Redirect URL l'URL vers laquelle l'application sera redirigée. Pour les autres méthodes d'autorisation, vous pouvez utiliser l'adresse https://localhost/.

4. Dans la liste Permissions, cochez les autorisations nécessaires pour votre application.

5. Sauvegardez les modifications en utilisant le bouton Create.

Page d'édition de l'application

Sur la page de l'application, en plus de modifier ses propriétés, vous pouvez également voir la liste des clés d'accès qui ont été obtenues par les utilisateurs de cette application. Vous pouvez à tout moment supprimer les clés d'accès pour des utilisateurs spécifiques, les empêchant ainsi d'accéder aux ressources du serveur via l'API.

Vous pouvez également Regenerate le secret de l'application, ce qui peut être utile pour des raisons de sécurité afin de révoquer l'accès au serveur pour cette application ainsi que pour tous ses nouveaux utilisateurs. Veuillez noter que les clés d'accès et de renouvellement d'accès obtenues avec l'ancien secret continueront de fonctionner jusqu'à la fin de leur durée de vie.

Documentation API intégrée

La documentation intégrée relative à l'API v4 est disponible à partir de la version 5.5.3 du serveur.

Votre installation de serveur comprend déjà une documentation intégrée pour faciliter le travail avec l'API (tout comme pour cette documentation administrateur). Vos développeurs n'auront pas besoin de chercher des instructions sur Internet, et ils pourront créer des scripts et des applications en utilisant l'API TrueConf Server même en travaillant dans un réseau fermé (CSPD).

La documentation intégrée de l'API est disponible via le lien :

https://[server-address]/api/v4/docs/

où [server-address] est l'adresse IP ou le FQDN de votre serveur.

La documentation intégrée prend en charge le mode test pour toute requête. Pour ce faire :

1. Générez un jeton pour l'application OAuth 2.0 avec les droits nécessaires (ou utilisez un jeton de la section Web → Security à des fins de test).

2. Indiquez le jeton dans la section Introduction du bloc Bearer Token :

   

3. Désormais, ce jeton sera mémorisé pendant la session de cette page dans le navigateur et vous pouvez effectuer n'importe quelle requête en appuyant sur le bouton Test Request :

   

4. De plus, le jeton du point 1 sera mémorisé pour toutes les requêtes si vous le spécifiez dans n'importe quelle requête avant de l'envoyer :

   

Lors du changement de langue de la page ou de son actualisation, le jeton API spécifié pour les tests sera oublié et devra être saisi à nouveau. Cela est fait pour des raisons de sécurité, le jeton n'est pas mémorisé dans les cookies.