Migrare dispositivi Sophos tra tenant Central

In caso di acquisizione aziendale, consolidamento dei tenant o assegnazione errata del cliente, i computer gestiti vengono spostati da un account Sophos Fusion di origine a uno di destinazione mediante Device Migration. La procedura ordinaria utilizza l’Endpoint API: prima si crea un Receiving Job nella destinazione, quindi si avvia il relativo Sending Job nell’account di origine.

Ambito di applicazione: l’attuale guida Sophos descrive questa procedura per i «computers». Prima del rollout, occorre confermare nella documentazione aggiornata dell’Endpoint API, nella risposta del tenant live o con Sophos Support quali sistemi operativi, tipi di dispositivo, versioni dell’agente e prodotti installati siano ammessi nel tenant specifico. I tipi generali dell’Endpoint API non costituiscono un elenco di compatibilità per la migrazione. Access Point e switch seguono procedure proprie e non rientrano in questo workflow API.

Cosa fa Device Migration e cosa va preparato separatamente

Device Migration modifica la registrazione e l’account che gestisce il computer. Dopo una migrazione riuscita, il computer viene gestito dall’account di destinazione. Se la migrazione non riesce, secondo Sophos continua a essere gestito dall’account di origine.

La documentazione pubblica non descrive il trasferimento di policy, gruppi, eccezioni globali, elenchi di siti web, licenze, assegnazioni di prodotti, alert, indagini o cronologia degli audit. Non è quindi possibile dedurne né che questi dati vengano trasferiti automaticamente, né che rimangano integralmente nell’account di origine. Per questo motivo, la configurazione di destinazione va preparata e lo stato effettivo va verificato dopo la migrazione.

Pianificare prerequisiti e progetto pilota

Prima del primo job, si inventariano origine e destinazione e si definisce un progetto pilota piccolo e rappresentativo. Server critici, sistemi VDI, dispositivi in smart working, computer isolati e notebook che si connettono raramente vengono gestiti in ondate separate.

Devono essere soddisfatti i seguenti prerequisiti:

• In entrambi gli account, la persona che esegue l’operazione possiede il ruolo Sophos Admin.
• Per entrambi gli account esistono API Credentials separate con il ruolo credenziale Service Principal Super Admin. Un Super Admin umano deve creare e gestire queste credenziali; il solo ruolo Admin non è sufficiente.
• Il Tenant ID e l’host API regionale sono noti per entrambi gli account. Vengono determinati tramite la normale configurazione delle API Sophos e non ipotizzati.
• Gli Endpoint ID da migrare provengono dall’account di origine e l’idoneità di ciascun dispositivo pilota è stata confermata nel tenant live o con Sophos Support.
• Nella destinazione sono stati predisposti licenze, policy, gruppi, eccezioni ed elenchi di siti web adeguati.
• Update Cache, Message Relay e proxy dell’account di destinazione sono raggiungibili dalle rispettive ubicazioni dei dispositivi.
• Isolamenti, alert aperti e indagini in corso sono documentati; le prove necessarie relative a incidenti e audit sono state salvate prima del passaggio.

API Client Secret e Bearer Token ottenuto da esso appartengono sempre a uno specifico account. Il Migration Job Access Token restituito in seguito dal Receiving Job è un segreto diverso. Client Secret, Bearer Token e Migration Job Access Token non devono comparire in screenshot, ticket, cronologia della shell o registri operativi.

Abilitare Device Migration in entrambi gli account

Accedere prima all’account di origine e poi a quello di destinazione e, in ciascuno, aprire Global Settings > Platform > Device Migration:

1. Attivare Allow device migration.
2. Impostare un limite temporale il più breve possibile, ma sufficiente per il progetto pilota o l’ondata.
3. Subito prima di avviare il job, verificare nuovamente che la finestra sia attiva in entrambi gli account.

