https://www.youtube.com/watch ?v=nuXa-bn32Iw&t=4s
Si vous créez des automatisations qui appellent l’API de NinjaOne ou qui récupèrent des données depuis des outils comme Microsoft Defender ou Tenable, il vous faut un endroit pour exécuter ces scripts et un endroit pour stocker les identifiants qu’ils utilisent. Les exécuter depuis un poste de travail quelconque ou depuis votre propre compte technicien, c’est la meilleure façon de voir des identifiants fuiter ou être utilisés sans que vous puissiez facilement en assurer le suivi.
Un serveur API résout ce problème. Il s’agit d’un appareil Windows dédié, isolé dans sa propre société et dans son propre rôle, qui conserve vos identifiants API dans des champs personnalisés sécurisés visibles uniquement par les administrateurs système. Ce guide vous explique comment en configurer un de A à Z.
Prérequis pour un serveur API NinjaOne
Il vous faudra :
- Un appareil ou une MV (machine virtuelle) sous Windows. Une machine physique, une MV (machine virtuelle) HyperV ou une MV (machine virtuelle) dans le cloud conviennent toutes : c’est le système d’exploitation qui compte.
- Un accès administrateur système dans NinjaOne.
- Une liste claire des services avec lesquels ce serveur doit interagir (l’API de NinjaOne au minimum, plus tout autre service comme Defender ou Tenable).
La seule exigence incontournable : personne, en dehors de vos administrateurs système NinjaOne, ne doit avoir accès à cet appareil. Il va contenir des identifiants dotés d’autorisations de niveau administrateur système.
Configurer votre serveur API, étape par étape
Étape 1 : créer une société dédiée
Créez une nouvelle société pour héberger votre serveur API. Il reste ainsi totalement séparé de vos autres sociétés et n’apparaît pas mélangé aux données réelles de vos clients ou de vos terminaux.
Pour créer une nouvelle société :
cliquez sur le « + » en haut à droite > sélectionnez Société > donnez-lui un nom du type « Serveur API » > cliquez sur Enregistrer en haut à droite.
Étape 2 : créer un rôle d’appareil personnalisé
Allez dans Administration > Appareils > Rôles.
Cliquez sur Systèmes Windows pour développer la liste > survolez Windows Server (ou Ordinateurs de bureau et portables Windows, si votre serveur API fonctionne sous Windows 11) et cliquez sur les trois points > cliquez sur Ajouter un rôle enfant.
Nommez le rôle « Serveur API » et créez-le sous le parent correspondant à votre système d’exploitation.
Étape 3 : créer des champs personnalisés sécurisés
Toujours dans la page Rôles, allez dans Champs personnalisés d’appareil à gauche et créez trois nouveaux champs, tous de type Sécurisé.
Cliquez sur Ajouter un champ personnalisé > sélectionnez Sécurisé > dans le libellé, saisissez « NinjaOne Instance ».
À gauche, allez dans Autorisations > réglez Automatisations sur Lecture seule > réglez API sur Aucun > réglez l’accès Tous les techniciens sur Modifiable > cliquez sur Soumettre.
Répétez exactement la même procédure pour les deux champs suivants, en ne changeant que les libellés :
- NinjaOne Client ID
- NinjaOne Client Secret
Reprenez ces libellés exactement comme indiqué ci-dessus. NinjaOne convertit automatiquement le libellé en un nom de champ en camelCase, et ce nom est sensible à la casse lorsque vous le référencez plus tard dans un script.
Réglez l’autorisation API sur Aucun pour les trois champs. Rien ne justifie un accès de niveau API à un champ qui stocke justement les identifiants servant à authentifier vos appels API.
Conseil : si vous prévoyez de récupérer des données depuis d’autres services comme Defender ou Tenable, répétez cette procédure et créez des champs personnalisés sécurisés dédiés pour les identifiants de chacun d’eux.
Étape 4 : associer les champs à votre rôle
Revenez à Rôles à gauche > développez Systèmes Windows > développez votre rôle parent > repérez Serveur API et cliquez sur les trois points à droite > cliquez sur Modifier.
Cliquez sur Gérer les onglets en haut à droite > cliquez sur Ajouter un onglet et créez un nouvel onglet (par exemple « Identifiants API ») > une fois créé, cliquez sur le menu déroulant en haut à droite et basculez vers le nouvel onglet > dans la barre de recherche à gauche, saisissez « NinjaOne » > ajoutez les trois champs personnalisés sécurisés créés à l’étape 3 > cliquez sur Enregistrer les modifications en haut à droite.
Étape 5 : créer et appliquer votre politique
Allez dans Politiques > cliquez sur Ajouter une politique d’agent > nommez-la « Serveur API » > pour le rôle, sélectionnez le rôle Windows Server (ou Windows Desktop) sous lequel vous avez créé le rôle personnalisé > cliquez sur Créer > une fois la politique ouverte, cliquez sur Fermer en haut à droite.
Allez ensuite dans Sociétés > sélectionnez votre société Serveur API > cliquez sur Politiques à gauche > repérez la ligne Serveur API et ouvrez le menu déroulant > attribuez la politique que vous venez de créer > cliquez sur Enregistrer en haut à droite > une fois l’enregistrement effectué, cliquez sur Fermer.
Étape 6 : créer une catégorie d’automatisation
Dans Administration, allez dans Bibliothèque > cliquez sur Automatisation à gauche > sélectionnez l’onglet Catégories > cliquez sur Créer une catégorie tout à droite > donnez-lui un nom du type « Scripts API » > cliquez sur Créer.
Vos scripts liés à l’API restent ainsi bien organisés, et vous disposez d’une catégorie que vous pourrez ensuite restreindre aux seuls administrateurs système.
Étape 7 : installer l’agent
Téléchargez l’installateur de l’agent NinjaOne pour votre société Serveur API et exécutez-le sur votre appareil ou votre MV (machine virtuelle) dédié. Si vous réaffectez un appareil existant, déplacez-le plutôt dans la société Serveur API, mettez à jour son rôle et vérifiez que la politique Serveur API est bien appliquée via la nouvelle attribution.
Dans NinjaOne, cliquez sur le signe « + » en haut à droite > cliquez sur Appareil > cliquez sur Ordinateur > sélectionnez votre société Serveur API et le rôle de serveur API > cliquez sur Générer l’installateur > téléchargez ensuite l’installateur ou copiez le lien et exécutez-le sur votre appareil.
Attendez que l’appareil soit entièrement enregistré avant de poursuivre.
Si vous réaffectez un appareil existant, vous pouvez le faire depuis la grille de recherche des appareils :
dans le volet de navigation bleu à gauche, sélectionnez l’onglet Appareils > dans la liste des appareils, repérez l’appareil existant > cochez la case à côté du nom de l’appareil > cliquez sur Modifier > cliquez sur Société/Site et basculez vers la société Serveur API > cliquez sur Mettre à jour
L’appareil toujours sélectionné, cliquez sur Modifier > cliquez sur Rôle de l’appareil et choisissez le rôle personnalisé API > cliquez sur Mettre à jour.
L’appareil toujours sélectionné, cliquez sur Modifier > cliquez sur Politique et choisissez la politique Serveur API > cliquez sur Mettre à jour.
Étape 8 : créer les identifiants API
Une fois votre appareil connecté, allez dans Administration > Applications > API et cliquez sur Ajouter une application client en haut à droite.
Sélectionnez API Services (machine-to-machine) et créez une application client avec :
- Portées : Monitoring et Management
- Type d’autorisation : identifiants client
- URL de redirection : laissez vide
Cliquez sur Ajouter. NinjaOne génère alors un ID client et un secret client.
Étape 9 : renseigner vos champs personnalisés
Copiez l’ID client et le secret client de l’application que vous venez de créer > accédez à votre appareil Serveur API > survolez l’onglet personnalisé et sélectionnez l’onglet Identifiants API > cliquez sur l’icône de modification tout à droite > collez l’ID client et le secret client dans les champs correspondants.
Pour le champ d’instance, saisissez votre région NinjaOne (visible dans l’URL de connexion) :
- app.ninjarmm.com ou us2 pour les instances américaines
- ca.ninjarmm.com pour les instances canadiennes
- eu.ninjarmm.com pour les instances européennes
- oc.ninjarmm.com pour les instances Asie-Pacifique Sud-Est
- jp.ninjarmm.com pour les instances japonaises
- fed.ninjarmm.com pour les instances FedRAMP Moderate
Conseil : ces noms de champs sont sensibles à la casse une fois convertis en camelCase (ninjaoneClientId, ninjaoneClientSecret, ninjaoneInstance). Si vos scripts référencent les champs mais ne renvoient rien à l’exécution, vérifiez que les libellés correspondent exactement.
Une fois vos identifiants renseignés et testés, retournez dans Administration > Appareils > Champs personnalisés d’appareil > recherchez « ninjaone » et cliquez sur le ou les noms de champs pour faire repasser l’autorisation Accès Tous les techniciens des trois champs de Modifiable à Lecture seule. Les valeurs ne pourront ainsi plus être modifiées après la configuration.
Étape 10 : verrouiller les accès des techniciens
C’est cette étape qui rend la configuration sécurisée. Sans elle, n’importe quel technicien peut consulter des identifiants dotés d’un accès de niveau administrateur système.
Allez dans Administration > Comptes > Rôles de technicien.
Pour chaque rôle de technicien qui ne doit pas avoir accès (dans la plupart des cas, tous sauf les administrateurs système) :
cliquez sur le rôle concerné pour ouvrir l’éditeur > allez dans Sociétés à gauche.
- Sous Sociétés, réglez la société Serveur API sur Aucun accès.
- Sous Appareils, réglez le rôle Serveur API sur Aucun accès.
- Sous Politiques, réglez la politique Serveur API sur Aucun accès.
- Sous la bibliothèque d’automatisation, réglez votre catégorie Scripts API sur Aucun accès
Comment vérifier la configuration de votre serveur API. Une fois terminé, vous devriez avoir :
- une société dédiée contenant un seul appareil, votre serveur API ;
- un rôle personnalisé avec des champs sécurisés stockant votre ID client, votre secret client et votre instance ;
- une politique appliquée uniquement à cette société ;
- une catégorie d’automatisation verrouillée pour vos scripts API ;
- tous les rôles de technicien non administrateurs empêchés de voir la société, le rôle d’appareil, la politique et la catégorie d’automatisation.
Si un technicien de niveau 1 peut accéder à la société Serveur API et y voir quoi que ce soit, revenez à l’étape 10.
L’intérêt de cette approche
Des identifiants API avec un type d’autorisation « identifiants client » pèsent lourd. Selon les portées que vous sélectionnez, la personne qui les détient peut lire et écrire des données dans tout votre environnement NinjaOne. Stocker ces identifiants dans un champ personnalisé ordinaire sur un appareil partagé, ou les laisser visibles par tous les techniciens, transforme une configuration d’automatisation utile en véritable risque.
Mettre en place un serveur API dédié prend une vingtaine de minutes la première fois. En échange, vous obtenez une structure propre et auditable : un seul endroit pour les identifiants, une seule politique qui les régit et un modèle d’autorisations techniciens qui verrouille l’ensemble. Une fois cette base construite, ajouter une nouvelle intégration consiste simplement à créer quelques champs personnalisés supplémentaires et à déposer le script dans votre catégorie Scripts API.
Quelques exemples d’usages concrets de cette configuration :
l’importation de données de vulnérabilité depuis Microsoft Defender, pour que les résultats d’analyse arrivent directement dans NinjaOne au lieu de rester dans une console distincte.
Importation des vulnérabilités Microsoft Defender
Les rapports sur la gestion des correctifs du système d’exploitation Windows, qui consolident l’état des correctifs de tout votre environnement dans une vue unique.
Rapports sur la gestion des correctifs du système d’exploitation Windows
La synchronisation de l’état des correctifs, qui maintient les données à jour entre NinjaOne et une autre source de référence, sans passer par des vérifications manuelles.
Synchronisation de l’état des correctifs
