Magento-Migrations-Assistent entfernen

Wie eine Migration von Magento 1 zu Shopware 6 abläuft

Der Standardweg von Magento 1 nach Shopware 6 führt über den offiziellen Migrations-Assistenten. Dafür werden im frisch aufgesetzten Shopware-6-Shop zwei Plugins installiert: der Shopware Migrations-Assistent selbst und das Shopware Magento-Migration-Profil, das die Magento-spezifischen Datenstrukturen kennt und für Magento 1 wie Magento 2 zuständig ist.

In der Administration wird dann eine Verbindung zum alten Shop angelegt. Beim Magento-Profil heißt das: direkter Zugriff auf die Magento-Datenbank, denn anders als bei einer Shopware-zu-Shopware-Migration gibt es keine API-Anbindung. Anschließend wählt der Betreiber aus, welche Datenbereiche übernommen werden sollen, typischerweise Kunden, Produkte, Kategorien, Bestellungen und Medien. Der Assistent liest die Daten aus, übersetzt sie in das Shopware-Datenmodell und legt sie im neuen Shop an. Offene Zuordnungen wie Sprachen, Währungen, Kundengruppen oder Versandarten fragt er in einem Mapping-Schritt ab. Der Lauf lässt sich beliebig wiederholen, bis das Ergebnis stimmt, dann folgt der Go-live.

So weit die Theorie. In der Praxis funktioniert die Magento-Migration damit nicht optimal: Der Assistent übernimmt die Rohdaten, aber vieles kommt nicht oder nicht brauchbar an. Gewachsene Magento-Shops stecken voller Eigenheiten wie individueller Attribute, Preisregeln, CMS-Inhalte oder Plugin-Daten, für die es im Shopware-Datenmodell kein direktes Gegenstück gibt. Nach dem Durchlauf beginnt deshalb regelmäßig viel Handarbeit: Datenbereiche prüfen und nacharbeiten, Kategoriestrukturen und Attribute aufräumen, Inhalte neu aufbauen, URLs für die Suchmaschinen absichern. Die Migration mit dem Assistenten ist ein Startpunkt, kein Knopfdruck-Umzug.

Ein Haken zeigt sich zudem erst nach dem Umzug: Die beiden Migrations-Plugins müssen im Shop des Betreibers dauerhaft installiert und aktiv bleiben. Wer sie entfernt, sperrt alle Bestandskunden aus, die sich seit der Migration noch nicht angemeldet haben, deren erster Login im neuen Shop schlägt dann fehl. Aus einem Umzugswerkzeug werden so zwei Dauergäste, die bei jedem Shopware-Update mitgepflegt werden wollen.

Warum die Plugins nicht weg dürfen: die Passwörter

Magento und Shopware hashen Passwörter unterschiedlich, und ein Passwort-Hash lässt sich prinzipbedingt nicht in ein anderes Format konvertieren, ohne das Klartext-Passwort zu kennen. Die Migration übernimmt deshalb den originalen Magento-Hash und vermerkt am Kundendatensatz, mit welchem Alt-Verfahren er erzeugt wurde. Erst wenn sich der Kunde das erste Mal im neuen Shop anmeldet, liegt das Passwort kurz im Klartext vor: Shopware prüft es gegen den Alt-Hash und speichert es anschließend im eigenen, aktuellen Format neu.

Die Encoder für die Magento-Formate, in Shopware Legacy-Encoder genannt, bringt aber das Migrations-Plugin mit. Wird es deaktiviert, findet Shopware beim ersten Login eines noch nicht umgestellten Kunden keinen passenden Encoder und lehnt die Anmeldung mit einer Fehlermeldung ab. Und weil niemand vorhersagen kann, wann sich der letzte migrierte Kunde zum ersten Mal anmeldet, bleibt der komplette Migrations-Assistent samt Magento-Profil auf unbestimmte Zeit im System, obwohl von seinem Funktionsumfang nur noch ein winziger Ausschnitt gebraucht wird: vier kleine Passwort-Encoder.

Genau diese vier Funktionen als eigenständiges Plugin

Das Plugin ComWerftRemoveMigration löst das Dilemma auf die naheliegende Art: Es liefert ausschließlich die vier Passwort-Encoder, die migrierte Magento-Kunden für den ersten Login brauchen, und sonst nichts. Danach lassen sich SwagMigrationAssistant und SwagMigrationMagento deinstallieren.

Die vier Encoder decken alle Hash-Formate ab, die der Migrations-Assistent aus Magento übernimmt:

• Magento19 für Magento 1.9: dort können md5-, sha256-, sha512- und bcrypt-Hashes nebeneinander existieren, jeweils mit oder ohne Salt
• Magento2Md5 für Magento 2 mit Hash-Version 0 (md5 über Salt und Passwort)
• Magento2Sha256 für Magento 2 mit Hash-Version 1 (sha256 über Salt und Passwort)
• Magento2Argon2Id13 für Magento 2 mit Hash-Version 2 (Argon2id über die Sodium-Erweiterung von PHP)

