Gestire in sicurezza le API Credential di Sophos Central
Sophos Central può essere automatizzato tramite API e collegato a piattaforme SIEM, RMM, di reporting o assicurative. Non si usano account amministratore personali, ma API Credential dedicate formate da Client ID e Client Secret.
Queste credenziali sono identità macchina. Chi possiede il secret può eseguire tutte le azioni API consentite dal ruolo Service Principal assegnato. Il secret va quindi trattato come una password privilegiata e non deve finire in script, ticket, e-mail o repository Git.
Distinguere API Credentials e Integration Credential Manager
In Global Settings > Access Control esistono due aree dal nome simile:
| Area | Compito |
|---|---|
| API Credentials | identità tecnica con cui un’applicazione richiama le API Sophos Central |
| Integration Credential Manager | credenziali di prodotti terzi usate da Sophos per integrazioni come Data Ingestion o Response Actions |
Per uno script proprio, una query SIEM o un client API si creano API Credential. Le credenziali di un prodotto terzo che Sophos Central deve usare appartengono invece all’Integration Credential Manager.
Prerequisiti e responsabilità
Solo un Super Admin può creare e gestire API Credential. L’applicazione si autentica in seguito indipendentemente da questo amministratore personale. Se l’amministratore viene disattivato, l’identità tecnica resta valida fino alla scadenza o eliminazione.
Prima della creazione si documentano scopo, proprietario, sistema di destinazione, ruolo necessario, scadenza e contatto di emergenza. Si usa una Credential distinta per ogni applicazione e ambiente. Un secret condiviso tra script di backup, SIEM e fornitori esterni impedisce un blocco mirato e complica l’analisi delle cause.
Scegliere il ruolo Service Principal corretto
Sophos offre diversi ruoli:
- Service Principal Read-Only legge i dati del tenant, ma non può modificarli né eseguire query Live Discover.
- Service Principal Management può leggere, creare, modificare ed eliminare utenti e gruppi, leggere e gestire alert, leggere Endpoint ed eseguire azioni come uno scan, oltre a visualizzare e modificare impostazioni globali Endpoint Protection. Gestisce anche amministratori, ruoli e Security Policy, ma non accede alle query Live Discover.
- Service Principal Forensics crea, avvia ed elimina query Live Discover.
- Service Principal Active Directory Sync è esclusivamente per la sincronizzazione AD e non può svolgere altre attività API.
- Service Principal Firewall limita l’identità alla gestione Firewall e vieta attività API Central esterne a tale ambito.
- Service Principal Super Admin dispone di ampi diritti di lettura, scrittura, eliminazione e query.
La scelta parte sempre dal ruolo più ristretto. Un’integrazione di reporting o assicurazione cyber riceve Read-Only. AD Sync usa il ruolo dedicato. Super Admin si usa solo se gli endpoint API documentati richiedono davvero ampi diritti di scrittura e nessun ruolo più ristretto funziona.
Creare una Credential
Il percorso è Global Settings > Access Control > API Credentials. Al primo accesso occorre accettare le condizioni di utilizzo.
- Aprire Add Credential.
- Inserire un nome univoco e una descrizione con applicazione, ambiente e proprietario.
- Selezionare il ruolo Service Principal minimo necessario.
- Creare la Credential e acquisire subito Client ID e Client Secret.
- Conservare il secret in un secret store aziendale e cancellarlo dagli appunti temporanei.
Il Client Secret viene mostrato una sola volta e non può essere visualizzato di nuovo. Se viene perso, non si ripristina quello esistente: si crea una nuova Credential e si elimina la precedente dopo una migrazione riuscita.
Testare l’autenticazione in modo controllato
Il primo test non deve essere un’azione di scrittura in produzione. Si ottiene innanzitutto un OAuth Access Token dall’endpoint Sophos Identity. L’endpoint whoami restituisce poi Tenant ID, API Host e tipo di account. Solo allora si esegue una chiamata di lettura innocua contro l’API Host fornito per il tenant.
L’API Host non va copiato da un esempio. Sophos utilizza più regioni dati e occorre quindi usare l’URL restituito da whoami. Anche Tenant ID e Organization ID non sono intercambiabili.
Il test documenta almeno:
- l’autenticazione con la nuova identità funziona,
- viene restituito il tenant previsto,
- le operazioni di lettura autorizzate funzionano,
- un’operazione non consentita viene rifiutata con
403 Forbidden, - Audit Log o log dell’integrazione mostrano il test in modo tracciabile.
Gestire scadenza e rotazione
Sophos non invia avvisi quando una API Credential scade. Dopo la scadenza non può più autenticarsi e viene rimossa automaticamente da Central. Il monitoraggio deve quindi avvenire fuori da Central.
Una rotazione corretta usa una breve sovrapposizione:
- Creare una nuova Credential con ruolo identico o più ristretto.
- Configurare l’applicazione con Client ID e secret nuovi.
- Testare autenticazione e funzione operativa.
- Eliminare la vecchia Credential.
- Verificare la modifica in Audit Log, registro dei secret e documentazione operativa.
La vecchia Credential non va lasciata attiva per mesi come precauzione. Se un’applicazione supporta un solo set di secret, si pianifica una finestra di manutenzione.
Sostituire i vecchi token SIEM API
API Token Management è la precedente autenticazione della SIEM Integration API. Sophos non emette più nuovi token e non estende la durata di quelli esistenti, che funzionano solo fino alla scadenza.
Un’integrazione che li usa non va lasciata invariata fino all’ultimo giorno. Si inventariano token, sistema di destinazione, scadenza ed endpoint usati, si crea una API Credential appropriata, si migra l’applicazione e si verifica l’intero flusso dati. Il vecchio token viene rimosso solo dopo un controllo parallelo riuscito.
Il passaggio da token legacy ad API Credential non è una semplice rinomina. L’integrazione deve supportare autenticazione OAuth, whoami, host regionale e modello dei ruoli. Un connettore SIEM si configura quindi secondo la documentazione attuale del produttore, non con un vecchio esempio di token.
Fornitori esterni e accesso di terzi
Per un soggetto esterno si crea un’identità Service Principal Read-Only dedicata, se bastano diritti di lettura. Client ID e secret vengono trasferiti su canali cifrati separati. L’accesso riceve una data di fine e viene eliminato alla conclusione del progetto.
Via API, questo accesso può leggere soprattutto Alerts ed Events, risultati dell’Account Health Check, dettagli dei dispositivi e configurazioni delle policy. Read-Only impedisce aggiunte, modifiche ed eliminazioni in Central, ma non limita automaticamente quali dati leggibili vengano prelevati o conservati dalla piattaforma terza. Prima dell’autorizzazione si chiariscono contrattualmente ambito, scopo, luogo di archiviazione, conservazione ed eliminazione dei dati.
La creazione segue Global Settings > Access Control > API Credentials > Add Credential. Al primo accesso si accettano condizioni d’uso e privacy, si sceglie Service Principal Read-Only e si acquisiscono in sicurezza Client ID e Client Secret visibile una sola volta. Il trasferimento avviene tramite un canale cifrato approvato, come il portale HTTPS del fornitore, non via e-mail o ticket.
L’API Host non viene copiato da una tabella regionale statica. L’applicazione usa whoami per determinare l’host valido proprio per quel tenant. La documentazione resta così corretta anche se Sophos modifica regioni o endpoint. Quando il fornitore non necessita più dell’accesso, si elimina la Credential revocando immediatamente l’autorizzazione API.
Non sono accettabili l’esportazione dell’account Super Admin personale, un’identità API condivisa tra più clienti o un secret nel ticket di supporto. Il fornitore deve inoltre dichiarare dove conserva il secret, come lo protegge e quando lo elimina.
Individuare gli errori
401 Unauthorized
Di norma Client ID, secret, endpoint token o richiesta OAuth sono errati. Anche una Credential scaduta e già rimossa causa questo errore. Verificare prima che esista ancora in Central e che l’applicazione usi davvero il set di secret più recente.
403 Forbidden
L’autenticazione è riuscita, ma il ruolo non consente l’azione. Invece di assegnare subito Super Admin, si associa l’endpoint API necessario al ruolo Service Principal appropriato.
Token corretto, regione dati errata
L’Access Token non determina da solo l’API Host operativo. L’applicazione deve usare l’host regionale restituito da whoami. Un host fisso di un’altra regione causa errori o query contro il confine di piattaforma errato.
L’integrazione si interrompe senza preavviso
Se Central non mostra un alert aperto, si verificano scadenza, ultima chiamata API riuscita e versione del secret nel sistema di destinazione. Il monitoraggio della scadenza appartiene al sistema esterno.
Controllo periodico
Almeno ogni trimestre si verificano nome, proprietario, ruolo, ultimo utilizzo, scadenza e destinazione di ogni Credential. Le identità non attribuibili o inutilizzate vengono eliminate. In caso di sospetta fuoriuscita del secret, la Credential viene bloccata immediatamente, sostituita e l’Audit Log esaminato per azioni insolite.
I diritti degli amministratori personali vengono controllati separatamente secondo Assegnare correttamente i ruoli amministrativi di Sophos Central. Le API Credential non sostituiscono né MFA né un accesso amministrativo personale tracciabile.