Se stai creando automazioni che richiamano l’API di NinjaOne oppure importi dati da strumenti come Microsoft Defender o Tenable, ti serve un posto dove eseguire quegli script e un posto dove conservare le credenziali che utilizzano. Eseguire tutto questo da una workstation qualsiasi o dal tuo account da tecnico è il modo più rapido per far trapelare le credenziali o per vederle usate in modi difficili da tracciare.
Un API server risolve il problema. È un dispositivo Windows dedicato, isolato in un’organizzazione e in un ruolo propri, che conserva le credenziali API in campi personalizzati sicuri visibili solo ai System Administrator. Questa guida ti accompagna nella configurazione da zero.
Requisiti per l’API server di NinjaOne
Ti serviranno:
- Un dispositivo o una virtual machine con Windows. Vanno bene una macchina fisica, una virtual machine HyperV o una virtual machine nel cloud: ciò che conta è il sistema operativo.
- Accesso come System Administrator in NinjaOne.
- Un elenco chiaro dei servizi con cui questo server deve interagire (come minimo l’API di NinjaOne, più eventuali altri servizi come Defender o Tenable).
L’unico requisito irrinunciabile: nessuno, a parte i tuoi system administrator di NinjaOne, deve avere accesso a questo dispositivo. Conterrà credenziali con permessi a livello di system administrator.
Passo dopo passo: come configurare l’API server
Passaggio 1: crea un’organizzazione dedicata
Crea una nuova organizzazione che ospiti il tuo API server. In questo modo resta completamente separato dalle altre organizzazioni e non compare mischiato ai dati reali di clienti o endpoint.
Per creare una nuova organizzazione:
Fai clic sul “+” in alto a destra > seleziona Organizzazione > assegnale un nome come “API Server” > fai clic su Salva in alto a destra.
Passaggio 2: crea un ruolo dispositivo personalizzato
Vai su Amministrazione > Dispositivi > Ruoli.
Fai clic su Windows Systems per espanderlo > passa il mouse su Windows Server (oppure su Windows Desktops and Laptops, se il tuo API server usa Windows 11), fai clic sui tre puntini > fai clic su Aggiungi ruolo figlio.
Chiama il ruolo “API Server” e crealo sotto il ruolo padre corrispondente al tuo sistema operativo.
Passaggio 3: crea i campi personalizzati sicuri
Sempre nella pagina Ruoli, nel menu a sinistra vai su Campi personalizzati dispositivo e crea tre nuovi campi, tutti di tipo Secure.
Fai clic su Aggiungi campo personalizzato > seleziona Secure > nell’etichetta inserisci “NinjaOne Instance.”
Nel menu a sinistra vai su Autorizzazioni > imposta Automazioni su Sola lettura > imposta API su Nessuno > imposta Accesso di tutti i tecnici su Modificabile > fai clic su Invia.
Ripeti esattamente la stessa procedura per i due campi seguenti, cambiando solo le etichette:
- NinjaOne Client ID
- NinjaOne Client Secret
Scrivi le etichette esattamente come indicato sopra. NinjaOne converte automaticamente l’etichetta in un nome di campo in camelCase, e quel nome distingue maiuscole e minuscole quando lo richiami in uno script.
Imposta l’autorizzazione API su Nessuno per tutti e tre i campi. Non c’è alcun motivo per consentire un accesso a livello di API a un campo che contiene proprio le credenziali usate per autenticare le tue chiamate API.
Consiglio: se prevedi di importare dati da altri servizi come Defender o Tenable, ripeti questa procedura e crea campi personalizzati sicuri dedicati alle credenziali di ciascuno.
Passaggio 4: assegna i campi al tuo ruolo
Torna su Ruoli nel menu a sinistra > espandi Windows Systems > espandi il ruolo padre > individua API Server e fai clic sui tre puntini a destra > fai clic su Modifica.
Fai clic su Gestisci schede in alto a destra > fai clic su Aggiungi scheda e crea una nuova scheda (per esempio “API Credentials”) > una volta creata, fai clic sul menu a discesa in alto a destra e passa alla nuova scheda > nella barra di ricerca a sinistra digita “NinjaOne” > aggiungi i tre campi personalizzati sicuri creati al Passaggio 3 > fai clic su Salva modifiche in alto a destra.
Passaggio 5: crea e applica la policy
Vai su Policy > fai clic su Aggiungi policy agente > chiamala “API Server” > come Ruolo seleziona il ruolo Windows Server (o Windows Desktop) sotto cui hai creato il ruolo personalizzato > fai clic su Crea > una volta aperta, fai clic su Chiudi in alto a destra.
Poi vai su Organizzazioni > seleziona l’organizzazione API Server > fai clic su Policy a sinistra > individua la riga API Server e apri il menu a discesa > assegna la policy appena creata > fai clic su Salva in alto a destra > una volta salvato, fai clic su Chiudi.
Passaggio 6: crea una categoria di automazione
In Amministrazione, vai su Libreria > fai clic su Automazione a sinistra > seleziona la scheda Categorie > fai clic su Crea categoria all’estrema destra > assegnale un nome come “API Scripts” > fai clic su Crea.
In questo modo i tuoi script legati alle API restano organizzati e ottieni una categoria che potrai poi riservare ai soli System Administrator.
Passaggio 7: installa l’agente
Scarica l’installer dell’agente NinjaOne per la tua organizzazione API Server ed eseguilo sul dispositivo o sulla virtual machine dedicata. In alternativa, se stai riutilizzando un dispositivo esistente, spostalo nell’organizzazione API Server, aggiorna il suo ruolo e verifica che la policy API Server venga applicata tramite la nuova assegnazione.
In NinjaOne, fai clic sul segno “+” in alto a destra > fai clic su Dispositivo > fai clic su Computer > seleziona l’organizzazione API Server e il ruolo API server > fai clic su Genera installer > poi scarica l’installer oppure copia il link ed eseguilo sul tuo dispositivo.
Aspetta che il dispositivo sia completamente registrato prima di proseguire.
Se stai riutilizzando un dispositivo esistente, puoi farlo dalla griglia di ricerca dei dispositivi:
Nel pannello di navigazione blu a sinistra, seleziona la scheda Dispositivi > nell’elenco dei dispositivi individua quello esistente > seleziona la casella accanto al nome del dispositivo > fai clic su Modifica > fai clic su Organizzazione/Sede e passa all’organizzazione API Server > fai clic su Aggiorna
Con il dispositivo ancora selezionato, fai clic su Modifica > fai clic su Ruolo dispositivo e scegli il ruolo API personalizzato > fai clic su Aggiorna.
Con il dispositivo ancora selezionato, fai clic su Modifica > fai clic su Policy e scegli la policy API Server > fai clic su Aggiorna.
Passaggio 8: crea le credenziali API
Una volta che il dispositivo è connesso, vai su Amministrazione > App > API e fai clic su Aggiungi app client in alto a destra.
Seleziona API Services (machine-to-machine) e crea un’app client con:
- Scope: Monitoring and Management
- Grant Type: Client credentials
- Redirect URL: lascia vuoto
Fai clic su Aggiungi. NinjaOne genererà un client ID e un client secret.
Passaggio 9: compila i campi personalizzati
Copia il client ID e il client secret dall’app appena creata > vai al dispositivo API Server > passa il mouse sulla scheda personalizzata e seleziona la scheda API Credentials > fai clic sull’icona di modifica all’estrema destra > incolla il client ID e il client secret nei campi corrispondenti.
Nel campo dell’istanza, inserisci la tua region NinjaOne (la trovi nell’URL di login):
- app.ninjarmm.com oppure us2 per le istanze USA
- ca.ninjarmm.com per le istanze Canada
- eu.ninjarmm.com per le istanze Europa
- oc.ninjarmm.com per le istanze Asia-Pacifico sud-orientale
- jp.ninjarmm.com per le istanze Giappone
- fed.ninjarmm.com per le istanze FedRAMP Moderate
Consiglio: questi nomi di campo distinguono maiuscole e minuscole una volta convertiti in camelCase (ninjaoneClientId, ninjaoneClientSecret, ninjaoneInstance). Se i tuoi script richiamano i campi ma non restituiscono nulla durante l’esecuzione, verifica che le etichette corrispondano esattamente.
Una volta inserite e testate le credenziali, torna su Amministrazione > Dispositivi > Campi personalizzati dispositivo > cerca “ninjaone” e fai clic sul nome dei campi per riportare l’autorizzazione Accesso di tutti i tecnici su tutti e tre i campi da Modificabile a Sola lettura, così i valori non potranno essere alterati dopo la configurazione.
Passaggio 10: limita l’accesso dei tecnici
È questo il passaggio che rende sicura la configurazione. Senza di esso, qualsiasi tecnico può visualizzare credenziali con accesso a livello di system administrator.
Vai su Amministrazione > Account > Ruoli tecnico.
Per ogni ruolo tecnico che non deve avere accesso (nella maggior parte dei casi, tutti tranne i system administrator):
Fai clic sul ruolo desiderato per aprire l’editor > vai su Organizzazioni nel menu a sinistra.
- In Organizzazioni, imposta l’organizzazione API Server su Nessun accesso.
- In Dispositivi, imposta il ruolo API Server su Nessun accesso.
- In Policy, imposta la policy API Server su Nessun accesso.
- Nella libreria di automazione, imposta la categoria API Scripts su Nessun accesso
Come verificare la configurazione del tuo API server Una volta terminato, dovresti avere:
- Un’organizzazione dedicata che contiene un solo dispositivo, il tuo API server.
- Un ruolo personalizzato con campi sicuri che conservano client ID, client secret e istanza.
- Una policy applicata solo a quell’organizzazione.
- Una categoria di automazione bloccata per i tuoi script API.
- Tutti i ruoli tecnico non amministrativi impossibilitati a vedere l’organizzazione, il ruolo dispositivo, la policy e la categoria di automazione.
Se un tecnico di livello 1 riesce ad accedere all’organizzazione API Server e a vedere qualcosa, torna al Passaggio 10.
Perché è importante
Le credenziali API con grant type client credentials hanno un peso concreto. A seconda degli scope selezionati, chi le possiede può leggere e scrivere dati in tutto il tuo ambiente NinjaOne. Conservare quelle credenziali in un campo personalizzato normale su un dispositivo condiviso, o lasciarle visibili a ogni tecnico, trasforma una configurazione di automazione utile in un rischio.
Creare un API server dedicato richiede forse venti minuti la prima volta. In cambio ottieni una struttura pulita e verificabile: un unico posto per le credenziali, un’unica policy che le governa e un modello di permessi per i tecnici che tiene tutto sotto controllo. Una volta realizzato, aggiungere una nuova integrazione significa semplicemente creare qualche campo personalizzato in più e inserire lo script nella categoria API Scripts.
Alcuni esempi di utilizzo di questa configurazione:
Importazione dei dati sulle vulnerabilità da Microsoft Defender, così i risultati delle scansioni arrivano direttamente in NinjaOne invece di restare in una console separata.
Importazione delle vulnerabilità da Microsoft Defender
Reportistica delle patch per Windows OS, che raccoglie lo stato delle patch di tutto l’ambiente in una vista consolidata.
Reportistica delle patch per Windows OS
Sincronizzazione dello stato delle patch, per mantenere i dati sulle patch allineati tra NinjaOne e un’altra fonte attendibile, senza dover ricorrere a controlli manuali.
Sincronizzazione dello stato delle patch
