Activer et gérer l'API publique de SES Evolution

SES Evolution dispose d'une API REST permettant d'utiliser la solution via vos propres outils d'orchestration.

Toutes les fonctionnalités de SES Evolution ne sont pas encore disponibles dans l'API publique. Celle-ci est enrichie au fur et à mesure des versions.

Par défaut, l'API publique n'est pas activée.

L'authentification sur l'API publique est sécurisée par des clés API, générées par les administrateurs. Ces clés possèdent une utilisation ainsi qu'une durée de validité paramétrables.

Les actions de type POST effectuées via l'API publique sont consignées dans les logs système.

Pour faciliter l'utilisation de l'API, une documentation OpenAPI est accessible via un lien affiché dans la console d'administration. Elle est également disponible sur le site de la Documentation technique Stormshield.

Vous devez disposer du droit API publique-Modifier pour activer l'API publique et générer des clés, à partir du menu Clés API de la console d'administration. Voir Gérer les utilisateurs de la console d'administration SES Evolution.

Ce droit est prioritaire sur le droit Système. Si un administrateur n'a aucun droit Système, mais possède le droit API publique-Afficher ou API publique-Modifier, le menu Système s'affiche avec uniquement l'onglet Clés API.

L'API publique de SES Evolution est désactivée par défaut.

Lorsque l'API publique est activée :

  • l'accès aux routes de l'API est autorisé,

  • les administrateurs autorisés peuvent créer, modifier et révoquer des clés API.

Pour activer l'API publique :

  1. Dans le menu Backoffice > Système, affichez l'onglet Clés API,

  2. Cliquez sur Modifier dans le bandeau supérieur,

  3. Cochez Activer l'API publique.

    onglet Clés API

L'onglet Clés API permet d'ajouter, modifier et révoquer les clés donnant accès aux routes de l'API publique de SES Evolution.

Ces clés possèdent un identifiant, une description, une date de création, une date d'expiration et une utilisation. Elles sont nécessaires pour chaque requête de l'API publique.

Pour ajouter une clé :

  1. Cliquez sur Modifier dans le bandeau supérieur.

  2. Cliquez sur Ajouter une clé API.

  3. Entrez une description.

  4. Choisissez une durée de validité. Après la création de la clé, vous ne pourrez plus modifier cette durée.

  5. Cochez les utilisations de la clé, qui ouvrent l'accès aux différentes routes proposées par l'API.

  6. Lorsque vous cliquez sur OK, la clé n'est pas enregistrée en base de données. Vous devez la copier et la stocker en sécurité car elle ne sera plus disponible par la suite.

  7. Cliquez sur Fermer, puis sur Enregistrer dans le bandeau supérieur.

Tous les administrateurs de SES Evolution qui ont le droit d'afficher l'onglet Clés API ont accès à la liste des clés créées.

Une clé API peut être utilisée dans la documentation de l'API pour tester les requêtes :

  1. Cliquez sur le lien Voir la documentation API.

  2. Cliquez sur le bouton .

  3. Entrez la clé API dans le champ Value.

  4. Cliquez sur Authorize puis sur Close.

Vous pouvez révoquer les clés API. Lorsqu'elles sont révoquées, vous ne pouvez plus les utiliser pour faire des requêtes sur l'API.

Pour révoquer une clé :

  1. Cliquez sur Modifier dans le bandeau supérieur,

  2. Sur la ligne de la clé à révoquer, cliquez sur l'icône dans la colonne Actions,

  3. Validez.

Si vous souhaitez afficher dans le tableau seulement les clés non révoquées, activez le bouton Cacher les clés révoquées.

La documentation de l'API publique ne s'affiche pas

Situation : Le lien Voir la documentation API dans la console d'administration ouvre un navigateur Internet et la documentation ne s'affiche pas.

Cause :  Si vous avez mis à jour SES Evolution vers la version 2.5.5 et si votre serveur backend est installé sur le système d'exploitation Windows Server 2022, l'option TLS 1.3 est activée par défaut dans les paramètres IIS du backend. Cette option rend la documentation API incompatible avec ce système d'exploitation.

Solution : Dans votre Gestionnaire de services IIS, vous devez désactiver l'option TLS 1.3 over TCP dans les paramètres du nom d'hôte du backend. Le nom d'hôte à modifier est visible dans l'URL de la documentation API. Il correspond au nom d'hôte du cluster du backend, utilisé lors de l'installation de SES Evolution.