การตรวจสอบหลังปัจจัยแรก (Post first-factor verification)
Action การตรวจสอบหลังปัจจัยแรก (Post first-factor verification) รองรับการย้ายผู้ใช้แบบ just-in-time จากระบบรหัสผ่านเดิม
แม้จะชื่อว่า “หลังปัจจัยแรก” แต่ Action นี้จะไม่ทำงานหลังจากการยืนยันปัจจัยแรกทุกครั้ง จะทำงานเฉพาะเมื่อเงื่อนไขทั้งหมดต่อไปนี้เป็นจริง:
- การโต้ตอบผ่าน Experience API คือ
SignIn - ผู้ใช้ส่งชื่อผู้ใช้ อีเมล หรือเบอร์โทรศัพท์พร้อมรหัสผ่าน
- การตรวจสอบรหัสผ่านภายในของ Logto ล้มเหลว
- หาก identifier นั้นเป็นของผู้ใช้ Logto ที่มีอยู่ ผู้ใช้นั้นต้องไม่ถูกระงับ
หากรหัสผ่านภายในถูกต้อง Logto จะดำเนินการต่อโดยไม่เรียกใช้ Action นี้ การลงทะเบียน ลืมรหัสผ่าน การลงชื่อเข้าใช้แบบไม่ใช้รหัสผ่าน และผู้ใช้ที่ถูกระงับจะไม่เรียกใช้ Action นี้
ข้อมูลเหตุการณ์ (Event payload)
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;
};
user จะเป็น null เมื่อ identifier ไม่ใช่ของผู้ใช้ Logto มิฉะนั้นจะมีข้อมูลโปรไฟล์ของผู้ใช้ที่แก้ไขได้
event.password คือรหัสผ่านแบบ plaintext ที่ผู้ใช้ส่งมา ส่งเฉพาะไปยัง endpoint การยืนยันตัวตนเดิมที่คุณไว้วางใจผ่าน HTTPS เท่านั้น ห้ามบันทึก เก็บไว้ ใส่ใน customData รวมใน error หรือส่งกลับจาก Action เด็ดขาด
ผลลัพธ์ (Result)
หลังจากระบบเดิมตรวจสอบข้อมูลรับรองแล้ว ให้ส่งคืนผลลัพธ์อย่างใดอย่างหนึ่งต่อไปนี้:
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อาจมีเฉพาะ ฟิลด์ที่รองรับสำหรับ user patch เท่านั้น
สำหรับผู้ใช้ใหม่ Logto จะเพิ่ม identifier ที่ใช้ลงชื่อเข้าใช้ที่ส่งมาเมื่อผลลัพธ์ไม่มีข้อมูลนี้ Action ไม่สามารถเปลี่ยน identifier ที่ส่งมาเป็นค่าอื่นได้ การเปรียบเทียบอีเมลไม่สนใจตัวพิมพ์เล็ก-ใหญ่ เบอร์โทรศัพท์จะถูกเปรียบเทียบหลัง normalization และชื่อผู้ใช้ต้องตรงกันเป๊ะ
เมื่อผลลัพธ์ได้รับการยอมรับ Logto จะ hash รหัสผ่านที่ส่งมาด้วย Argon2i และบันทึกเป็นรหัสผ่านภายในของผู้ใช้ สคริปต์ต้องไม่สร้างหรือส่งคืน password hash
ส่งคืน undefined เมื่อระบบเดิมปฏิเสธข้อมูลรับรอง ผลลัพธ์ที่ว่าง ผิดรูปแบบ หรือไม่รองรับจะถือว่าเป็นข้อมูลรับรองไม่ถูกต้องเช่นกัน
ย้ายปัจจัย MFA (Migrate MFA factors)
เพิ่ม mfaVerifications เพื่อถ่ายโอนปัจจัย MFA เดิมของผู้ใช้พร้อมกับรหัสผ่าน Logto จะเพิ่มปัจจัยเหล่านี้เข้าไปในปัจจัยที่ผู้ใช้มีอยู่และเปิดใช้งาน MFA สำหรับบัญชี ดังนั้นการลงชื่อเข้าใช้เดียวกันจะถูกท้าทายด้วยปัจจัยที่ย้ายมาหากจำเป็นต้องใช้ MFA ประเภทของปัจจัยต้องถูกเปิดใช้งานในการตั้งค่า MFA ของประสบการณ์การลงชื่อเข้าใช้จึงจะถูกท้าทายได้ การตั้งค่า skipMfaOnSignIn ที่ผู้ใช้หรือผู้ดูแลระบบตั้งไว้ในบัญชีจะยังคงอยู่
- TOTP —
{ type: 'Totp', secret }secretคือรหัสลับ TOTP แบบ Base32 Logto จะลบช่องว่าง แปลงเป็นตัวพิมพ์ใหญ่ และเติม Base32 padding ก่อนตรวจสอบ; ผลลัพธ์ต้องยาว 16 ถึง 32 ตัวอักษร ผู้ใช้มีได้เพียง 1 ปัจจัย TOTP - Backup codes —
{ type: 'BackupCode', codes }codesต้องมี 1 ถึง 10 โค้ด แต่ละโค้ดยาว 10 ตัวอักษรจาก0-9และa-fโค้ดที่ย้ายมาจะถูกเก็บเป็นโค้ดที่ยังไม่ได้ใช้ ดังนั้นให้ส่งเฉพาะโค้ดที่ยังไม่ได้ใช้ในระบบเดิม Backup codes ไม่สามารถเป็นปัจจัยเดียวได้: ผู้ใช้ต้องมีปัจจัยอื่นอยู่แล้ว หรือได้รับปัจจัยอื่นในผลลัพธ์เดียวกัน - WebAuthn —
{ type: 'WebAuthn', credentialId, publicKey, counter, transports?, agent?, name? }credentialIdและpublicKeyเป็น Base64URL ที่ไม่เติม padding;publicKeyคือ public key ของ credential จะตรวจสอบได้เฉพาะ credential ที่ลงทะเบียนกับโดเมนที่ผู้ใช้ลงชื่อเข้าใช้ Logto เท่านั้น ดังนั้นอย่าย้าย passkey ที่ลงทะเบียนกับโดเมนอื่น
ปัจจัยที่เหมือนกับที่ผู้ใช้มีอยู่แล้วจะถูกข้าม: เช่น TOTP secret เดิม credential WebAuthn ที่มี credentialId และ publicKey เดียวกัน หรือ backup codes ที่มีอยู่ในชุดของผู้ใช้แล้วไม่ว่าจะใช้ไปหรือยัง ปัจจัยที่เคยใช้แล้วจะยังคงถือว่าใช้แล้ว
ปัจจัยที่ขัดแย้งกันจะทำให้การลงชื่อเข้าใช้ล้มเหลวพร้อม error แทนที่จะแทนที่ปัจจัยเดิม เช่น TOTP secret ใหม่เมื่อผู้ใช้มี TOTP อยู่แล้ว backup codes ใหม่เมื่อชุดเดิมยังมีโค้ดที่ยังไม่ได้ใช้ หรือ credential WebAuthn ที่ลงทะเบียนกับผู้ใช้นี้หรือผู้อื่นอยู่แล้ว เมื่อ backup code เดิมถูกใช้หมด โค้ดที่ย้ายมาจะแทนที่ชุดเดิมที่หมดแล้ว Error จะไม่รวมค่า credential ใด ๆ
หากปัจจัยใดไม่ผ่านการตรวจสอบ ผลลัพธ์ทั้งหมดจะถือว่าเป็นข้อมูลรับรองไม่ถูกต้องและจะไม่บันทึกอะไรเลย
credential WebAuthn ที่ย้ายมาสามารถใช้ MFA ได้ทันที แต่จะยังไม่สามารถใช้ลงชื่อเข้าใช้ด้วย passkey ได้จนกว่าผู้ใช้จะทำ MFA ด้วย credential นั้นอย่างน้อย 1 ครั้ง การตรวจสอบ MFA ครั้งแรกจะบันทึกโดเมนของ credential ซึ่งจำเป็นสำหรับการลงชื่อเข้าใช้ด้วย passkey
ปัจจัยจะถูกบันทึกเพียงครั้งเดียว หลังจากย้ายสำเร็จ การลงชื่อเข้าใช้ครั้งต่อไปจะตรวจสอบรหัสผ่านภายในและ Action นี้จะไม่ถูกรันสำหรับผู้ใช้นั้นอีก
mfaVerifications มีข้อมูล credential ที่มีอายุยาว ห้ามบันทึก TOTP secret, backup codes หรือข้อมูล credential WebAuthn, รวมใน error หรือส่งคืนที่อื่นนอกจาก mfaVerifications
ตัวอย่างการย้าย (Migration example)
ตั้งค่า LEGACY_VERIFY_URL และ LEGACY_API_TOKEN เป็น environment variable ของ 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,
}),
});
// กรณีการยืนยันตัวตนถูกปฏิเสธ ให้ถือว่าเป็นข้อมูลรับรองไม่ถูกต้อง
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,
},
},
};
};
หากผู้ใช้เดิมมีปัจจัย 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 นี้
- สคริปต์ส่ง identifier และรหัสผ่านไปยังระบบเดิม
- ระบบเดิมตรวจสอบข้อมูลรับรองและสคริปต์ส่งคืน
createUserหรือupdateUser - Logto สร้างหรืออัปเดตผู้ใช้ บันทึกรหัสผ่านที่ส่งมาเป็น credential Argon2i ใหม่ และบันทึกปัจจัย MFA ที่ย้ายมา
- ผู้ใช้ทำ MFA หากจำเป็น รวมถึงปัจจัยที่ย้ายมา และ Logto ดำเนินการลงชื่อเข้าใช้จนเสร็จ
- ในการลงชื่อเข้าใช้ครั้งถัดไป รหัสผ่านภายในที่ย้ายมาจะผ่านการตรวจสอบ Action นี้จะไม่ถูกรันสำหรับผู้ใช้นั้นอีก
ขอบเขตความปลอดภัย (Security boundaries)
การเขียนข้อมูลผู้ใช้ รหัสผ่าน และ MFA จาก Action นี้เกิดขึ้นก่อน MFA จะเสร็จสมบูรณ์ หากผู้ใช้ละทิ้งหรือทำ MFA ไม่ผ่าน ข้อมูลที่เขียนไว้จะยังคงอยู่
ผู้ใช้ที่ถูกสร้างโดย Action นี้จะข้ามข้อจำกัดเฉพาะการลงทะเบียน เช่น รายการบล็อกอีเมล กฎโดเมน SSO-only โหมดปิดรับสมัคร และการตรวจสอบโปรไฟล์บังคับขณะลงทะเบียน Sentinel protection และ MFA ยังมีผลอยู่
ใช้มาตรการป้องกันเหล่านี้:
- ส่งคืน
passwordVerified: trueเฉพาะเมื่อระบบเดิมตรวจสอบรหัสผ่านที่ส่งมาตรงกันจริง ๆ แล้วเท่านั้น - ทำให้ endpoint เดิมเป็นส่วนตัวเมื่อเป็นไปได้ กำหนดให้ต้องมีการยืนยันตัวตนของบริการ ใช้ HTTPS และจำกัดอัตราการเข้าถึง
- ส่งคืน user patch เท่าที่จำเป็น หลีกเลี่ยงการคัดลอก identifier หรือข้อมูลโปรไฟล์ที่ไม่ได้ตรวจสอบ
- ปฏิบัติต่อ TOTP secret, backup codes และข้อมูล credential WebAuthn เป็นข้อมูล credential ห้ามบันทึก ใส่ใน
customDataหรือรวมใน error - ทดสอบกรณีสร้างผู้ใช้ใหม่ อัปเดตผู้ใช้เดิม ชน identifier ผู้ใช้ถูกระงับ การย้าย MFA และกรณีขัดแย้ง ความล้มเหลวจากต้นทาง และความพยายามพร้อมกัน
- เฝ้าติดตาม
Action.PostFirstFactorVerificationใน audit logs - เปิดใช้งาน Action นี้เฉพาะช่วงเวลาที่จำเป็นสำหรับการย้ายข้อมูลเท่านั้น
หากคุณสามารถส่งออกข้อมูลผู้ใช้และ password hash ที่เข้ากันได้ล่วงหน้าได้ ให้พิจารณา การย้ายผู้ใช้แบบกลุ่ม (bulk user migration) แทน