Activer et gérer l'API publique de SMC

SMC dispose d'une API REST standard permettant d'utiliser et d'interroger vos serveurs SMC via vos propres outils d'orchestration.

Toutes les fonctionnalités de SMC 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. Seul le super administrateur de SMC peut l'activer.

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 des droits en lecture/écriture ou bien lecture seule, ainsi qu'une période de validité paramétrable.

Toutes les actions effectuées via l'API publique sont consignées dans les logs d'audit.

Pour faciliter l'utilisation de l'API, une documentation OpenAPI est accessible sur le serveur SMC via l'adresse https://<@IP de SMC>/docs/papi ou via le lien affiché dans l'interface web de SMC.

La documentation est également disponible sur le site de la Documentation technique Stormshield.

NOTE
En cas d'utilisation intensive de l'API, c'est-à-dire plusieurs requêtes en écriture dans un délai de quelques secondes, alors que d'autres utilisateurs utilisent l'interface web d'administration en même temps, les performances de SMC peuvent être impactées. Certaines requêtes pourraient ne pas aboutir.
De même, si vous planifiez une utilisation intensive régulière, nous vous recommandons de désactiver la vérification de la cohérence de la configuration pour ne pas impacter les performances de SMC. Pour plus d'informations, reportez-vous à la section Vérifier la cohérence de la configuration.

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

Seul le super administrateur a le droit de l'activer et de la désactiver depuis l'interface web d'administration de SMC.

Lorsque l'API publique est activée :

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

  • l'accès à la documentation de l'API est autorisé,

  • le super administrateur peut accorder le droit de créer et révoquer des clés API aux autres administrateurs,

  • les administrateurs possédant le droit peuvent créer et révoquer des clés API.

Pour activer l'API publique :

  1. Dans le menu Maintenance > Serveur SMC, affichez l'onglet API publique,

  2. Cochez Activer l'API publique.

L'onglet API publique affiche les clés API créées par les autres administrateurs. Le super administrateur ne peut pas créer de clé API, mais il peut les révoquer. Pour plus d'informations sur la révocation des clés, reportez-vous à la section Révoquer des clés API.

Une clé API est nécessaire pour être authentifié sur l'API publique. Les administrateurs créent les clés API dans l'interface web d'administration de SMC. Ils choisissent une utilisation lecture/écriture ou lecture seule pour les clés, ainsi qu'une date d'expiration. Pour en savoir plus sur la création des clés, reportez-vous à la section Créer des clés API.

Les clés API créées doivent être ajoutées dans l'en-tête Authorization de chaque requête API.

EXEMPLE DE REQUÊTE API
En ligne de commande : curl -H "Authorization: Bearer <API_KEY>" https://<IP_SMC>/api/v1/firewalls

Le droit de créer et révoquer des clés API est accordé par le super administrateur, dans le profil des administrateurs.

NOTE
Le super administrateur ne peut pas créer de clé API.

Pour accorder à un administrateur le droit de créer et révoquer des clés API :

  1. Dans le menu Maintenance > Serveur SMC, affichez l'onglet Administrateurs,

  2. Double-cliquez sur le profil d'un administrateur,

  3. Cochez Création/Révocation de clés API dans la section Droits d'accès.

Cette option est grisée si l'API publique est désactivée.

Le super administrateur a la possibilité de définir une période de validité par défaut pour les clés API. Lorsqu'un autre administrateur crée une clé, la période de validité définie par le super administrateur est donc proposée par défaut dans le champ Date d'expiration, et l'administrateur peut modifier cette date.

Pour modifier la politique globale des clés API :

  1. Dans le menu Maintenance > Serveur SMC, affichez l'onglet API publique,

  2. Cliquez sur Modifier la politique globale des clés API.

  3. Définissez la période de validité proposée par défaut aux administrateurs lorsqu'ils créent une clé et appliquez. Celle-ci ne peut excéder 25 ans.

Les administrateurs possédant le droit Création/Révocation de clés API peuvent créer des clés API à utiliser pour l'authentification sur l'API publique. Pour en savoir plus sur ce droit, reportez-vous à la section Autoriser les administrateurs à créer et révoquer des clés API.

Ces clés possèdent un identifiant, un nom, une date d'expiration et une utilisation lecture/écriture ou lecture seule. Elles sont nécessaires pour chaque requête de l'API publique.

Pour créer une clé :

  1. Dans le menu Maintenance > Serveur SMC, affichez l'onglet Clés API. Il liste les clés déjà créées et leurs informations.

  2. Cliquez sur Ajouter une clé.

  3. Entrez un nom et une date d'expiration. La période de validité par défaut est définie par le super administrateur. Pour plus d'informations, reportez-vous à la section Modifier la politique globale des clés API.

  4. Dans le champ Utilisation, sélectionnez l'option souhaitée. Vous ne pouvez pas sélectionner l'utilisation Écriture si vous-même ne possédez pas ce droit sur SMC en tant qu'administrateur.

  5. Lorsque vous cliquez sur Appliquer, 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.

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 dans l'onglet Clés API depuis la vue Administrateur ou dans l'onglet API publique depuis la vue Super administrateur.

  2. Cliquez sur le bouton bouton Authorize.

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

  4. Cliquez sur Authorize puis sur Close.

Lorsque le profil d'un administrateur de SMC est supprimé, les clés API qui lui sont associées sont automatiquement supprimées, si elles ont été révoquées auparavant. Pour plus d'informations sur la révocation, reportez-vous à la section suivante.

Le super administrateur peut révoquer toutes les clés API et les administrateurs peuvent révoquer les clés API qu'ils ont créées eux-mêmes. Lorsque les clés API sont révoquées, vous ne pouvez plus les utiliser pour faire des requêtes sur l'API.

En tant que super administrateur :

  1. Dans le menu Maintenance > Serveur SMC, affichez l'onglet API publique,

  2. Sélectionnez la clé à révoquer dans la grille,

  3. Cliquez sur Révoquer.

Si en tant que super administrateur, vous souhaitez supprimer le profil d'un administrateur, vous devez révoquer les clés API qui lui sont associées auparavant. Il n'est pas possible de supprimer un profil si l'administrateur possède des clés actives.

De même, vous ne pouvez pas retirer le droit Lecture/Écriture SMC d'un administrateur si celui-ci possède des clés API actives et avec l'utilisation Lecture/Écriture. Vous devez auparavant révoquer les clés concernées.

En tant qu'administrateur :

  1. Dans le menu Maintenance > Serveur SMC, affichez l'onglet Clés API,

  2. Sélectionnez la clé à révoquer dans la grille,

  3. Cliquez sur Révoquer.

Par défaut, l'API publique et sa documentation utilisent le port 443.

Vous pouvez modifier le port par défaut à l'aide de la variable d'environnement SMC_PUBLIC_API_PORT_INT :

  1. Connectez-vous au serveur SMC via la console de votre hyperviseur ou en SSH.
  2. Dans le fichier /data/config/fwadmin-env.conf.local, ajoutez la variable d'environnement SMC_PUBLIC_API_PORT_INT="portNumber".
  3. Redémarrez le serveur avec la commande nrestart fwadmin-server.