Benutzermigration

Logto unterstützt sowohl die Massenmigration als auch die Just-in-Time-Migration bestehender Benutzer aus einem anderen Identitätssystem. In dieser Anleitung wird erklärt, wie du Benutzer in großen Mengen über die Management API importierst und worauf du vor der Migration achten solltest.

Wähle eine Migrationsstrategie

Strategie	Wähle sie, wenn	So funktioniert es
Massenmigration	Du kannst die Benutzerdatensätze und Passwort-Hashes in einem von Logto unterstützten Format exportieren.	Importiere die Benutzer vor dem Wechsel über die Management API, wie im weiteren Verlauf dieser Anleitung beschrieben.
Just-in-Time-Migration	Du musst Passwörter gegen das bestehende System prüfen, kannst keine kompatiblen Passwort-Hashes exportieren oder möchtest aktive Benutzer schrittweise migrieren.	Konfiguriere eine Post First-Factor Verification Action. Beim ersten Passwort-Login des Benutzers prüft Logto die Zugangsdaten über deine Action, erstellt oder aktualisiert den Benutzer und speichert einen neuen lokalen Passwort-Hash.

Die Just-in-Time-Migration hält den alten Authentifizierungsdienst im Anmeldeprozess, bis die Benutzer migriert sind. Verwende einen schnellen, zuverlässigen HTTPS-Endpunkt und halte ihn während der Migrationsphase verfügbar.

Benutzerschema

Bevor wir beginnen, werfen wir einen Blick auf das Benutzerschema in Logto. Es gibt 3 Teile des Benutzerschemas, die du kennen solltest:

1. Basisdaten: Dies sind die Basisinformationen aus dem Benutzerprofil, du kannst die Daten aus deinem bestehenden Benutzerprofil zuordnen.
2. Benutzerdefinierte Daten: Speichert zusätzliche Benutzerinformationen, du kannst dies verwenden, um Felder zu speichern, die nicht den Basisdaten zugeordnet werden können.
3. Soziale Identitäten: Speichert die Benutzerinformationen, die durch Social Sign-In abgerufen wurden.

Du kannst eine Zuordnung erstellen, um die Benutzerinformationen aus deinem bestehenden Benutzerprofil den Basisdaten und benutzerdefinierten Daten zuzuordnen. Für Social Sign-In sind zusätzliche Schritte erforderlich, um die sozialen Identitäten zu importieren. Siehe dazu die API von Soziale Identität mit Benutzer verknüpfen.

Vorhandene Benutzer-IDs beibehalten

Standardmäßig generiert Logto eine zufällige ID für jeden Benutzer, der über die Management API erstellt wird. Wenn deine Anwendung bereits Benutzer-IDs vom vorherigen Identitätsanbieter speichert, kannst du diese beibehalten, indem du eine optionale id im create user-Request-Body übergibst. So vermeidest du eine Zuordnungstabelle zwischen alten und neuen IDs.

