Sophos-Geräte zwischen Central-Tenants migrieren

Bei einer Firmenübernahme, Tenant-Konsolidierung oder falschen Kundenzuordnung werden verwaltete Computer mit Device Migration von einem sendenden in ein empfangendes Sophos-Fusion-Konto verschoben. Der reguläre Ablauf verwendet die Endpoint API: Zuerst wird im Ziel ein Receiving Job erstellt, danach im Quellkonto der zugehörige Sending Job gestartet.

Geltungsbereich: Die aktuelle Sophos-Hilfe beschreibt diesen Ablauf für «computers». Welche Betriebssysteme, Gerätetypen, Agent-Versionen und installierten Produkte im konkreten Tenant zugelassen sind, muss vor dem Rollout mit der aktuellen Endpoint-API-Dokumentation, der Antwort des Live-Tenants oder Sophos Support bestätigt werden. Die allgemeinen Endpoint-API-Typen sind keine Migrations-Freigabeliste. Access Points und Switches haben eigene Abläufe und gehören nicht in diesen API-Workflow.

Was Device Migration leistet – und was separat vorbereitet wird

Device Migration ändert die Registrierung und das verwaltende Konto des Computers. Nach einer erfolgreichen Migration wird er vom empfangenden Konto verwaltet. Schlägt die Migration fehl, bleibt er gemäss Sophos beim sendenden Konto verwaltet.

Die öffentliche Dokumentation beschreibt die Übertragung von Policies, Gruppen, globalen Ausnahmen, Website-Listen, Lizenzen, Produktzuweisungen, Alerts, Untersuchungen oder Audit-Historie nicht. Daraus lässt sich weder ableiten, dass diese Daten automatisch übertragen werden, noch dass sie vollständig im Quellkonto verbleiben. Deshalb wird die Zielkonfiguration vorbereitet und der wirksame Zustand nach der Migration geprüft.

Voraussetzungen und Pilot planen

Vor dem ersten Job werden Quelle und Ziel inventarisiert und ein kleiner, repräsentativer Pilot festgelegt. Kritische Server, VDI-Systeme, Homeoffice-Geräte, isolierte Computer und selten verbundene Notebooks kommen in separate Wellen.

Folgende Voraussetzungen müssen erfüllt sein:

• Die ausführende Person besitzt in beiden Konten die Sophos-Rolle Admin.
• Für beide Konten existieren getrennte API Credentials mit der Credential-Rolle Service Principal Super Admin. Ein menschlicher Super Admin muss diese Credentials erstellen und verwalten; die Rolle Admin allein reicht dafür nicht aus.
• Tenant-ID und regionaler API-Host sind für beide Konten bekannt. Sie werden über den regulären Sophos-API-Setup ermittelt und nicht geraten.
• Die zu migrierenden Endpoint-IDs stammen aus dem sendenden Konto und die Eignung jedes Pilots ist im Live-Tenant beziehungsweise mit Sophos Support bestätigt.
• Im Ziel sind passende Lizenzen, Policies, Gruppen, Ausnahmen und Website-Listen vorbereitet.
• Update Caches, Message Relays und Proxies des Zielkontos sind vom jeweiligen Gerätestandort erreichbar.
• Isolierungen, offene Alerts und laufende Untersuchungen sind dokumentiert; benötigte Incident- und Audit-Nachweise sind vor dem Wechsel gesichert.

API Client Secret und daraus bezogener Bearer Token gehören jeweils zu einem Konto. Der später vom Receiving Job ausgegebene Migration Job Access Token ist ein anderes Geheimnis. Client Secrets, Bearer Tokens und Migration Job Access Tokens gehören weder in Screenshots noch in Tickets, Shell-History oder Betriebsprotokolle.

Device Migration in beiden Konten freigeben

Zuerst meldet man sich im sendenden und danach im empfangenden Konto an und öffnet jeweils Global Settings > Platform > Device Migration:

1. Allow device migration aktivieren.
2. Ein möglichst kurzes, für Pilot oder Welle ausreichendes Zeitlimit setzen.
3. Vor dem Jobstart nochmals prüfen, dass das Fenster in beiden Konten aktiv ist.

