Zum Hauptinhalt springen

Benutzermigration

Logto unterstützt die manuelle Migration bestehender Benutzer von einer anderen Plattform. Diese Anleitung zeigt dir, wie du bestehende Benutzer über die Management API importierst und erläutert Dinge, die du vor der Migration beachten solltest.

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.

Passwort-Hashing​

Logto verwendet Argon2, um das Passwort des Benutzers zu hashen, 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 Anmelden 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.

Das Format des JSON-Strings ist wie folgt:

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

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

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

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

Dies entspricht folgendem Code:

const hash = crypto.createHash('sha256');
hash.update('salt123' + 'password123');
const expectedHashedValue = hash.digest('hex');

Schritte zur Migration​

  1. 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"
      }
    ]

  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 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),
          });
          // Sleep for a while to avoid rate limit
          await new Promise((resolve) => setTimeout(resolve, 200));
        } catch (error) {
          console.error(`Failed to import user ${user.username}: ${error.message}`);
        }
      }
    };

    importUsers();

Bitte beachte, dass der API-Endpunkt einer Rate-Limitierung unterliegt. Du solltest zwischen den einzelnen Anfragen eine Pause einlegen, 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.

Eine allgemeine Anleitung zur Migration deiner bestehenden Benutzerdatenbank zu Logto