# Utilisation de l'API du serveur
Vous pouvez étendre les fonctionnalités de TrueConf Server grâce à l'API RESTful, disponible dans toutes les versions, y compris la version gratuite.
# Principes de fonctionnement de l'API et d'OAuth 2.0
La section API → OAuth2 est destinée à la gestion des applications ou services utilisant l'API TrueConf Server. La gestion de l'accès s'effectue conformément au protocole d'autorisation OAuth 2.0, que vous pouvez découvrir plus en détail dans la documentation officielle RFC 6749 (opens new window), 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 à la suite du processus d'autorisation sur TrueConf Server via le protocole OAuth 2.0. Les applications disposant d'un jeton d'accès valide peuvent accéder à tout moment à l'API de TrueConf Server, dont la liste des appels est décrite dans la documentation. Dans cette section du panneau de contrôle, l'administrateur de TrueConf Server a le contrôle non seulement sur les accès des applications tierces, mais aussi sur les jetons obtenus via ces applications.
Des exemples de l'utilisation de l'API de TrueConf 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.
| 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 aux données d'un utilisateur spécifique. Aucune autorisation de l'utilisateur n'est requise. Recommandé uniquement pour les applications de confiance. | Non limitée. | Une clé d'accès (access token) est délivrée avec une durée de vie de 1 heure. |
| User Credentials (également connu sous le nom de Resource Owner Password Credentials Grant)
Pour obtenir une clé d'accès, il est nécessaire de transmettre le login et le mot de passe de l'utilisateur, obtenus du côté de l'application. | Limitée à la portée de l'utilisateur autorisé. | Une clé d'accès est délivrée pour 1 heure, ainsi qu'un jeton de renouvellement (refresh token) pour 7 jours. |
| Authorization Code La clé d'accès (access token) est délivrée après l'autorisation autonome de l'utilisateur du côté de TrueConf Server. Le login et le mot de passe de l'utilisateur ne sont pas accessibles à l'application. | Limitée à la portée de l'utilisateur autorisé. | Une clé d'accès est délivrée pour 1 heure, ainsi qu'un jeton de renouvellement pour 7 jours. |
| Refresh Token Cette méthode d'autorisation permet d'obtenir une nouvelle clé d'accès (access token) basée sur un jeton de renouvellement existant (refresh token). | Limitée à la portée de l'utilisateur à qui le jeton de renouvellement a été délivré. | Une nouvelle clé d'accès est délivrée pour 1 heure. Il ne peut pas être renouvelé avec cette méthode. |
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é.
# 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 avec chaque version de l'API, parallèlement à l'augmentation des fonctionnalités du serveur de visioconférence. Vous trouverez la correspondance entre l'API et la version du serveur dans la documentation de l'API.
Dans la documentation de l'TrueConf Server API, chaque méthode spécifie l'ensemble des autorisations requises pour son appel réussi.
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 :
Cliquez sur Create a new application.
Indiquez son identifiant dans le champ Name. Il est utilisé uniquement pour l'affichage dans la liste des applications.
Pour l'autorisation par la méthode Authorization Code, spécifiez l'URL de redirection dans le champ Redirect URL, vers lequel l'application sera redirigée. Pour les autres méthodes d'autorisation, vous pouvez indiquer l'adresse
https://localhost/.Dans la liste Permissions, cochez les autorisations nécessaires pour votre application.
Enregistrez les modifications à l'aide du 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 bloquer l'accès de cette application au serveur ainsi qu'à tous ses nouveaux utilisateurs. Notez que les clés d'accès et de renouvellement d'accès obtenues avec l'ancien secret continueront de fonctionner jusqu'à l'expiration de leur durée de vie.