ข้ามไปยังเนื้อหาหลัก

การตรวจสอบหลังปัจจัยแรก (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 ให้ละเว้นฟิลด์นี้

การลงชื่อเข้าใช้ครั้งแรกที่ได้รับการยอมรับจะทำงานดังนี้:

  1. การตรวจสอบรหัสผ่านภายในล้มเหลว Logto จึงรัน Action นี้
  2. สคริปต์ส่ง identifier และรหัสผ่านไปยังระบบเดิม
  3. ระบบเดิมตรวจสอบข้อมูลรับรองและสคริปต์ส่งคืน createUser หรือ updateUser
  4. Logto สร้างหรืออัปเดตผู้ใช้ บันทึกรหัสผ่านที่ส่งมาเป็น credential Argon2i ใหม่ และบันทึกปัจจัย MFA ที่ย้ายมา
  5. ผู้ใช้ทำ MFA หากจำเป็น รวมถึงปัจจัยที่ย้ายมา และ Logto ดำเนินการลงชื่อเข้าใช้จนเสร็จ
  6. ในการลงชื่อเข้าใช้ครั้งถัดไป รหัสผ่านภายในที่ย้ายมาจะผ่านการตรวจสอบ 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) แทน