Bouwt u automatiseringen die de API van NinjaOne aanroepen of haalt u gegevens op uit tools als Microsoft Defender of Tenable? Dan hebt u een plek nodig om die scripts uit te voeren en een plek om de bijbehorende referenties op te slaan. Draait u dat vanaf een willekeurige werkplek of vanaf uw eigen technicusaccount dan lekken referenties uit of worden ze gebruikt op een manier die u niet goed kunt volgen.
Een API-server lost dit op. Het is een speciaal ingericht Windows-device, geïsoleerd in een eigen organisatie en rol, dat uw API-referenties bewaart in beveiligde aangepaste velden die alleen systeembeheerders kunnen zien. In deze handleiding richt u er stap voor stap een in.
Vereisten voor een NinjaOne API-server
U hebt nodig:
- Een device of VM met Windows. Fysiek, een HyperV-VM of een cloud-VM werken allemaal, het gaat om het besturingssysteem.
- Toegang als systeembeheerder in NinjaOne.
- Een duidelijk overzicht van de diensten waarmee deze server moet communiceren (minimaal de API van NinjaOne, plus eventueel Defender of Tenable).
De enige harde eis: niemand behalve uw NinjaOne-systeembeheerders mag toegang hebben tot dit device. Het bewaart straks referenties met rechten op systeembeheerdersniveau.
Stap voor stap: uw API-server inrichten
Stap 1: maak een aparte organisatie aan
Maak een nieuwe organisatie aan voor uw API-server. Zo staat hij volledig los van uw andere organisaties en verschijnt hij niet tussen echte klant- of endpointgegevens.
Een nieuwe organisatie aanmaken:
Klik op de “+” rechtsboven > selecteer Organization > geef hem een naam als “API Server” > klik rechtsboven op Save.
Stap 2: maak een aangepaste devicerol aan
Ga naar Administration > Devices > Roles.
Klik op Windows Systems om het uit te klappen > ga met de muis over Windows Server (of Windows Desktops and Laptops als uw API-server op Windows 11 draait) en klik op de drie puntjes > klik op Add child role.
Noem de rol “API Server” en maak hem aan onder het bovenliggende item dat bij uw besturingssysteem past.
Stap 3: maak beveiligde aangepaste velden aan
Ga binnen de pagina Roles links naar Device custom fields en maak drie nieuwe velden aan, allemaal van het veldtype Secure.
Klik op Add custom field > selecteer Secure > vul als label “NinjaOne Instance.” in.
Ga links naar Permissions > zet Automations op Read Only > zet API op None > zet All technicians Access op Editable > klik op Submit.
Herhaal dit precies zo voor de volgende twee velden en wijzig alleen de labels:
- NinjaOne Client ID
- NinjaOne Client Secret
Gebruik exact de labels zoals hierboven geschreven. NinjaOne zet het label automatisch om in een veldnaam in camelCase en die naam is hoofdlettergevoelig wanneer u er later in een script naar verwijst.
Zet de rechten voor API op None bij alle drie de velden. Er is geen enkele reden voor toegang op API-niveau tot een veld dat juist de referenties bewaart waarmee uw API-aanroepen worden geauthenticeerd.
Tip: wilt u ook gegevens ophalen uit andere diensten zoals Defender of Tenable? Herhaal dit proces dan en maak aparte beveiligde aangepaste velden aan voor de referenties van elke dienst.
Stap 4: wijs de velden toe aan uw rol
Ga links terug naar Roles > klap Windows Systems uit > klap uw bovenliggende rol uit > zoek API Server en klik rechts op de drie puntjes > klik op Edit.
Klik rechtsboven op Manage Tabs > klik op Add tab en maak een nieuw tabblad aan (bijvoorbeeld “API Credentials”) > klik na het aanmaken rechtsboven op de dropdown en schakel over naar het nieuwe tabblad > typ in de zoekbalk links “NinjaOne” > voeg de drie beveiligde aangepaste velden uit stap 3 toe > klik rechtsboven op Save Changes.
Stap 5: stel uw beleid samen en pas het toe
Ga naar Policies > klik op Add Agent policy > noem het “API Server” > selecteer bij Role de rol Windows Server (of Windows Desktop) waaronder u de aangepaste rol hebt aangemaakt > klik op Create > klik na het openen rechtsboven op Close.
Ga vervolgens naar Organizations > selecteer uw organisatie API Server > klik links op Policies > zoek de regel voor API Server en open de dropdown > wijs het zojuist aangemaakte beleid toe > klik rechtsboven op Save > klik na het opslaan op Close.
Stap 6: maak een automatiseringscategorie aan
Ga in Administration naar Library > klik links op Automation > selecteer het tabblad Categories > klik helemaal rechts op Create category > geef hem een naam als “API Scripts” > klik op Create.
Zo houdt u uw API-scripts geordend en hebt u een categorie die u later kunt afschermen voor iedereen behalve systeembeheerders.
Stap 7: installeer de agent
Download de installateur van de NinjaOne Agent voor uw organisatie API Server en voer hem uit op uw speciaal ingerichte device of VM. Hergebruikt u een bestaand device? Verplaats het dan naar de organisatie API Server, werk de rol bij en controleer of het beleid API Server via de nieuwe toewijzing wordt toegepast.
Klik in NinjaOne rechtsboven op het “+”-teken > klik op Device > klik op Computer > selecteer uw organisatie API Server en de rol API-server > klik op Generate Installer > download daarna de installateur of kopieer de link en voer hem uit op uw device.
Wacht tot het device volledig is geregistreerd voordat u verdergaat.
Hergebruikt u een bestaand device dan kan dat via de Device Search Grid:
Selecteer in het blauwe navigatievenster links het tabblad Devices > zoek het bestaande device in de devicelijst > klik op het selectievakje naast de devicenaam > klik op Edit > klik op Organization/Location en schakel over naar de organisatie API Server > klik op Update
Klik terwijl het device nog geselecteerd is op Edit > klik op Device Role en kies de aangepaste rol API > klik op Update.
Klik terwijl het device nog geselecteerd is op Edit > klik op Policy en kies het beleid API Server > klik op Update.
Stap 8: maak API-referenties aan
Zodra uw device verbonden is, gaat u naar Administration > Apps > API en klikt u rechtsboven op Add client app.
Selecteer API Services (machine-to-machine) en bouw een client-app met:
- Scopes: Monitoring and Management
- Grant Type: Client credentials
- Redirect URL: laat leeg
Klik op Add. NinjaOne genereert een client-ID en een client secret.
Stap 9: vul uw aangepaste velden
Kopieer het client-ID en de client secret uit de app die u zojuist hebt aangemaakt > ga naar uw device API Server > ga met de muis over het aangepaste tabblad en selecteer het tabblad API Credentials > klik helemaal rechts op het bewerkpictogram > plak het client-ID en de client secret in de bijbehorende velden.
Vul bij het instance-veld uw NinjaOne-regio in (te vinden in de login-URL):
- app.ninjarmm.com of us2 voor instances in de VS
- ca.ninjarmm.com voor instances in Canada
- eu.ninjarmm.com voor instances in Europa
- oc.ninjarmm.com voor instances in Zuidoost-Azië en de Stille Oceaan
- jp.ninjarmm.com voor instances in Japan
- fed.ninjarmm.com voor instances met FedRAMP Moderate
Tip: deze veldnamen zijn hoofdlettergevoelig zodra ze zijn omgezet naar camelCase (ninjaoneClientId, ninjaoneClientSecret, ninjaoneInstance). Verwijzen uw scripts naar de velden maar krijgen ze bij uitvoering niets terug? Controleer dan of de labels exact overeenkomen.
Zodra uw referenties zijn ingevuld en getest, gaat u terug naar Administration > Devices > Device custom fields > zoek “ninjaone” en klikt u op de veldnaam of veldnamen om bij alle drie de velden het recht All-technicians Access terug te zetten van Editable naar Read Only, zodat de waarden na de installatie niet meer gewijzigd kunnen worden.
Stap 10: zet de technicustoegang dicht
Dit is de stap die de inrichting veilig maakt. Zonder deze stap kan elke technicus referenties met toegang op systeembeheerdersniveau inzien.
Ga naar Administration > Accounts > Technician Roles.
Voor elke technicusrol die geen toegang hoort te hebben (in de meeste gevallen alle rollen behalve systeembeheerders):
Klik op de gewenste rol om de editor te openen > ga links naar Organizations.
- Zet onder Organizations de organisatie API Server op No Access.
- Zet onder Devices de rol API Server op No Access.
- Zet onder Policies het beleid API Server op No Access.
- Zet onder de automatiseringsbibliotheek uw categorie API Scripts op No Access
Zo controleert u de configuratie van uw API-server. Als u klaar bent, hebt u:
- Een aparte organisatie met één device erin, uw API-server.
- Een aangepaste rol met beveiligde velden waarin uw client-ID, client secret en instance staan.
- Een beleid dat alleen op die organisatie wordt toegepast.
- Een afgeschermde automatiseringscategorie voor uw API-scripts.
- Elke technicusrol zonder beheerdersrechten geblokkeerd voor de organisatie, de devicerol, het beleid en de automatiseringscategorie.
Kan een technicus van level 1 naar de organisatie API Server navigeren en daar iets zien? Ga dan terug naar stap 10.
Waarom dit belangrijk is
API-referenties met grant type client credentials wegen zwaar. Afhankelijk van de scopes die u selecteert kan degene die ze in handen heeft gegevens lezen en schrijven in uw volledige NinjaOne-omgeving. Bewaart u die referenties in een gewoon aangepast veld op een gedeeld device of laat u ze zichtbaar voor elke technicus dan verandert een nuttige automatiseringsopzet in een risico.
Een eigen API-server bouwen kost de eerste keer zo’n twintig minuten. Daar krijgt u een overzichtelijke, controleerbare structuur voor terug: één plek voor referenties, één beleid dat ze beheert en een rechtenmodel voor technici dat het geheel afgeschermd houdt. Zodra het staat, is een nieuwe integratie toevoegen niet meer dan een paar extra aangepaste velden aanmaken en het script in uw categorie API Scripts zetten.
Een paar voorbeelden van waar deze opzet voor wordt gebruikt:
Gegevens over kwetsbaarheden importeren uit Microsoft Defender, zodat scanresultaten rechtstreeks in NinjaOne terechtkomen in plaats van in een apart portaal.
Import van kwetsbaarheden uit Microsoft Defender
Rapportage over Windows OS-patches, waarbij u de patchstatus uit uw hele omgeving in één overzicht samenbrengt.
Rapportage over Windows OS-patches
Synchronisatie van de patchstatus, waarmee patchgegevens actueel blijven tussen NinjaOne en een andere bron van waarheid in plaats van dat u handmatig moet controleren.
Synchronisatie van de patchstatus
