Skip to main content

Post first-factor verification

The Post first-factor verification Action supports just-in-time user migration from a legacy password system.

Despite its name, this Action does not run after every successful first factor. It runs only when all of the following are true:

  • The Experience API interaction is SignIn.
  • The user submitted a username, email address, or phone number with a password.
  • Logto's local password verification failed.
  • If the identifier belongs to an existing Logto user, that user is not suspended.

If the local password is valid, Logto continues without running the Action. Registration, forgot-password, non-password sign-in, and suspended-user attempts do not trigger it.

Event payload​

The event has this shape:

type PostFirstFactorVerificationEvent = {
// Retained for backward compatibility after the feature was renamed to 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 is null when the identifier does not belong to a Logto user. Otherwise, it contains the existing user's editable profile context.

danger:

event.password is the plaintext password submitted by the user. Send it only to your trusted legacy authentication endpoint over HTTPS. Never log it, store it, place it in customData, include it in an error, or return it from the Action.

Result​

After the legacy system verifies the submitted credentials, return one of these results:

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[];
};

The result must match the event:

  • When event.user is null, return createUser.
  • When event.user is present, return updateUser.
  • passwordVerified must be the literal value true.
  • user may contain only the supported user patch fields.

For a new user, Logto adds the submitted sign-in identifier when the result does not include it. The Action cannot change the submitted identifier to a different value. An email comparison is case-insensitive, phone numbers are compared after normalization, and usernames must match exactly.

When the result is accepted, Logto hashes the submitted password with Argon2i and saves it as the user's local password. The script must not generate or return a password hash.

Return undefined when the legacy system rejects the credentials. An empty, malformed, or unsupported result is also treated as invalid credentials.

Migrate MFA factors​

Include mfaVerifications to carry over the user's existing MFA factors with the password. Logto adds the factors to the user's existing factors and enables MFA for the account, so the same sign-in is challenged for one of the migrated factors when MFA is required. The factor type must be enabled in the sign-in experience's MFA settings to be challenged. A skipMfaOnSignIn setting that the user or an admin already set on the account is kept.

  • TOTP — { type: 'Totp', secret }. secret is a Base32 TOTP secret. Logto removes whitespace, converts it to uppercase, and adds Base32 padding before validating it; the result must be 16 to 32 characters long. A user can have only one TOTP factor.
  • Backup codes — { type: 'BackupCode', codes }. codes must contain 1 to 10 codes, each 10 characters from 0-9 and a-f. Migrated codes are stored as unused, so pass only the codes that are still unused in the legacy system. Backup codes cannot be the only factor: the user must already have another factor, or receive one in the same result.
  • WebAuthn — { type: 'WebAuthn', credentialId, publicKey, counter, transports?, agent?, name? }. credentialId and publicKey are unpadded Base64URL strings; publicKey is the credential public key. Only credentials registered for the domain the user signs in to Logto with can be verified, so do not migrate passkeys registered for a different domain.

A factor identical to one the user already has is skipped: the same TOTP secret, a WebAuthn credential with the same credentialId and publicKey, or backup codes that are all already in the user's set, used or not. A previously used code stays used.

A conflicting factor fails the sign-in with an error instead of replacing the existing factor. This covers a different TOTP secret when the user already has TOTP, new backup codes when the user's existing set still has unused codes, and a WebAuthn credential that is already registered to this or another user. When every existing backup code has been used, migrated codes replace the exhausted set. The error does not include any credential value.

If any factor fails validation, the whole result is treated as invalid credentials and nothing is written.

note:

A migrated WebAuthn credential can be used for MFA right away, but it cannot be used for passkey sign-in until the user completes MFA with it once. That first MFA verification records the credential's domain, which passkey sign-in needs to find it.

The factors are written once. After a successful migration, later sign-ins verify the local password and this Action no longer runs for that user.

danger:

mfaVerifications carries long-lived credentials. Do not log the TOTP secret, backup codes, or WebAuthn credential data, include them in an error, or return them anywhere except mfaVerifications.

Migration example​

Configure LEGACY_VERIFY_URL and LEGACY_API_TOKEN as Action environment variables, then adapt this script to your legacy API:

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,
}),
});

// Treat an authentication rejection as an ordinary invalid-credentials result.
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,
},
},
};
};

If the legacy user has MFA factors, map them into the same result:

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,
})),
];

Add mfaVerifications: toActionMfaVerifications(legacyUser) to the returned result. Omit the field when the legacy user has no MFA factors.

The first accepted sign-in works as follows:

  1. Local password verification fails, so Logto runs the Action.
  2. The script sends the identifier and password to the legacy system.
  3. The legacy system verifies the credentials and the script returns createUser or updateUser.
  4. Logto creates or updates the user, stores the submitted password as a new local Argon2i credential, and writes any migrated MFA factors.
  5. The user completes MFA if required, including a migrated factor, and Logto completes the sign-in.
  6. On later sign-ins, the migrated local password succeeds, so this Action is no longer called for that user.

Security boundaries​

warning:

User, password, and MFA writes from this Action happen before MFA is complete. If the user abandons or fails MFA, those writes remain.

A user created by this Action also bypasses registration-only guards, including email blocklists, SSO-only domain rules, disabled sign-up mode, and registration mandatory-profile checks. Sentinel protection and MFA still apply.

Use these safeguards:

  • Return passwordVerified: true only after the legacy system has positively verified the exact submitted password.
  • Keep the legacy endpoint private when possible, require service authentication, use HTTPS, and apply rate limiting.
  • Keep the returned user patch minimal. Do not copy unvalidated identifiers or profile data.
  • Treat TOTP secrets, backup codes, and WebAuthn credential data as credentials. Do not log them, place them in customData, or include them in errors.
  • Test unknown-user creation, existing-user update, identifier collisions, suspended users, MFA migration and conflicts, upstream failures, and concurrent attempts.
  • Monitor Action.PostFirstFactorVerification in audit logs.
  • Keep the Action enabled only for the duration of the migration when practical.

If you can export user data and compatible password hashes in advance, consider bulk user migration instead.