Vérification après le premier facteur
L’Action de vérification après le premier facteur prend en charge la migration utilisateur just-in-time depuis un ancien système de mot de passe.
Malgré son nom, cette Action ne s’exécute pas après chaque premier facteur réussi. Elle ne s’exécute que lorsque toutes les conditions suivantes sont réunies :
- L’interaction Experience API est
SignIn. - L’utilisateur a soumis un nom d’utilisateur, une adresse e-mail ou un numéro de téléphone avec un mot de passe.
- La vérification du mot de passe local de Logto a échoué.
- Si l’identifiant appartient à un utilisateur Logto existant, cet utilisateur n’est pas suspendu.
Si le mot de passe local est valide, Logto continue sans exécuter l’Action. Les tentatives d’inscription, de mot de passe oublié, de connexion sans mot de passe et d’utilisateur suspendu ne la déclenchent pas.
Charge utile de l’événement
L’objet event a cette forme :
type PostFirstFactorVerificationEvent = {
// Conservé pour la compatibilité après le renommage de la fonctionnalité en Actions.
key: 'inlineHook.postFirstFactorVerification';
interactionEvent: 'SignIn';
verificationType: 'Password';
identifier: {
type: 'username' | 'email' | 'phone';
value: string;
};
user: {
id: string;
username: string | null;
primaryEmail: string | null;
primaryPhone: string | null;
name: string | null;
avatar: string | null;
customData: Record<string, unknown>;
profile: Record<string, unknown>;
} | null;
password: string;
};
user vaut null lorsque l’identifiant ne correspond à aucun utilisateur Logto. Sinon, il contient le contexte éditable du profil de l’utilisateur existant.
event.password est le mot de passe en clair soumis par l’utilisateur. Envoyez-le uniquement à votre point de terminaison d’authentification héritée de confiance via HTTPS. Ne le journalisez jamais, ne le stockez pas, ne le placez pas dans customData, ne l’incluez pas dans une erreur, et ne le retournez pas depuis l’Action.
Résultat
Après que le système hérité a vérifié les identifiants soumis, retournez l’un de ces résultats :
type ActionMfaVerification =
| {
type: 'Totp';
secret: string;
}
| {
type: 'BackupCode';
codes: string[];
}
| {
type: 'WebAuthn';
credentialId: string;
publicKey: string;
counter: number;
transports?: ('usb' | 'nfc' | 'ble' | 'internal' | 'cable' | 'hybrid' | 'smart-card')[];
agent?: string;
name?: string;
};
type PostFirstFactorVerificationResult =
| {
action: 'createUser';
passwordVerified: true;
user: ActionUserPatch;
mfaVerifications?: ActionMfaVerification[];
}
| {
action: 'updateUser';
passwordVerified: true;
user: ActionUserPatch;
mfaVerifications?: ActionMfaVerification[];
};
Le résultat doit correspondre à l’événement :
- Lorsque
event.userestnull, retournezcreateUser. - Lorsque
event.userest présent, retournezupdateUser. passwordVerifieddoit avoir la valeur littéraletrue.userne peut contenir que les champs de modification utilisateur pris en charge.
Pour un nouvel utilisateur, Logto ajoute l’identifiant de connexion soumis si le résultat ne l’inclut pas. L’Action ne peut pas modifier l’identifiant soumis pour une autre valeur. La comparaison des e-mails est insensible à la casse, les numéros de téléphone sont comparés après normalisation, et les noms d’utilisateur doivent correspondre exactement.
Lorsque le résultat est accepté, Logto hache le mot de passe soumis avec Argon2i et l’enregistre comme mot de passe local de l’utilisateur. Le script ne doit pas générer ni retourner de hachage de mot de passe.
Retournez undefined lorsque le système hérité rejette les identifiants. Un résultat vide, mal formé ou non pris en charge est également traité comme des identifiants invalides.
Migrer les facteurs MFA
Incluez mfaVerifications pour transférer les facteurs MFA existants de l’utilisateur avec le mot de passe. Logto ajoute les facteurs aux facteurs existants de l’utilisateur et active la MFA pour le compte, de sorte que la même connexion soit soumise à l’un des facteurs migrés lorsque la MFA est requise. Le type de facteur doit être activé dans les paramètres MFA de l’expérience de connexion pour être sollicité. Un paramètre skipMfaOnSignIn déjà défini par l’utilisateur ou un administrateur sur le compte est conservé.
- TOTP —
{ type: 'Totp', secret }.secretest une clé TOTP en Base32. Logto supprime les espaces, la convertit en majuscules et ajoute le padding Base32 avant de la valider ; le résultat doit faire entre 16 et 32 caractères. Un utilisateur ne peut avoir qu’un seul facteur TOTP. - Codes de secours —
{ type: 'BackupCode', codes }.codesdoit contenir de 1 à 10 codes, chacun de 10 caractères parmi0-9eta-f. Les codes migrés sont stockés comme non utilisés, donc ne transmettez que les codes encore inutilisés dans le système hérité. Les codes de secours ne peuvent pas être le seul facteur : l’utilisateur doit déjà avoir un autre facteur, ou en recevoir un dans le même résultat. - WebAuthn —
{ type: 'WebAuthn', credentialId, publicKey, counter, transports?, agent?, name? }.credentialIdetpublicKeysont des chaînes Base64URL non paddées ;publicKeyest la clé publique de l’identifiant. Seuls les identifiants enregistrés pour le domaine sur lequel l’utilisateur se connecte à Logto peuvent être vérifiés, donc ne migrez pas de passkeys enregistrées pour un autre domaine.
Un facteur identique à un déjà présent chez l’utilisateur est ignoré : même secret TOTP, identifiant WebAuthn avec le même credentialId et publicKey, ou codes de secours déjà tous présents dans l’ensemble de l’utilisateur, utilisés ou non. Un code déjà utilisé reste utilisé.
Un facteur en conflit fait échouer la connexion avec une erreur au lieu de remplacer le facteur existant. Cela concerne un secret TOTP différent alors que l’utilisateur a déjà TOTP, de nouveaux codes de secours alors que l’ensemble existant contient encore des codes inutilisés, et un identifiant WebAuthn déjà enregistré pour cet utilisateur ou un autre. Lorsque tous les codes de secours existants ont été utilisés, les codes migrés remplacent l’ensemble épuisé. L’erreur n’inclut aucune valeur d’identifiant.
Si un facteur échoue à la validation, l’ensemble du résultat est traité comme des identifiants invalides et rien n’est écrit.
Un identifiant WebAuthn migré peut être utilisé pour la MFA immédiatement, mais il ne peut pas être utilisé pour la connexion par passkey tant que l’utilisateur n’a pas effectué une MFA avec lui au moins une fois. Cette première vérification MFA enregistre le domaine de l’identifiant, ce dont la connexion par passkey a besoin pour le retrouver.
Les facteurs sont écrits une seule fois. Après une migration réussie, les connexions ultérieures vérifient le mot de passe local et cette Action ne s’exécute plus pour cet utilisateur.
mfaVerifications transporte des identifiants à longue durée de vie. Ne journalisez pas le secret TOTP, les codes de secours ou les données d’identifiant WebAuthn, ne les incluez pas dans une erreur, et ne les retournez nulle part ailleurs que dans mfaVerifications.
Exemple de migration
Configurez LEGACY_VERIFY_URL et LEGACY_API_TOKEN comme variables d’environnement de l’Action, puis adaptez ce script à votre API héritée :
const runAction = async ({ event, environmentVariables = {} }) => {
const response = await fetch(environmentVariables.LEGACY_VERIFY_URL, {
method: 'POST',
headers: {
'content-type': 'application/json',
authorization: `Bearer ${environmentVariables.LEGACY_API_TOKEN}`,
},
body: JSON.stringify({
identifier: event.identifier,
password: event.password,
}),
});
// Traitez un rejet d’authentification comme un résultat d’identifiants invalides ordinaire.
if (response.status === 401 || response.status === 404) {
return;
}
if (!response.ok) {
throw new Error(`Le service d’authentification hérité a retourné ${response.status}`);
}
const legacyUser = await response.json();
if (!legacyUser.passwordVerified) {
return;
}
return {
action: event.user ? 'updateUser' : 'createUser',
passwordVerified: true,
user: {
...(legacyUser.name && { name: legacyUser.name }),
customData: {
migratedFrom: 'legacy',
legacyUserId: legacyUser.id,
},
},
};
};
Si l’utilisateur hérité possède des facteurs MFA, mappez-les dans le même résultat :
const toActionMfaVerifications = (legacyUser) => [
...(legacyUser.totpSecret
? [
{
type: 'Totp',
secret: legacyUser.totpSecret,
},
]
: []),
...(legacyUser.backupCodes?.length
? [
{
type: 'BackupCode',
codes: legacyUser.backupCodes,
},
]
: []),
...(legacyUser.passkeys ?? []).map((passkey) => ({
type: 'WebAuthn',
credentialId: passkey.credentialId,
publicKey: passkey.publicKey,
counter: passkey.counter,
})),
];
Ajoutez mfaVerifications: toActionMfaVerifications(legacyUser) au résultat retourné. Omettez le champ si l’utilisateur hérité n’a pas de facteurs MFA.
La première connexion acceptée fonctionne comme suit :
- La vérification du mot de passe local échoue, donc Logto exécute l’Action.
- Le script envoie l’identifiant et le mot de passe au système hérité.
- Le système hérité vérifie les identifiants et le script retourne
createUserouupdateUser. - Logto crée ou met à jour l’utilisateur, stocke le mot de passe soumis comme nouvel identifiant Argon2i local, et écrit les facteurs MFA migrés.
- L’utilisateur effectue la MFA si nécessaire, y compris avec un facteur migré, et Logto termine la connexion.
- Lors des connexions ultérieures, le mot de passe local migré réussit, donc cette Action n’est plus appelée pour cet utilisateur.
Périmètres de sécurité
Les écritures utilisateur, mot de passe et MFA issues de cette Action ont lieu avant la fin de la MFA. Si l’utilisateur abandonne ou échoue la MFA, ces écritures restent.
Un utilisateur créé par cette Action contourne également les gardes réservés à l’inscription, y compris les listes de blocage d’e-mails, les règles de domaine SSO uniquement, le mode d’inscription désactivé et les vérifications de profil obligatoires à l’inscription. La protection Sentinel et la MFA s’appliquent toujours.
Utilisez ces mesures de sécurité :
- Retournez
passwordVerified: trueuniquement après que le système hérité a vérifié positivement le mot de passe soumis exact. - Gardez le point de terminaison hérité privé si possible, exigez une authentification de service, utilisez HTTPS et appliquez une limitation de débit.
- Gardez le patch utilisateur retourné minimal. Ne copiez pas d’identifiants ou de données de profil non validés.
- Considérez les secrets TOTP, les codes de secours et les données d’identifiant WebAuthn comme des identifiants. Ne les journalisez pas, ne les placez pas dans
customData, et ne les incluez pas dans les erreurs. - Testez la création d’utilisateur inconnu, la mise à jour d’utilisateur existant, les collisions d’identifiants, les utilisateurs suspendus, la migration et les conflits MFA, les échecs en amont et les tentatives concurrentes.
- Surveillez
Action.PostFirstFactorVerificationdans les journaux d’audit. - Laissez l’Action activée uniquement pendant la durée de la migration lorsque cela est possible.
Si vous pouvez exporter les données utilisateur et des hachages de mot de passe compatibles à l’avance, envisagez plutôt la migration utilisateur en masse.