Die ID muss zwischen 1 und 128 Zeichen lang sein und darf Buchstaben, Zahlen sowie _ - . @ : + = | enthalten. Dies deckt gängige Formate wie auth0|5f7c8ec7c33c6c004bbafe82, google-oauth2|103547991597142817347, UUIDs, user_01H8MZ2QK3V4X5Y6Z7 und E-Mail-Adressen ab. Zeichen, die in URL-Pfaden nicht zulässig sind (Leerzeichen, /, ?, #, %, \), werden mit 400 abgelehnt, da die ID in /api/users/{userId} verwendet wird. Ist die ID bereits vergeben, schlägt die Anfrage mit 422 user.id_already_in_use fehl.

{
  "id": "auth0|5f7c8ec7c33c6c004bbafe82",
  "primaryEmail": "john.doe@example.com",
  "passwordAlgorithm": "Bcrypt",
  "passwordDigest": "$2b$10$..."
}

hinweis:

Benutzerdefinierte Benutzer-IDs werden nur im selbst gehosteten Logto unterstützt. Logto Cloud lehnt Anfragen mit id mit 501 request.feature_not_supported ab, da Benutzer-IDs mandantenübergreifend eindeutig sein müssen.

Passwort-Hashing

Logto verwendet Argon2 zum Hashen des Benutzerpassworts und unterstützt zur Erleichterung der Migration auch andere Algorithmen wie MD5, SHA1, SHA256 und Bcrypt. Diese Algorithmen gelten als unsicher, die entsprechenden Passwort-Hashes werden beim ersten erfolgreichen Login des Benutzers auf Argon2 migriert.

Wenn du andere Hashing-Algorithmen oder Salt verwendest, kannst du passwordAlgorithm auf Legacy setzen. Dadurch kannst du jeden von Node.js unterstützten Hash-Algorithmus verwenden. Die Liste der unterstützten Algorithmen findest du in der Node.js Crypto-Dokumentation. In diesem Fall ist passwordDigest ein JSON-String, der den Hash-Algorithmus und weitere algorithmusspezifische Parameter enthält.

Allgemeines Legacy-Format

Das Format des JSON-Strings ist wie folgt:

["hash_algorithm", ["argument1", "argument2", ...], "expected_hashed_value"]

Du kannst @ als Platzhalter für den tatsächlichen Passwortwert in den Argumenten verwenden.

Wenn du z. B. SHA256 mit einem Salt verwendest, kannst du das Passwort im folgenden Format speichern:

["sha256", ["salt123", "@"], "c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e"]

Das entspricht folgendem Code:

const hash = crypto.createHash('sha256');
// Salt und Passwort werden zusammengefügt
hash.update('salt123' + 'password123');
const expectedHashedValue = hash.digest('hex');

PBKDF2-Unterstützung

Logto unterstützt speziell PBKDF2.

Um mit PBKDF2 gehashte Passwörter zu migrieren, setze passwordAlgorithm auf Legacy und formatiere passwordDigest wie folgt:

["pbkdf2", ["salt", "1000", "20", "sha512", "@"], "expected_hashed_value"]

Die Parameter sind:

• salt: Der beim ursprünglichen Hashing verwendete Salt-Wert
• iterations: Anzahl der Iterationen (z. B. "1000")
• keylen: Länge des abgeleiteten Schlüssels in Bytes (z. B. "20")
• digest: Die verwendete Hashfunktion (z. B. "sha512", "sha256", "sha1")
• @: Platzhalter für den tatsächlichen Passwortwert
• expected_hashed_value: Das erwartete Hash-Ergebnis als Hex-String

Beispiel für ein Migrations-Payload:

{
  "username": "john_doe",
  "primaryEmail": "john.doe@example.com",
  "passwordAlgorithm": "Legacy",
  "passwordDigest": "[\"pbkdf2\", [\"mySalt123\", \"1000\", \"20\", \"sha512\", \"@\"], \"c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e\"]"
}

Firebase Scrypt-Unterstützung

Logto unterstützt auch den von Firebase Authentication verwendeten modifizierten Scrypt-Algorithmus. Setze passwordAlgorithm auf Legacy und formatiere passwordDigest wie folgt:

[
  "firebase-scrypt",
  ["salt", "signer_key", "salt_separator", "rounds", "mem_cost", "@"],
  "expected_hashed_value"
]

Die Parameter sind:

• salt: Das salt des Benutzers aus firebase auth:export
• signer_key, salt_separator, rounds, mem_cost: Die Passwort-Hash-Parameter deines Projekts, zu finden in der Firebase-Konsole unter Authentication > Users > ⋮ > Password hash parameters
• @: Platzhalter für den tatsächlichen Passwortwert
• expected_hashed_value: Das passwordHash des Benutzers aus dem Export, im Standard-Base64. Wenn du Benutzer mit dem Firebase Admin SDK ausliest, konvertiere das URL-sichere Base64 (-, _) zuerst in Standard-Base64 (+, /).

passwordDigest ist auf 256 Zeichen begrenzt, daher solltest du es als kompaktes JSON ohne Leerzeichen serialisieren (z. B. mit JSON.stringify).

Benutzer, die mit einem Nicht-Scrypt-Hash in Firebase importiert wurden und sich seitdem nicht angemeldet haben, werden mit leerem passwordHash und salt exportiert. Importiere sie mit ihrem ursprünglichen Hash, falls du ihn noch hast, oder bitte sie, ihr Passwort zurückzusetzen.

Beispiel für ein Migrations-Payload:

{
  "username": "john_doe",
  "primaryEmail": "john.doe@example.com",
  "passwordAlgorithm": "Legacy",
  "passwordDigest": "[\"firebase-scrypt\",[\"42xEC+ixf3L2lw==\",\"jxspr8Ki0RYycVU8zykbdLGjFQ3McFUH0uiiTvC8pVMXAn210wjLNmdZJzxUECKbm0QsEmYUSDzZvpjeJ9WmXA==\",\"Bw==\",\"8\",\"14\",\"@\"],\"lSrfV15cpx95/sZS2W9c9Kp6i/LVgQNDNC/qzrCnh1SAyZvqmZqAjTdn3aoItz+VHjoZilo78198JAdRuid5lQ==\"]"
}

Schritte zur Migration

1. Benutzerdaten vorbereiten
   Exportiere zunächst die Benutzerdaten aus deiner bestehenden Plattform und ordne die Benutzerinformationen dem Logto-Benutzerschema zu. Wir empfehlen, die zugeordneten Daten im JSON-Format vorzubereiten. Hier ein Beispiel für Benutzerdaten:

   [
     {
       "username": "user1",
       "passwordDigest": "password-encrypted",
       "passwordAlgorithm": "SHA256"
     },
     {
       "username": "user2",
       "passwordDigest": "password-encrypted",
       "passwordAlgorithm": "SHA256"
     }
   ]

2. Logto-Tenant erstellen
   Du musst einen Tenant in Logto einrichten. Du kannst entweder Logto Cloud oder Logto OSS verwenden. Falls du dies noch nicht getan hast, siehe die Anleitung Logto Cloud einrichten.

3. Verbindung zur Management API einrichten
   Wir verwenden die Management API, um die Benutzerdaten zu importieren. Siehe Management API, um zu erfahren, wie du die Verbindung in deiner Entwicklungsumgebung einrichtest.

4. Benutzerdaten importieren
   Es wird empfohlen, ein Skript zu erstellen, das die Benutzerdaten einzeln importiert. Wir rufen die create user-API auf, um die Benutzerdaten zu importieren. Hier ein Beispiel für ein Skript:

   const users = require('./users.json');
   
   const importUsers = async () => {
     for (const user of users) {
       try {
         await fetch('https://[tenant_id].logto.app/api/users', {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json',
             Authorization: 'Bearer [your-access-token]',
           },
           body: JSON.stringify(user),
         });
         // Kurze Pause, um das Rate Limit nicht zu überschreiten
         await new Promise((resolve) => setTimeout(resolve, 200));
       } catch (error) {
         console.error(`Fehler beim Importieren des Benutzers ${user.username}: ${error.message}`);
       }
     }
   };
   
   importUsers();

Beachte, dass der API-Endpunkt rate-limitiert ist. Du solltest zwischen den Anfragen eine Pause einbauen, um das Rate Limit nicht zu überschreiten. Siehe unsere Seite zu Rate Limits für Details.

Wenn du eine große Menge an Benutzerdaten (100k+ Benutzer) hast, kannst du uns kontaktieren, um das Rate Limit zu erhöhen.

Verwandte Ressourcen

Allgemeine Richtlinien zur Migration deiner bestehenden Benutzerdatenbank zu Logto