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 verifizieren, 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 überprü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 Legacy-Authentifizierungsdienst im Anmeldeprozess, bis die Benutzer migriert sind. Verwende einen schnellen, zuverlässigen HTTPS-Endpunkt und halte ihn während des Migrationszeitraums 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.

Passwort-Hashing

Logto verwendet Argon2 zum Hashen des Benutzerpassworts und unterstützt außerdem andere Algorithmen wie MD5, SHA1, SHA256 und Bcrypt zur Erleichterung der Migration. 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 algorithmenspezifische 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 zum Beispiel 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 das passwordDigest wie folgt:

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

Die Parameter sind:

salt: Der im 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 Hexadezimal-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 zuerst die Benutzerdaten aus deiner bestehenden Plattform exportieren und dann die Benutzerinformationen dem Logto-Benutzerschema zuordnen. Wir empfehlen, die zugeordneten Daten im JSON-Format vorzubereiten. Hier ist 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 vorzubereiten, um die Benutzerdaten einzeln zu importieren. Wir rufen die create user API auf, um die Benutzerdaten zu importieren. Hier ist 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(`Benutzerimport für ${user.username} fehlgeschlagen: ${error.message}`);
    }
  }
};

importUsers();

Bitte beachte, dass der API-Endpunkt einer Rate-Limitierung unterliegt. Du solltest zwischen den einzelnen 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 hast (100.000+ Benutzer), 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​

Passwort-Hashing​

Allgemeines Legacy-Format​

PBKDF2-Unterstützung​

Schritte zur Migration​

Verwandte Ressourcen​