Se l’opzione è bloccata, la configurazione deriva dalle impostazioni globali del partner o dell’amministratore Enterprise. Non si deve aggirare il blocco mediante workaround: l’amministrazione sovraordinata competente deve concedere l’autorizzazione.

Eseguire la migrazione con Receiving Job e Sending Job

L’attuale guida Sophos su Device Migration descrive l’ordine dei job. L’Endpoint Migration API Guide rimanda all’attuale riferimento API. Immediatamente prima dell’esecuzione, verificare nella definizione aggiornata dell’Endpoint API la struttura esatta delle richieste, i campi e l’attuale limite quantitativo. Payload o limiti storici non devono essere adottati senza verifica. L’ordine da seguire è il seguente:

1. Creare il Receiving Job nella destinazione

Il modello operativo è POST /endpoint/v1/migrations. La chiamata utilizza l’host API regionale e le credenziali dell’account di destinazione. Invia il Bearer Token nell’header Authorization, l’ID dell’account di destinazione nell’header X-Tenant-ID e, in presenza di un body JSON, l’header Content-Type: application/json.

Il body specifica l’account di origine e i dispositivi confermati del progetto pilota o dell’ondata. Nello schema storico, questi campi si chiamano fromTenant ed endpoints; prima dell’esecuzione occorre confermare se nello schema live abbiano ancora esattamente questi nomi e siano entrambi obbligatori in questa fase.

Dalla risposta, salvare:

• l’ID del Receiving Job;
• il Migration Job Access Token per il relativo Sending Job;
• una data di scadenza restituita dall’API corrente, se presente.

L’ID del job può essere inserito nel registro delle modifiche. Il Migration Job Access Token viene trasmesso esclusivamente tramite un canale sicuro per i segreti alla persona o all’automazione che crea il Sending Job e non viene registrato in modo permanente.

2. Avviare il Sending Job nell’origine

Successivamente, autenticarsi separatamente nell’account di origine. Il modello operativo è PUT /endpoint/v1/migrations/{receivingMigrationJobId}. Il percorso contiene l’ID del Receiving Job. La chiamata invia il Bearer Token nell’header Authorization e l’ID dell’account di origine nell’header X-Tenant-ID; in presenza di un body JSON, si aggiunge Content-Type: application/json.

Il Sending Job utilizza:

• l’elenco confermato degli Endpoint ID dell’account di origine;
• l’ID del Receiving Job creato in precedenza;
• il relativo Migration Job Access Token.

Lo schema storico indica i campi del body come token ed endpoints. Anche questi nomi e l’attuale struttura della risposta devono essere confermati nella definizione live prima dell’esecuzione.

La migrazione inizia con il Sending Job. Prima dell’invio, verificare nuovamente il contesto del tenant, l’elenco degli endpoint e l’ambito dell’ondata. Non riutilizzare un token o un ID job proveniente da un’altra esecuzione. L’ID del Sending Job restituito dall’API corrente viene registrato insieme all’ID del Receiving Job; una data di scadenza viene registrata solo se fornita dalla risposta live.

3. Monitorare stato e coda

Lo stato di avanzamento viene interrogato tramite GET /endpoint/v1/migrations/{migrationJobId}/endpoints. La chiamata viene eseguita per ciascun Sending Job e Receiving Job pertinente, rispettivamente nel contesto dell’account di origine e di destinazione, utilizzando per ognuno il relativo Bearer Token e X-Tenant-ID. Se i risultati sono suddivisi su più pagine, occorre interrogarle tutte e confrontare i risultati per ogni Endpoint ID richiesto. Facoltativamente, GET /endpoint/v1/settings/migration indica se la migrazione è abilitata nel rispettivo account.

La definizione live corrente determina i valori di stato e i campi di dettaglio. Lo schema API storico utilizzava pending, succeeded e failed; a seconda del risultato, restituiva fra l’altro un nuovo Endpoint ID, informazioni temporali e il motivo dell’errore. Questi nomi sono indicazioni orientative, non una garanzia dello schema attuale. Occorre salvare i valori e i campi effettivamente restituiti.

