首次因子验证后
首次因子验证后 Action 支持从传统密码系统进行即时用户迁移。
尽管名字如此,该 Action 并不会在每次首次因子验证成功后运行。它仅在以下所有条件都满足时运行:
- Experience API 交互为
SignIn。 - 用户提交了用户名、电子邮件地址或手机号和密码。
- Logto 的本地密码验证失败。
- 如果该标识符属于现有 Logto 用户,则该用户未被暂停。
如果本地密码有效,Logto 会继续流程而不会运行该 Action。注册、忘记密码、非密码登录和被暂停用户的尝试不会触发它。
事件负载
event 的结构如下:
type PostFirstFactorVerificationEvent = {
// 为了向后兼容,在功能重命名为 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;
};
当标识符不属于 Logto 用户时,user 为 null。否则,它包含现有用户可编辑的资料上下文。
event.password 是用户提交的明文密码。仅通过 HTTPS 发送到你信任的传统认证 (Authentication) 端点。切勿记录、存储、放入 customData、包含在错误中或从 Action 返回该密码。
结果
传统系统验证提交的凭据后,返回以下结果之一:
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[];
};
结果必须与事件匹配:
- 当
event.user为null时,返回createUser。 - 当
event.user存在时,返回updateUser。 passwordVerified必须为字面值true。user只能包含支持的用户补丁字段。
对于新用户,如果结果未包含提交的登录标识符,Logto 会自动添加。Action 不能将提交的标识符更改为其他值。电子邮件比较不区分大小写,手机号在归一化后比较,用户名必须完全匹配。
当结果被接受后,Logto 会用 Argon2i 对提交的密码进行哈希,并将其保存为用户的本地密码。脚本不应生成或返回密码哈希。
当传统系统拒绝凭据时,返回 undefined。空、格式错误或不支持的结果也会被视为无效凭据。
迁移 MFA 因子
包含 mfaVerifications 字段可将用户现有的多因素认证 (MFA) 因子与密码一起迁移。Logto 会将这些因子添加到用户现有因子中,并为账户启用 MFA,因此当需要 MFA 时,同一次登录会被要求验证其中一个迁移的因子。因子类型必须在登录体验的 MFA 设置中启用才会被要求。用户或管理员已在账户上设置的 skipMfaOnSignIn 设置会被保留。
- TOTP —
{ type: 'Totp', secret }。secret是 Base32 TOTP 密钥。Logto 会去除空格、转换为大写并添加 Base32 填充后再验证;结果长度必须为 16 到 32 个字符。用户只能有一个 TOTP 因子。 - 备份码 —
{ type: 'BackupCode', codes }。codes必须包含 1 到 10 个代码,每个为 10 位0-9和a-f字符。迁移的备份码会被存为未使用,因此只传递传统系统中仍未使用的代码。备份码不能是唯一因子:用户必须已有其他因子,或在同一结果中获得一个。 - WebAuthn —
{ type: 'WebAuthn', credentialId, publicKey, counter, transports?, agent?, name? }。credentialId和publicKey为未填充的 Base64URL 字符串;publicKey是凭据公钥。只有为用户登录 Logto 的域注册的凭据才能被验证,因此不要迁移为其他域注册的密钥。
与用户已有因子完全相同的因子会被跳过:相同的 TOTP 密钥、credentialId 和 publicKey 都相同的 WebAuthn 凭据,或所有已在用户集合中的备份码(无论是否已用)。已用过的备份码仍然视为已用。
冲突的因子会导致登录失败并报错,而不是替换现有因子。这包括用户已有 TOTP 时传入不同的 TOTP 密钥、用户现有备份码还有未用时传入新备份码,以及已注册给该用户或其他用户的 WebAuthn 凭据。当所有现有备份码都已用完时,迁移的代码会替换已耗尽的集合。错误不会包含任何凭据值。
如果有任何因子验证失败,整个结果会被视为无效凭据,不会写入任何内容。
迁移的 WebAuthn 凭据可以立即用于 MFA,但在用户用它完成一次 MFA 验证前,不能用于密钥登录。首次 MFA 验证会记录凭据的域,密钥登录需要用来查找它。
因子只会写入一次。迁移成功后,后续登录会验证本地密码,该 Action 不再为该用户运行。
mfaVerifications 携带长期凭据。切勿记录 TOTP 密钥、备份码或 WebAuthn 凭据数据,不要将它们包含在错误中,也不要在 mfaVerifications 以外的任何地方返回。
迁移示例
将 LEGACY_VERIFY_URL 和 LEGACY_API_TOKEN 配置为 Action 环境变量,然后将此脚本适配到你的传统 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,
}),
});
// 将认证 (Authentication) 拒绝视为普通的无效凭据结果。
if (response.status === 401 || response.status === 404) {
return;
}
if (!response.ok) {
throw new Error(`传统认证 (Authentication) 服务返回 ${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,
},
},
};
};
如果传统用户有 MFA 因子,将它们映射到同一结果中:
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,
})),
];
在返回结果中添加 mfaVerifications: toActionMfaVerifications(legacyUser)。如果传统用户没有 MFA 因子,则省略该字段。
首次被接受的登录流程如下:
- 本地密码验证失败,Logto 运行该 Action。
- 脚本将标识符和密码发送到传统系统。
- 传统系统验证凭据,脚本返回
createUser或updateUser。 - Logto 创建或更新用户,将提交的密码作为新的本地 Argon2i 凭据保存,并写入任何迁移的 MFA 因子。
- 如需 MFA,用户完成 MFA,包括迁移的因子,Logto 完成登录。
- 后续登录时,迁移的本地密码验证成功,该 Action 不再为该用户调用。
安全边界
该 Action 写入的用户、密码和 MFA 信息发生在 MFA 完成之前。如果用户放弃或未通过 MFA,这些写入仍然保留。
通过该 Action 创建的用户也会绕过仅限注册的保护措施,包括邮箱黑名单、仅限 SSO 域规则、禁用注册模式和注册强制资料检查。哨兵保护和 MFA 仍然适用。
请采取以下安全措施:
- 仅在传统系统已明确验证提交的密码后返回
passwordVerified: true。 - 尽可能保持传统端点私有,要求服务认证 (Authentication),使用 HTTPS,并实施限流。
- 返回的用户补丁应尽量精简。不要复制未经验证的标识符或资料数据。
- 将 TOTP 密钥、备份码和 WebAuthn 凭据数据视为凭据。不要记录、放入
customData或包含在错误中。 - 测试未知用户创建、现有用户更新、标识符冲突、被暂停用户、MFA 迁移与冲突、上游失败和并发尝试。
- 监控 审计日志中的
Action.PostFirstFactorVerification。 - 实际迁移期间,尽量只在需要时启用该 Action。
如果你可以提前导出用户数据和兼容的密码哈希,建议考虑批量用户迁移。