Ist die Option gesperrt, stammt die Vorgabe aus den globalen Einstellungen des Partners oder Enterprise-Administrators. Der Job wird dann nicht mit Workarounds umgangen; die zuständige übergeordnete Administration muss die Freigabe erteilen.

Migration mit Receiving Job und Sending Job durchführen

Die aktuelle Sophos-Hilfe zu Device Migration beschreibt die Reihenfolge der Jobs. Der Endpoint Migration API Guide führt zur aktuellen API-Referenz. Die genaue Request-Struktur, Feldbelegung und aktuelle Mengenbegrenzung wird direkt vor der Ausführung in der aktuellen Endpoint-API-Definition geprüft. Historische Payloads oder Limits werden nicht ungeprüft übernommen. Dabei gilt folgende Reihenfolge:

1. Receiving Job im Ziel erstellen

Das Operationsmuster ist POST /endpoint/v1/migrations. Der Aufruf verwendet den regionalen API-Host und die Credentials des empfangenden Kontos. Er sendet den Bearer Token im Header Authorization, die ID des empfangenden Kontos im Header X-Tenant-ID und bei einem JSON-Body den Header Content-Type: application/json.

Der Body bezeichnet das sendende Konto und die bestätigten Geräte der Pilotphase beziehungsweise Welle. Im historischen Schema heissen diese Felder fromTenant und endpoints; ob sie im Live-Schema weiterhin genau so heissen und beide in diesem Schritt erforderlich sind, muss vor dem Lauf bestätigt werden.

Aus der Antwort sichert man:

• die ID des Receiving Jobs;
• den Migration Job Access Token für den zugehörigen Sending Job;
• ein von der aktuellen API ausgegebenes Ablaufdatum, falls vorhanden.

Die Job-ID darf ins Änderungsprotokoll. Der Migration Job Access Token wird nur über einen geschützten Secret-Kanal an die Person oder Automation übergeben, welche den Sending Job anlegt, und nicht dauerhaft protokolliert.

2. Sending Job in der Quelle starten

Danach authentifiziert man sich separat im sendenden Konto. Das Operationsmuster ist PUT /endpoint/v1/migrations/{receivingMigrationJobId}. Im Pfad steht die Receiving-Job-ID. Der Aufruf sendet den Bearer Token im Header Authorization und die ID des sendenden Kontos im Header X-Tenant-ID; bei einem JSON-Body kommt Content-Type: application/json hinzu.

Der Sending Job verwendet:

• die bestätigte Liste der Endpoint-IDs aus dem Quellkonto;
• die ID des zuvor erstellten Receiving Jobs;
• dessen Migration Job Access Token.

Das historische Schema nennt die Body-Felder token und endpoints. Auch diese Namen und die aktuelle Antwortstruktur werden vor dem Lauf in der Live-Definition bestätigt.

Mit dem Sending Job startet die Migration. Vor dem Absenden werden Tenant-Kontext, Endpoint-Liste und Wellenumfang nochmals geprüft. Ein Token oder eine Job-ID aus einem anderen Lauf darf nicht wiederverwendet werden. Die von der aktuellen API zurückgegebene Sending-Job-ID wird zusammen mit der Receiving-Job-ID festgehalten; ein Ablaufdatum wird nur erfasst, falls die Live-Antwort eines liefert.

3. Status und Warteschlange überwachen

Der Fortschritt wird mit GET /endpoint/v1/migrations/{migrationJobId}/endpoints abgefragt. Der Aufruf erfolgt für den jeweils relevanten Sending- und Receiving-Job im Kontext des sendenden beziehungsweise empfangenden Kontos, jeweils mit dessen Bearer Token und X-Tenant-ID. Bei mehreren Ergebnisseiten werden alle Seiten abgefragt und pro angeforderter Endpoint-ID abgeglichen. Optional zeigt GET /endpoint/v1/settings/migration, ob die Migration im jeweiligen Konto freigegeben ist.

Die aktuelle Live-Definition bestimmt die Statuswerte und Detailfelder. Das historische API-Schema verwendete pending, succeeded und failed; es lieferte je nach Ergebnis unter anderem eine neue Endpoint-ID, Zeitangaben und einen Fehlergrund. Diese Namen sind Orientierungshilfen, keine Zusage des aktuellen Schemas. Gesichert werden die tatsächlich ausgegebenen Werte und Felder.