I computer rimangono nella coda di migrazione fino a 14 giorni. Un computer offline deve tornare online entro questo periodo. Una finestra di migrazione configurata con una durata inferiore può ridurre ulteriormente il tempo disponibile. Se il dispositivo rimane offline più a lungo e la migrazione scade, l’operazione non riesce e un amministratore deve inserire nuovamente il dispositivo nella coda di migrazione in modo manuale.

Un dispositivo offline in sospeso non deve essere disinstallato preventivamente né modificato intervenendo localmente sul Tenant ID. Per prima cosa, ripristinare la connessione entro la finestra valida. In caso di tentativo non riuscito, il dispositivo rimane gestito dall’account di origine.

Verificare il successo nell’origine, nella destinazione e sul dispositivo

Lo stato dell’API da solo non costituisce una prova completa di accettazione. Prima dell’ondata successiva, confrontare i risultati nei due account e sul computer.

Prove ufficiali della migrazione

1. Nell’Audit Log dell’account di origine è presente l’evento Send endpoints to another tenant.
2. Nell’evento del computer migrato correttamente compare Device registered with new account . It’s now managed by that account.
3. Per un computer la cui migrazione non è riuscita, compare invece Device failed to register with new account . It continues to be managed by this account.
4. Nell’Audit Log dell’account di destinazione è presente Allow endpoints to migrate to this tenant.
5. In My Environment > Computers & Servers, nella destinazione, il computer è registrato, assegnato a un utente e aggiornato.
6. Tutti gli Endpoint ID richiesti sono associati ai risultati API; se restituito, viene documentato anche il nuovo Endpoint ID.

Accettazione operativa

Successivamente, verificare che nella destinazione il computer sia effettivamente protetto e gestito come previsto:

• Il tipo di dispositivo, la licenza e i prodotti installati corrispondono alla configurazione di destinazione prevista.
• Il gruppo di destinazione, le policy effettive, le eccezioni globali e gli elenchi di siti web sono corretti.
• Gli aggiornamenti dell’agente, un test di protezione autorizzato e le funzioni di risposta previste funzionano.
• Il comportamento di Update Cache, Message Relay e proxy è conforme all’account di destinazione.
• Il vecchio record nell’account di origine non viene confuso con la registrazione attiva nella destinazione.

L’ondata successiva, anch’essa di dimensioni ridotte, inizia solo quando il risultato API, gli eventi di audit e dell’endpoint e l’accettazione operativa coincidono.

Circoscrivere gli errori in modo sicuro

Il job rimane aperto

Se l’API corrente mostra uno stato non ancora completato, verificare innanzitutto che il computer sia online, possa raggiungere Sophos e che entrambe le finestre di migrazione siano ancora valide. Finché la migrazione è abilitata, un dispositivo offline può rimanere nella coda. Dopo un errore o una scadenza, l’endpoint viene reinserito manualmente nella coda con una nuova finestra di migrazione valida.

La migrazione non riesce

Per prima cosa, confrontare il motivo dell’errore restituito dall’API corrente con l’evento del computer e gli Audit Log di entrambi gli account. Quindi verificare il contesto del tenant, l’Endpoint ID, l’associazione del job, l’autorizzazione alla migrazione corrente e l’idoneità confermata del computer. Se l’errore non è chiaro, salvare entrambi gli ID job, l’Endpoint ID, il timestamp, i dati di correlazione API e un archivio SDU e trasmetterli a Sophos Support, senza segreti o token.

In caso di errore, la gestione non è stata trasferita correttamente e il dispositivo rimane nell’account di origine. Per una migrazione già riuscita, l’API documentata non attesta alcuna procedura automatica di annullamento, ripristino o rollback. Il ritorno viene pianificato come una nuova migrazione, confermata separatamente, oppure come una nuova registrazione.

