Benutzermigration

Logto unterstützt sowohl die Massenmigration als auch die Just-in-Time-Migration bestehender Benutzer aus einem anderen Identitätssystem. Diese Anleitung erklärt, wie du Benutzer in großen Mengen über die Management API importierst und was du vor der Migration beachten 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 Rest 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:

Basisdaten: Dies sind die Basisinformationen aus dem Benutzerprofil, du kannst die Daten aus deinem bestehenden Benutzerprofil zuordnen.
Benutzerdefinierte Daten: Speichert zusätzliche Benutzerinformationen, du kannst dies verwenden, um Felder zu speichern, die nicht den Basisdaten zugeordnet werden können.
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 für jeden über die Management API erstellten Benutzer eine zufällige ID. 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 in selbstgehostetem Logto unterstützt. Logto Cloud lehnt Anfragen mit id mit 501 request.feature_not_supported ab, da Benutzer-IDs mandantenübergreifend geteilt werden.

Passwort-Hashing

Logto verwendet Argon2 zum Hashen des Benutzerpassworts und unterstützt zur 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 das passwordDigest ein JSON-String, der den Hash-Algorithmus und andere 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 beispielsweise SHA256 mit Salt verwendest, kannst du das Passwort im folgenden Format speichern:

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

Das entspricht folgendem Code:

const hash = crypto.createHash('sha256');
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 das 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\"]"
}

Schritte zur Migration

Benutzerdaten vorbereiten
Du solltest zunächst die Benutzerdaten aus deiner bestehenden Plattform exportieren und dann die Benutzerinformationen auf das Logto-Benutzerschema abbilden. Wir empfehlen, die abgebildeten Daten im JSON-Format vorzubereiten. Hier ein Beispiel für die Benutzerdaten:
```
[
  {
    "username": "user1",
    "passwordDigest": "password-encrypted",
    "passwordAlgorithm": "SHA256"
  },
  {
    "username": "user2",
    "passwordDigest": "password-encrypted",
    "passwordAlgorithm": "SHA256"
  }
]
```
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.
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.

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 das 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 einer Rate-Limitierung unterliegt. 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.

Allgemeine Richtlinien zur Migration deiner bestehenden Benutzerdatenbank zu Logto

Wähle eine Migrationsstrategie​

Benutzerschema​

Vorhandene Benutzer-IDs beibehalten​

Passwort-Hashing​

Allgemeines Legacy-Format​

PBKDF2-Unterstützung​

Schritte zur Migration​

Verwandte Ressourcen​