Computer bleiben bis zu 14 Tage in der Migrationswarteschlange. Ein offline stehender Computer muss innerhalb dieses Zeitraums online kommen. Ein kürzer eingestelltes Migrationsfenster kann den verfügbaren Zeitraum zusätzlich begrenzen. Bleibt das Gerät länger offline und die Migration läuft ab, schlägt sie fehl und muss durch einen Administrator manuell neu in die Migration eingereiht werden.

Ein ausstehendes Offline-Gerät wird nicht vorsorglich deinstalliert oder mit lokalen Tenant-ID-Änderungen bearbeitet. Zuerst wird die Verbindung innerhalb des gültigen Fensters wiederhergestellt. Bei einem fehlgeschlagenen Versuch bleibt das Gerät vom Quellkonto verwaltet.

Erfolg in Quelle, Ziel und am Gerät prüfen

Ein API-Status allein ist kein vollständiger Abnahmenachweis. Vor der nächsten Welle werden die Resultate über beide Konten und den Computer abgeglichen.

Offizielle Migrationsnachweise

1. Im Audit Log des sendenden Kontos ist das Ereignis Send endpoints to another tenant vorhanden.
2. Im Event des erfolgreich migrierten Computers steht Device registered with new account . It’s now managed by that account.
3. Bei einem fehlgeschlagenen Computer steht stattdessen Device failed to register with new account . It continues to be managed by this account.
4. Im Audit Log des empfangenden Kontos ist Allow endpoints to migrate to this tenant vorhanden.
5. Unter My Environment > Computers & Servers im Ziel ist der Computer registriert, einem Benutzer zugewiesen und aktuell.
6. Die angeforderten Endpoint-IDs sind lückenlos den API-Ergebnissen zugeordnet; falls ausgegeben, wird auch die neue Endpoint-ID dokumentiert.

Betriebliche Abnahme

Anschliessend wird geprüft, ob der Computer im Ziel tatsächlich wie geplant geschützt und betrieben wird:

• Gerätetyp, Lizenz und installierte Produkte entsprechen der vorgesehenen Zielkonfiguration.
• Zielgruppe, effektive Policies, globale Ausnahmen und Website-Listen sind korrekt.
• Agent-Updates, ein freigegebener Schutztest und die vorgesehenen Response-Funktionen funktionieren.
• Update Cache, Message Relay und Proxy-Verhalten passen zum Zielkonto.
• Der alte Datensatz im Quellkonto wird nicht mit der aktiven Zielregistrierung verwechselt.

Erst wenn API-Resultat, Audit- und Endpoint-Events sowie die betriebliche Abnahme übereinstimmen, beginnt die nächste kleine Welle.

Fehler sicher eingrenzen

Job bleibt offen

Zeigt die aktuelle API einen noch nicht abgeschlossenen Zustand, prüft man zuerst, ob der Computer online ist, Sophos erreicht und beide Migrationsfenster noch gültig sind. Solange die Migration freigegeben ist, darf ein offline stehendes Gerät in der Warteschlange bleiben. Nach dem Fehlschlag oder Ablauf wird der Endpoint mit einem neuen, gültigen Migrationsfenster manuell erneut eingereiht.

Migration schlägt fehl

Zuerst wird ein von der aktuellen API ausgegebener Fehlergrund mit dem Event des Computers sowie den Audit Logs beider Konten abgeglichen. Danach prüft man Tenant-Kontext, Endpoint-ID, Job-Zuordnung, aktuelle Migrationsfreigabe und die für diesen Computer bestätigte Eignung. Bei einem unklaren Fehler werden beide Job-IDs, Endpoint-ID, Zeitstempel, API-Korrelationsdaten und ein SDU-Archiv gesichert und an Sophos Support übergeben – ohne Secrets oder Tokens.

Bei einem Fehlschlag wurde die Verwaltung nicht erfolgreich übertragen; das Gerät bleibt beim Quellkonto. Für eine bereits erfolgreiche Migration ist in der dokumentierten API kein automatischer Cancel-, Undo- oder Rollback-Ablauf belegt. Ein Wechsel zurück wird als neue, separat bestätigte Migration beziehungsweise Neuregistrierung geplant.

API-Aufruf wird abgewiesen