La chiamata API viene rifiutata

Verificare che Bearer Token, X-Tenant-ID e host API regionale appartengano allo stesso account e che in tale account le API Credentials abbiano il ruolo Service Principal Super Admin. Il Bearer Token non deve essere confuso con il Migration Job Access Token del Receiving Job. Inoltre, Allow device migration deve essere ancora attivo in entrambi gli account.

Alternativa Windows: nuova registrazione con --registeronly

--registeronly non fa parte della procedura con Receiving Job e Sending Job e non sostituisce la migrazione API. L’opzione serve alla nuova registrazione Windows separata di un dispositivo già protetto quando Device Migration non è adatta o disponibile per il caso specifico e questo metodo è stato confermato in base all’attuale documentazione del programma di installazione Windows o da Sophos Support.

Si applicano prerequisiti specifici:

• Sul dispositivo Windows è presente un’installazione funzionante di Sophos Protection.
• Un programma di installazione SophosSetup.exe aggiornato e non modificato proviene da My Environment > Installers dell’account di destinazione.
• In conformità al prerequisito documentato per --registeronly, Tamper Protection è disattivata sul dispositivo.
• Il comando viene eseguito localmente o tramite distribuzione software con diritti di amministratore; il dispositivo deve poter raggiungere Sophos.

Sul dispositivo Windows, aprire il prompt dei comandi o PowerShell come amministratore e avviare il programma di installazione della destinazione:

.\SophosSetup.exe --registeronly

Il nome file e il percorso possono variare. Un pacchetto proveniente dall’account di origine non consentirebbe di raggiungere la destinazione prevista. Dopo il comando, si applicano le stesse verifiche operative nella destinazione descritte sopra; il solo completamento del processo del programma di installazione non costituisce una prova di successo.

L’opzione Windows non deve essere applicata a macOS o Linux. Per una nuova registrazione su altre piattaforme, utilizzare l’attuale procedura specifica documentata da Sophos oppure rivolgersi a Sophos Support. Se l’agente Windows esistente è danneggiato o è già stato rimosso, non è possibile utilizzare --registeronly. In tal caso, seguire la procedura supportata di riparazione o disinstallazione e successivamente eseguire una nuova installazione con il programma di installazione della destinazione. Per Windows, Disinstallare Sophos Endpoint con Tamper Protection attiva descrive la procedura di ripristino supportata.

Modifiche al registro, trucchi in modalità provvisoria, manipolazioni dei file MCS e Tenant ID impostati manualmente non sono procedure supportate per una migrazione o per il ritorno all’account di origine. Se --registeronly non riesce, verificare la provenienza e l’attualità del programma di installazione, i diritti di amministratore, la raggiungibilità Internet/proxy e lo stato dell’agente. Salvare i log di installazione e, se necessario, un archivio SDU prima di coinvolgere Sophos Support.

Completare l’ondata e conservare le prove

Dopo ogni ondata, confrontare l’elenco previsto con i risultati. Documentare:

• gli ID del Receiving Job e del Sending Job e l’associazione del job indicata nel risultato API;
• il vecchio Endpoint ID e, se restituito, quello nuovo;
• le informazioni di stato, temporali e di errore restituite dall’API corrente;
• la finestra di migrazione autorizzata, l’ambito dell’ondata e la persona responsabile;
• l’accettazione tecnica e operativa;
• il proprietario delle API Credentials utilizzate, ma nessun segreto, Bearer Token o Migration Job Access Token.

Dopo l’ultima ondata, disattivare Allow device migration o chiudere le autorizzazioni temporanee, eliminare le eccezioni temporanee e riportare tutti i controlli di protezione allo stato previsto. Non eliminare indiscriminatamente i vecchi oggetti di origine: verificare prima il risultato API, lo stato di proprietà e i requisiti di conservazione. Le prove relative a incidenti e audit rimangono archiviate separatamente in conformità alle disposizioni interne.

Domande frequenti