Überprüfung nach dem ersten Faktor
Die Aktion „Überprüfung nach dem ersten Faktor“ unterstützt die Just-in-Time-Benutzermigration aus einem alten Passwortsystem.
Trotz ihres Namens wird diese Aktion nicht nach jedem erfolgreichen ersten Faktor ausgeführt. Sie läuft nur, wenn alle folgenden Bedingungen erfüllt sind:
- Die Experience API-Interaktion ist
SignIn. - Der Benutzer hat einen Benutzernamen, eine E-Mail-Adresse oder eine Telefonnummer mit einem Passwort eingereicht.
- Die lokale Passwortüberprüfung von Logto ist fehlgeschlagen.
- Wenn der Bezeichner zu einem bestehenden Logto-Benutzer gehört, ist dieser Benutzer nicht gesperrt.
Ist das lokale Passwort gültig, fährt Logto fort, ohne die Aktion auszuführen. Registrierung, Passwort vergessen, Anmeldung ohne Passwort und Versuche gesperrter Benutzer lösen sie nicht aus.
Ereignis-Payload
Das event hat folgende Struktur:
type PostFirstFactorVerificationEvent = {
// Aus Kompatibilitätsgründen nach der Umbenennung des Features in Actions beibehalten.
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 ist null, wenn der Bezeichner keinem Logto-Benutzer gehört. Andernfalls enthält es den bearbeitbaren Profilkontext des bestehenden Benutzers.
event.password ist das vom Benutzer eingegebene Klartextpasswort. Sende es nur an deinen vertrauenswürdigen Legacy-Authentifizierungsendpunkt über HTTPS. Logge es niemals, speichere es nicht, platziere es nicht in customData, füge es nicht in einen Fehler ein und gib es nicht aus der Aktion zurück.
Ergebnis
Nachdem das Altsystem die übermittelten Zugangsdaten überprüft hat, gib eines dieser Ergebnisse zurück:
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[];
};
Das Ergebnis muss zum Ereignis passen:
- Wenn
event.usernullist, gibcreateUserzurück. - Wenn
event.uservorhanden ist, gibupdateUserzurück. passwordVerifiedmuss den Literalwerttruehaben.userdarf nur die unterstützten Benutzer-Patch-Felder enthalten.
Für einen neuen Benutzer fügt Logto den übermittelten Anmeldebezeichner hinzu, wenn das Ergebnis ihn nicht enthält. Die Aktion kann den übermittelten Bezeichner nicht auf einen anderen Wert ändern. Ein E-Mail-Vergleich ist nicht groß-/kleinschreibungssensitiv, Telefonnummern werden nach Normalisierung verglichen und Benutzernamen müssen exakt übereinstimmen.
Wenn das Ergebnis akzeptiert wird, hasht Logto das übermittelte Passwort mit Argon2i und speichert es als lokales Passwort des Benutzers. Das Skript darf keinen Passwort-Hash generieren oder zurückgeben.
Gib undefined zurück, wenn das Altsystem die Zugangsdaten ablehnt. Ein leeres, fehlerhaftes oder nicht unterstütztes Ergebnis wird ebenfalls als ungültige Zugangsdaten behandelt.
MFA-Faktoren migrieren
Füge mfaVerifications hinzu, um die bestehenden MFA-Faktoren des Benutzers zusammen mit dem Passwort zu übernehmen. Logto fügt die Faktoren zu den bestehenden Faktoren des Benutzers hinzu und aktiviert MFA für das Konto, sodass bei erforderlicher MFA dieselbe Anmeldung für einen der migrierten Faktoren herausgefordert wird. Der Faktor-Typ muss in den MFA-Einstellungen der Anmeldeerfahrung aktiviert sein, um abgefragt zu werden. Eine Einstellung skipMfaOnSignIn, die der Benutzer oder ein Admin bereits für das Konto gesetzt hat, bleibt erhalten.
- TOTP —
{ type: 'Totp', secret }.secretist ein Base32-TOTP-Geheimnis. Logto entfernt Leerzeichen, wandelt es in Großbuchstaben um und fügt Base32-Padding hinzu, bevor es validiert wird; das Ergebnis muss 16 bis 32 Zeichen lang sein. Ein Benutzer kann nur einen TOTP-Faktor haben. - Backup-Codes —
{ type: 'BackupCode', codes }.codesmuss 1 bis 10 Codes enthalten, jeweils 10 Zeichen aus0-9unda-f. Migrierte Codes werden als unbenutzt gespeichert, daher übergebe nur die Codes, die im Altsystem noch unbenutzt sind. Backup-Codes können nicht der einzige Faktor sein: Der Benutzer muss bereits einen anderen Faktor haben oder einen im selben Ergebnis erhalten. - WebAuthn —
{ type: 'WebAuthn', credentialId, publicKey, counter, transports?, agent?, name? }.credentialIdundpublicKeysind ungepolsterte Base64URL-Strings;publicKeyist der öffentliche Schlüssel der Anmeldeinformation. Nur Anmeldeinformationen, die für die Domain registriert sind, mit der sich der Benutzer bei Logto anmeldet, können verifiziert werden. Migriere daher keine Passkeys, die für eine andere Domain registriert sind.
Ein Faktor, der mit einem bereits vorhandenen Faktor des Benutzers identisch ist, wird übersprungen: dasselbe TOTP-Geheimnis, eine WebAuthn-Anmeldeinformation mit demselben credentialId und publicKey oder Backup-Codes, die alle bereits im Set des Benutzers sind, egal ob verwendet oder nicht. Ein zuvor verwendeter Code bleibt verwendet.
Ein widersprüchlicher Faktor führt dazu, dass die Anmeldung mit einem Fehler fehlschlägt, anstatt den bestehenden Faktor zu ersetzen. Dies betrifft ein anderes TOTP-Geheimnis, wenn der Benutzer bereits TOTP hat, neue Backup-Codes, wenn das bestehende Set des Benutzers noch unbenutzte Codes enthält, und eine WebAuthn-Anmeldeinformation, die bereits für diesen oder einen anderen Benutzer registriert ist. Wenn alle bestehenden Backup-Codes verwendet wurden, ersetzen migrierte Codes das erschöpfte Set. Der Fehler enthält keinen Anmeldewert.
Wenn ein Faktor die Validierung nicht besteht, wird das gesamte Ergebnis als ungültige Zugangsdaten behandelt und nichts wird geschrieben.
Eine migrierte WebAuthn-Anmeldeinformation kann sofort für MFA verwendet werden, aber sie kann nicht für Passkey-Anmeldung verwendet werden, bis der Benutzer einmal MFA damit abgeschlossen hat. Diese erste MFA-Verifizierung zeichnet die Domain der Anmeldeinformation auf, die für die Passkey-Anmeldung benötigt wird.
Die Faktoren werden einmalig geschrieben. Nach einer erfolgreichen Migration überprüft Logto bei späteren Anmeldungen das lokale Passwort und diese Aktion wird für diesen Benutzer nicht mehr ausgeführt.
mfaVerifications enthält langlebige Zugangsdaten. Logge das TOTP-Geheimnis, Backup-Codes oder WebAuthn-Anmeldedaten nicht, füge sie nicht in einen Fehler ein und gib sie nirgendwo außer in mfaVerifications zurück.
Migrationsbeispiel
Konfiguriere LEGACY_VERIFY_URL und LEGACY_API_TOKEN als Umgebungsvariablen der Aktion und passe dann dieses Skript an deine Legacy-API an:
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,
}),
});
// Behandle eine Authentifizierungsablehnung als gewöhnliches ungültige-Zugangsdaten-Ergebnis.
if (response.status === 401 || response.status === 404) {
return;
}
if (!response.ok) {
throw new Error(`Legacy authentication service returned ${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,
},
},
};
};
Wenn der Legacy-Benutzer MFA-Faktoren hat, mappe sie in dasselbe Ergebnis:
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,
})),
];
Füge mfaVerifications: toActionMfaVerifications(legacyUser) zum zurückgegebenen Ergebnis hinzu. Lass das Feld weg, wenn der Legacy-Benutzer keine MFA-Faktoren hat.
Die erste akzeptierte Anmeldung funktioniert wie folgt:
- Die lokale Passwortüberprüfung schlägt fehl, daher führt Logto die Aktion aus.
- Das Skript sendet den Bezeichner und das Passwort an das Altsystem.
- Das Altsystem überprüft die Zugangsdaten und das Skript gibt
createUseroderupdateUserzurück. - Logto erstellt oder aktualisiert den Benutzer, speichert das übermittelte Passwort als neues lokales Argon2i-Zertifikat und schreibt alle migrierten MFA-Faktoren.
- Der Benutzer schließt MFA ab, falls erforderlich, einschließlich eines migrierten Faktors, und Logto schließt die Anmeldung ab.
- Bei späteren Anmeldungen ist das migrierte lokale Passwort erfolgreich, sodass diese Aktion für diesen Benutzer nicht mehr aufgerufen wird.
Sicherheitsgrenzen
Benutzer-, Passwort- und MFA-Schreibvorgänge aus dieser Aktion erfolgen, bevor MFA abgeschlossen ist. Wenn der Benutzer MFA abbricht oder nicht besteht, bleiben diese Schreibvorgänge bestehen.
Ein durch diese Aktion erstellter Benutzer umgeht auch ausschließlich für die Registrierung geltende Schutzmechanismen, einschließlich E-Mail-Blocklisten, SSO-only-Domainregeln, deaktiviertem Anmeldemodus und verpflichtenden Profilprüfungen bei der Registrierung. Sentinel-Schutz und MFA gelten weiterhin.
Nutze diese Schutzmaßnahmen:
- Gib
passwordVerified: truenur zurück, nachdem das Altsystem das exakt übermittelte Passwort positiv verifiziert hat. - Halte den Legacy-Endpunkt nach Möglichkeit privat, verlange Service-Authentifizierung, verwende HTTPS und setze Ratenbegrenzung ein.
- Halte den zurückgegebenen Benutzer-Patch minimal. Kopiere keine nicht validierten Bezeichner oder Profildaten.
- Behandle TOTP-Geheimnisse, Backup-Codes und WebAuthn-Anmeldedaten als Zugangsdaten. Logge sie nicht, platziere sie nicht in
customDataund füge sie nicht in Fehler ein. - Teste die Erstellung unbekannter Benutzer, Aktualisierung bestehender Benutzer, Bezeichnerkollisionen, gesperrte Benutzer, MFA-Migration und Konflikte, Upstream-Fehler und gleichzeitige Versuche.
- Überwache
Action.PostFirstFactorVerificationin Audit-Logs. - Halte die Aktion nur für die Dauer der Migration aktiviert, wenn möglich.
Wenn du Benutzerdaten und kompatible Passwort-Hashes im Voraus exportieren kannst, erwäge stattdessen die Massenbenutzermigration.