Die Namen sind keine Kosmetik: Sie sind exakt die Werte, die der Migrations-Assistent seinerzeit am Kundendatensatz hinterlegt hat, und müssen deshalb dauerhaft stabil bleiben. Aus demselben Grund darf das Plugin nicht parallel zu SwagMigrationMagento laufen, denn beide registrieren Encoder unter denselben Namen, und einer würde den anderen stillschweigend überschreiben.

Version 0.2.0: aktuelle Shopware-Versionen und drei behobene Randfälle

Die gerade veröffentlichte Version 0.2.0 bringt das Plugin auf den aktuellen Stand: Es unterstützt Shopware 6.5, 6.6 und 6.7 mit PHP ab 8.1. Für Shops auf Shopware 6.4 bleibt Version 0.1.0 die richtige Wahl.

Interessanter als die Kompatibilität sind drei Fixes, die zeigen, wie viel Sorgfalt selbst in vier kleinen Encodern steckt:

Ein Argon2id-Hash mit ungültiger Salt-Länge führte bisher beim Login zu einer SodiumException und damit zu einem Serverfehler. Ein gespeicherter Hash darf einen Login-Versuch aber niemals in einen 500er verwandeln, richtig ist die abgelehnte Anmeldung. Die Salt-Länge wird jetzt vor dem Aufruf geprüft, und die Exception wird zusätzlich abgefangen.

Magento-2-Hashes ohne Versions-Segment erzeugten PHP-Warnungen im Error-Log. Solche Einträge können in Altdatenbeständen durchaus vorkommen, jetzt werden sie sauber als ungültig behandelt statt Log-Rauschen zu produzieren.

Außerdem sind die Passwort-Parameter mit dem PHP-Attribut SensitiveParameter markiert. Kommt es irgendwo im Login-Pfad zu einer Exception, erscheint das Klartext-Passwort damit nicht mehr in Stacktraces, die in Logs oder Monitoring-Systemen landen könnten.

Alle vier Encoder sind seit dieser Version mit Unit-Tests abgedeckt, gerade weil sich an Passwort-Prüfcode niemand ohne Sicherheitsnetz herantasten sollte.

Einbau in der richtigen Reihenfolge

Die Installation ist bewusst simpel gehalten:

1. Den Shopware Migrations-Assistenten (SwagMigrationAssistant) deaktivieren oder deinstallieren
2. Das Shopware Magento-Migration-Profil (SwagMigrationMagento) deaktivieren oder deinstallieren
3. Dieses Plugin installieren und aktivieren

So sieht der Zielzustand in der Erweiterungs-Übersicht aus: Das kleine Plugin ist aktiv, Migrations-Assistent und Magento-Profil sind nur noch als installierbare Einträge aus dem Store gelistet. Der Screenshot stammt aus der Zeit der Erstveröffentlichung auf Shopware 6.4, das Bild ist auf den aktuellen Versionen dasselbe.

Das Zeitfenster zwischen Schritt 2 und 3 kurz halten, denn in dieser Spanne würde der erste Login eines noch nicht umgestellten Kunden fehlschlagen. In einem Wartungsfenster oder direkt hintereinander ausgeführt ist das kein Thema.

Ob überhaupt noch Kunden mit Alt-Hashes im Bestand sind, verrät ein Blick in die Datenbank: Kundendatensätze, bei denen das Feld für den Legacy-Encoder noch gefüllt ist, haben sich seit der Migration nie angemeldet. Bei einem Shop, der schon Jahre auf Shopware 6 läuft, kann diese Zahl klein genug sein, dass sich die Frage stellt, ob diese Karteileichen überhaupt noch einen Login brauchen. Solange die Antwort nicht eindeutig nein lautet, ist das Plugin der sichere Weg.

Entstanden in echten Migrationsprojekten

Das Plugin ist kein Schreibtisch-Produkt. Die Encoder liefen zuerst vor rund fünf Jahren in zwei realen Magento-zu-Shopware-Migrationen, wo sich die Frage nach dem festsitzenden Migrations-Assistenten zum ersten Mal stellte. Weil das Problem jeden migrierten Shop betrifft, wurde daraus ein eigenständiges Plugin: Version 0.1.0 erschien im April 2022 für Shopware 6.4 im Shopware Store. Mit Version 0.2.0 hat es jetzt das Update auf die aktuellen Shopware-Versionen erhalten, zusammen mit den oben beschriebenen Härtungen.

Das Plugin ist Open Source unter MIT-Lizenz, der Code liegt auf GitHub, Bugs und Fragen nimmt der Issue-Tracker entgegen. Im Shopware Store ist es kostenlos verfügbar.

Mehr zur Migration selbst, vom Datenmodell bis zur SEO-sicheren URL-Übernahme, steht auf der Seite zur Shopware-Migration.