Passer au contenu principal

Documentation Index

Fetch the complete documentation index at: https://docs.replit.com/llms.txt

Use this file to discover all available pages before exploring further.

Si votre application dispose déjà d’un système d’authentification fonctionnel et d’une base de données de vrais utilisateurs, l’intégration de Clerk Auth n’est pas seulement un changement de code, c’est une migration de données. Sans un plan délibéré, chaque ligne existante dans votre table users devient étrangère à Clerk : de nouveaux comptes sont provisionnés lors de la première connexion, aucun d’eux ne correspond à vos données historiques, et les clients récurrents semblent avoir « perdu » leur compte. Il n’y a vraiment que deux choses à faire correctement.
Cette page couvre uniquement la migration d’une solution d’authentification personnalisée (votre propre table d’utilisateurs, hachage de mots de passe, sessions, etc.) vers Clerk Auth. Ce n’est pas un guide pour déplacer une application de Replit Auth vers Clerk Auth — des conseils officiels pour ce chemin de migration arrivent prochainement.Si vous démarrez une nouvelle application, consultez la vue d’ensemble de Clerk Auth — aucune migration n’est nécessaire.

​
1. Importez vos utilisateurs existants dans Clerk

Chaque utilisateur actif de votre application doit exister en tant qu’utilisateur Clerk avant que Clerk Auth ne soit mis en service. Au minimum, chaque importation doit inclure :
  • E-mail (requis)
  • Métadonnées de profil disponibles : nom, statut vérifié, tout ce que vous souhaitez visible dans le volet Auth
  • Condensé de mot de passe : le hachage de mot de passe existant de l’utilisateur
  • Algorithme de hachage : l’algorithme/format de ce hachage, exactement comme Clerk l’attend
L’algorithme de hachage est la partie facile à rater. Clerk n’accepte qu’un ensemble défini de formats de hachage de mots de passe, et chacun a un identifiant de chaîne spécifique (bcrypt, scrypt_firebase, argon2i, pbkdf2_sha256, etc.). Consultez la liste complète et le format exact de condensé que chacun requiert dans la référence API Créer un utilisateur Clerk. Cette étape nécessite plus qu’une invite d’une ligne. L’Agent pilotant la migration a besoin d’une compréhension approfondie de la façon dont les mots de passe sont hachés dans votre base de code actuelle — quelle bibliothèque, quels paramètres (facteur de coût, disposition du sel, poivre, etc.) et comment cela correspond à l’un des algorithmes pris en charge par Clerk. Une invite bien formulée ressemble à quelque chose comme : 
Lis mon code d'authentification existant et identifie exactement comment les mots de passe sont hachés
(bibliothèque, algorithme, paramètres, et comment la valeur stockée est formatée).
Ensuite, écris un script d'importation en une seule passe qui, pour chaque utilisateur dans ma table users,
appelle l'API Backend Clerk avec l'e-mail, les métadonnées de profil, le condensé de mot de passe
dans le format exact attendu par l'algorithme Clerk correspondant, et la valeur
correcte de `passwordHasher`. Dis-moi quel algorithme Clerk tu as choisi
et pourquoi avant de l'exécuter.
Si votre schéma de hachage ne correspond clairement à aucun des algorithmes pris en charge par Clerk, les utilisateurs importés ne pourront pas se connecter avec leur mot de passe existant. Dans ce cas, importez-les sans condensé et envoyez un e-mail de réinitialisation de mot de passe lors de la bascule.

​
2. Résolvez les utilisateurs Clerk vers vos ID utilisateurs existants

Une fois que les utilisateurs importés se connectent, chaque requête authentifiée porte une identité Clerk. Votre serveur doit mapper cette identité vers la ligne de votre table users — sinon l’ID utilisateur Clerk ne correspondra à aucune de vos clés étrangères existantes (orders.user_id, documents.owner_id, etc.) et les données historiques sembleront perdues. Clerk géré par Replit rend cela simple : lorsque vous importez un utilisateur avec son ID existant comme externalId de l’utilisateur Clerk, cette valeur est automatiquement écrite dans les claims de session comme sessionClaims.userId. Votre middleware n’a qu’à le préférer à l’ID d’utilisateur Clerk brut : 
import { getAuth } from "@clerk/express";

const requireAuth = (req: any, res: any, next: any) => {
  const auth = getAuth(req);
  const userId = auth?.sessionClaims?.userId || auth?.userId;
  if (!userId) {
    return res.status(401).json({ error: "Unauthorized" });
  }
  req.userId = userId;
  next();
};
Avec ce pattern :
  • Les utilisateurs importés se résolvent vers votre users.id existant via sessionClaims.userId — toutes leurs données historiques restent attachées.
  • Les nouveaux utilisateurs (qui se sont inscrits après la bascule et n’ont pas d’externalId) reviennent à auth.userId, qui est leur ID d’utilisateur Clerk. Utilisez l’ID d’utilisateur Clerk comme clé primaire pour ces nouvelles lignes, ou créez une ligne à la première connexion et liez-la en retour.

​
C’est tout

Tout le reste — garder votre ancienne authentification en parallèle, effectuer un essai à blanc sur de vrais comptes, surveiller la création de doublons d’utilisateurs après la bascule, décommissionner l’ancien système — est une hygiène de migration standard et n’est pas spécifique à Clerk Auth.

​
Ressources supplémentaires