Migration des utilisateurs

Logto prend en charge la migration des utilisateurs existants depuis un autre système d'identité, que ce soit en masse ou en mode just-in-time. Ce guide explique comment importer des utilisateurs en masse via l’API de gestion (Management API) et ce qu’il faut prendre en compte avant de migrer.

Choisir une stratégie de migration

Stratégie	À choisir lorsque	Fonctionnement
Migration en masse	Vous pouvez exporter les enregistrements utilisateurs et les empreintes de mots de passe dans un format pris en charge par Logto.	Importez les utilisateurs avant la bascule via la Management API, en suivant le reste de ce guide.
Migration just-in-time	Vous devez vérifier les mots de passe auprès du système existant, ne pouvez pas exporter des empreintes compatibles, ou souhaitez migrer progressivement les utilisateurs actifs.	Configurez une Action post-vérification du premier facteur. Lors de la première connexion par mot de passe de l’utilisateur, Logto vérifie les identifiants via votre Action, crée ou met à jour l’utilisateur, et stocke une nouvelle empreinte locale du mot de passe.

La migration just-in-time maintient le service d’authentification hérité dans le chemin de la requête de connexion jusqu’à ce que les utilisateurs soient migrés. Utilisez un point de terminaison HTTPS rapide et fiable et gardez-le disponible pendant la période de migration.

Schéma utilisateur

Avant de commencer, examinons le schéma utilisateur dans Logto. Il y a 3 parties du schéma utilisateur à connaître :

Données de base : informations de base du profil utilisateur, vous pouvez faire correspondre ces données avec celles de votre profil utilisateur existant.
Données personnalisées : stocke des informations utilisateur supplémentaires, vous pouvez utiliser cela pour stocker des fichiers qui ne correspondent pas aux données de base.
Identités sociales : stocke les informations utilisateur récupérées lors de la connexion sociale.

Vous pouvez créer une correspondance entre les informations de votre profil utilisateur existant et les données de base et données personnalisées. Pour la connexion sociale, des étapes supplémentaires sont nécessaires pour importer les identités sociales ; veuillez consulter l’API Lier une identité sociale à un utilisateur.

Conserver les identifiants utilisateurs existants

Par défaut, Logto génère un identifiant aléatoire pour chaque utilisateur créé via la Management API. Si votre application stocke déjà des identifiants utilisateurs provenant de l’ancien fournisseur d’identité, vous pouvez les conserver en passant un champ optionnel id dans le corps de la requête create user. Cela évite d’avoir à maintenir une table de correspondance entre les anciens et nouveaux identifiants.

L’identifiant doit comporter entre 1 et 128 caractères et peut contenir des lettres, des chiffres, et _ - . @ : + = |. Cela couvre les formats courants comme auth0|5f7c8ec7c33c6c004bbafe82, google-oauth2|103547991597142817347, UUID, user_01H8MZ2QK3V4X5Y6Z7, et les adresses e-mail. Les caractères non valides dans les chemins d’URL (espaces, /, ?, #, %, \) sont rejetés avec un code 400, car l’identifiant est utilisé dans /api/users/{userId}. Si l’identifiant est déjà utilisé, la requête échoue avec 422 user.id_already_in_use.

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

remarque:

Les identifiants utilisateurs personnalisés ne sont pris en charge que dans Logto auto-hébergé. Logto Cloud rejette les requêtes incluant id avec 501 request.feature_not_supported, car les identifiants utilisateurs sont partagés entre les locataires.

Hachage des mots de passe

Logto utilise Argon2 pour hacher les mots de passe des utilisateurs, et prend également en charge d’autres algorithmes comme MD5, SHA1, SHA256 et Bcrypt pour faciliter la migration. Ces algorithmes sont considérés comme non sécurisés ; les empreintes correspondantes seront migrées vers Argon2 lors de la première connexion réussie de l’utilisateur.

Si vous utilisez d’autres algorithmes de hachage ou du sel, vous pouvez définir passwordAlgorithm sur Legacy, ce qui vous permet d’utiliser n’importe quel algorithme de hachage pris en charge par Node.js. Vous trouverez la liste des algorithmes pris en charge dans la documentation crypto de Node.js. Dans ce cas, le champ passwordDigest sera une chaîne JSON contenant l’algorithme de hachage et d’autres paramètres spécifiques à l’algorithme.

Format général Legacy

Le format de la chaîne JSON est le suivant :

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

Vous pouvez utiliser @ comme espace réservé pour la valeur réelle du mot de passe dans les arguments.

Par exemple, si vous utilisez SHA256 avec un sel, vous pouvez stocker le mot de passe au format suivant :

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

Ce qui équivaut au code suivant :

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

Prise en charge de PBKDF2

Logto prend en charge spécifiquement PBKDF2.

Pour migrer des mots de passe hachés avec PBKDF2, définissez passwordAlgorithm sur Legacy et formatez passwordDigest comme suit :

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

Les paramètres sont :

salt : La valeur de sel utilisée dans le hachage d’origine
iterations : Nombre d’itérations (ex. "1000")
keylen : Longueur de la clé dérivée en octets (ex. "20")
digest : La fonction de hachage utilisée (ex. "sha512", "sha256", "sha1")
@ : Espace réservé pour la valeur réelle du mot de passe
expected_hashed_value : Le résultat attendu du hachage sous forme de chaîne hexadécimale

Exemple de charge utile de migration :

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

Étapes de migration

Préparer les données utilisateur
Vous devez d’abord exporter les données utilisateur de votre plateforme existante, puis faire correspondre les informations utilisateur au schéma utilisateur Logto. Nous vous recommandons de préparer les données mappées au format JSON. Voici un exemple de données utilisateur :
```
[
  {
    "username": "user1",
    "passwordDigest": "password-encrypted",
    "passwordAlgorithm": "SHA256"
  },
  {
    "username": "user2",
    "passwordDigest": "password-encrypted",
    "passwordAlgorithm": "SHA256"
  }
]
```
Créer un tenant Logto
Vous devrez configurer un tenant dans Logto. Vous pouvez utiliser Logto Cloud ou Logto OSS. Si ce n’est pas encore fait, veuillez consulter le guide Configurer Logto cloud.
Configurer la connexion à la Management API
Nous utiliserons la Management API pour importer les données utilisateur. Vous pouvez consulter la page Management API pour apprendre à configurer la connexion dans votre environnement de développement.

Importer les données utilisateur
Il est recommandé de préparer un script pour importer les utilisateurs un par un. Nous appellerons l’API create user pour importer les données utilisateur. Voici un exemple de script :

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),
      });
      // Pause pour éviter la limite de débit
      await new Promise((resolve) => setTimeout(resolve, 200));
    } catch (error) {
      console.error(`Échec de l'import de l'utilisateur ${user.username} : ${error.message}`);
    }
  }
};

importUsers();

Veuillez noter que le point d’API est soumis à une limite de débit ; vous devez ajouter une pause entre chaque requête pour éviter d’atteindre cette limite. Consultez notre page sur les limites de débit pour plus de détails.

Si vous avez un grand volume de données utilisateur (plus de 100 000 utilisateurs), vous pouvez nous contacter pour augmenter la limite de débit.

Guide général pour migrer votre base de données utilisateur existante vers Logto

Choisir une stratégie de migration​

Schéma utilisateur​

Conserver les identifiants utilisateurs existants​

Hachage des mots de passe​

Format général Legacy​

Prise en charge de PBKDF2​

Étapes de migration​

Ressources associées​