Man kontrolliert, ob Bearer Token, X-Tenant-ID und regionaler API-Host zum selben Konto gehören und ob die API Credentials dort die Rolle Service Principal Super Admin besitzen. Der Bearer Token darf nicht mit dem Migration Job Access Token des Receiving Jobs verwechselt werden. Ausserdem muss Allow device migration noch in beiden Konten aktiv sein.

Windows-Alternative: mit --registeronly neu registrieren

--registeronly gehört nicht zum Ablauf mit Receiving und Sending Job und ersetzt die API-Migration nicht. Der Schalter dient der separaten Windows-Neuregistrierung eines bereits geschützten Geräts, wenn Device Migration für den konkreten Fall nicht geeignet oder nicht verfügbar ist und dieser Weg anhand der aktuellen Windows-Installer-Dokumentation oder durch Sophos Support bestätigt wurde.

Dafür gelten eigene Voraussetzungen:

• Auf dem Windows-Gerät ist eine funktionsfähige Sophos-Protection-Installation vorhanden.
• Ein aktueller, unveränderter SophosSetup.exe-Installer stammt unter My Environment > Installers aus dem Zielkonto.
• Gemäss der dokumentierten Voraussetzung für --registeronly ist Tamper Protection auf dem Gerät ausgeschaltet.
• Der Befehl läuft lokal oder über Softwareverteilung mit Administratorrechten; das Gerät muss Sophos erreichen können.

Auf dem Windows-Gerät wird eine Eingabeaufforderung oder PowerShell als Administrator geöffnet und der Ziel-Installer gestartet:

.\SophosSetup.exe --registeronly

Dateiname und Pfad können abweichen. Ein Paket aus dem Quellkonto würde das Ziel verfehlen. Nach dem Befehl gelten dieselben betrieblichen Zielprüfungen wie oben; ein beendeter Installer-Prozess allein ist kein Erfolgsnachweis.

Der Windows-Schalter darf nicht auf macOS oder Linux übertragen werden. Für eine Neuregistrierung auf anderen Plattformen wird der aktuelle, von Sophos dokumentierte Plattformablauf oder Sophos Support verwendet. Ist der vorhandene Windows-Agent beschädigt oder bereits entfernt, kann --registeronly nicht verwendet werden. Dann folgt der unterstützte Reparatur- beziehungsweise Deinstallationsweg und anschliessend eine Neuinstallation mit dem Ziel-Installer. Für Windows beschreibt Sophos Endpoint mit aktiviertem Manipulationsschutz deinstallieren das unterstützte Wiederherstellungsverfahren.

Registry-Änderungen, Safe-Mode-Tricks, Manipulationen an MCS-Dateien und manuell gesetzte Tenant-IDs sind keine unterstützten Verfahren für eine Migration oder Rückkehr zum Quellkonto. Schlägt --registeronly fehl, werden Herkunft und Aktualität des Installers, Administratorrechte, Internet-/Proxy-Erreichbarkeit und Agent-Zustand geprüft. Installationslogs und bei Bedarf ein SDU-Archiv werden gesichert, bevor Sophos Support eingeschaltet wird.

Welle abschliessen und Nachweise sichern

Nach jeder Welle werden Soll-Liste und Resultate abgeglichen. Dokumentiert werden:

• Receiving- und Sending-Job-ID sowie die im API-Ergebnis ausgewiesene Job-Zuordnung;
• alte und, falls ausgegeben, neue Endpoint-ID;
• die von der aktuellen API ausgegebenen Status-, Zeit- und Fehlerangaben;
• freigegebenes Migrationsfenster, Wellenumfang und verantwortliche Person;
• technische und betriebliche Abnahme;
• Eigentümer der verwendeten API Credentials, aber keine Secrets, Bearer Tokens oder Migration Job Access Tokens.

Nach der letzten Welle werden Allow device migration beziehungsweise die zeitlich begrenzten Freigaben geschlossen, temporäre Ausnahmen bereinigt und alle Schutzkontrollen wieder in den vorgesehenen Zustand versetzt. Alte Quellobjekte werden nicht pauschal gelöscht: Zuerst werden API-Ergebnis, Eigentumsstatus und Aufbewahrungsanforderungen geprüft. Incident- und Audit-Nachweise bleiben gemäss den internen Vorgaben separat archiviert.

Häufige Fragen