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

การย้ายผู้ใช้ (User migration)

Logto รองรับทั้งการย้ายผู้ใช้แบบกลุ่ม (bulk) และแบบ Just-in-time จากระบบข้อมูลระบุตัวตนอื่น คู่มือนี้อธิบายวิธีนำเข้าผู้ใช้แบบกลุ่มผ่าน Management API และสิ่งที่ควรพิจารณาก่อนการย้าย

เลือกกลยุทธ์การย้าย​

กลยุทธ์เลือกใช้เมื่อวิธีการทำงาน
การย้ายแบบกลุ่ม (Bulk migration)คุณสามารถส่งออกข้อมูลผู้ใช้และรหัสผ่านที่เข้ารหัสในรูปแบบที่ Logto รองรับได้นำเข้าผู้ใช้ก่อนการเปลี่ยนผ่านผ่าน Management API ตามขั้นตอนในคู่มือนี้
การย้ายแบบ Just-in-time (Just-in-time migration)คุณต้องตรวจสอบรหัสผ่านกับระบบเดิม ไม่สามารถส่งออกรหัสผ่านที่เข้ารหัสในรูปแบบที่รองรับ หรืออยากย้ายผู้ใช้ที่ใช้งานอยู่ทีละน้อยกำหนดค่า Post first-factor verification Action เมื่อผู้ใช้ลงชื่อเข้าใช้ด้วยรหัสผ่านครั้งแรก Logto จะตรวจสอบข้อมูลรับรองผ่าน Action ของคุณ สร้างหรืออัปเดตผู้ใช้ และจัดเก็บรหัสผ่านใหม่ในรูปแบบ local hash

การย้ายแบบ Just-in-time จะคงบริการการยืนยันตัวตนเดิมไว้ในเส้นทางคำขอลงชื่อเข้าใช้จนกว่าผู้ใช้จะถูกย้าย ควรใช้ endpoint HTTPS ที่รวดเร็วและเชื่อถือได้ และเปิดใช้งานตลอดช่วงเวลาการย้าย

สคีมาผู้ใช้ (User schema)​

ก่อนเริ่มต้น มาดู user schema ใน Logto กันก่อน สคีมาผู้ใช้ใน Logto มี 3 ส่วนที่ควรทราบ:

  1. ข้อมูลพื้นฐาน (Basic data): คือข้อมูลพื้นฐานจากโปรไฟล์ผู้ใช้ คุณสามารถจับคู่ข้อมูลจากโปรไฟล์ผู้ใช้เดิมของคุณได้
  2. ข้อมูลกำหนดเอง (Custom data): เก็บข้อมูลผู้ใช้เพิ่มเติม ใช้สำหรับข้อมูลที่ไม่สามารถจับคู่กับข้อมูลพื้นฐานได้
  3. ข้อมูลโซเชียล (Social identities): เก็บข้อมูลผู้ใช้ที่ได้จากการลงชื่อเข้าใช้ด้วยโซเชียล

คุณสามารถสร้างแผนที่จับคู่ข้อมูลผู้ใช้จากโปรไฟล์เดิมไปยัง ข้อมูลพื้นฐาน และ ข้อมูลกำหนดเอง สำหรับการลงชื่อเข้าใช้ด้วยโซเชียล จะต้องมีขั้นตอนเพิ่มเติมในการนำเข้าข้อมูลโซเชียล โปรดดู API ของ Link social identity to user

การแฮชรหัสผ่าน (Password hashing)​

Logto ใช้ Argon2 ในการแฮชรหัสผ่านของผู้ใช้ และยังรองรับอัลกอริทึมอื่น เช่น MD5, SHA1, SHA256 และ Bcrypt เพื่อความสะดวกในการย้าย อัลกอริทึมเหล่านี้ถือว่าไม่ปลอดภัย รหัสผ่านที่ใช้แฮชเหล่านี้จะถูกย้ายเป็น Argon2 เมื่อผู้ใช้ลงชื่อเข้าใช้สำเร็จครั้งแรก

หากคุณใช้อัลกอริทึมหรือ salt อื่น ๆ สามารถตั้งค่า passwordAlgorithm เป็น Legacy ซึ่งจะอนุญาตให้ใช้ hash algorithm ใด ๆ ที่ Node.js รองรับ ดูรายการอัลกอริทึมที่รองรับได้ใน Node.js crypto documentation ในกรณีนี้ passwordDigest จะเป็น JSON string ที่มี hash algorithm และพารามิเตอร์เฉพาะของอัลกอริทึมนั้น

รูปแบบ Legacy ทั่วไป​

รูปแบบของ JSON string คือ:

["hash_algorithm", ["argument1", "argument2", ...], "expected_hashed_value"]

คุณสามารถใช้ @ เป็นตัวแทนรหัสผ่านจริงใน arguments

ตัวอย่างเช่น หากใช้ SHA256 กับ salt สามารถเก็บรหัสผ่านในรูปแบบนี้:

["sha256", ["salt123", "@"], "c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e"]

ซึ่งเทียบเท่ากับโค้ดนี้:

const hash = crypto.createHash('sha256');
hash.update('salt123' + 'password123');
const expectedHashedValue = hash.digest('hex');

รองรับ PBKDF2​

Logto รองรับ PBKDF2 โดยเฉพาะ

หากต้องการย้ายรหัสผ่านที่แฮชด้วย PBKDF2 ให้ตั้งค่า passwordAlgorithm เป็น Legacy และจัดรูปแบบ passwordDigest ดังนี้:

["pbkdf2", ["salt", "1000", "20", "sha512", "@"], "expected_hashed_value"]

พารามิเตอร์คือ:

  • salt: ค่า salt ที่ใช้ในกระบวนการแฮชเดิม
  • iterations: จำนวนรอบ (เช่น "1000")
  • keylen: ความยาวของคีย์ที่ได้ (เช่น "20")
  • digest: ฟังก์ชันแฮชที่ใช้ (เช่น "sha512", "sha256", "sha1")
  • @: ตัวแทนรหัสผ่านจริง
  • expected_hashed_value: ผลลัพธ์ hash ที่คาดหวังในรูปแบบ hexadecimal string

ตัวอย่าง payload สำหรับการย้าย:

{
  "username": "john_doe",
  "primaryEmail": "john.doe@example.com",
  "passwordAlgorithm": "Legacy",
  "passwordDigest": "[\"pbkdf2\", [\"mySalt123\", \"1000\", \"20\", \"sha512\", \"@\"], \"c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e\"]"
}

ขั้นตอนการย้าย​

  1. เตรียมข้อมูลผู้ใช้ คุณควรส่งออกข้อมูลผู้ใช้จากแพลตฟอร์มเดิม แล้วแมปข้อมูลผู้ใช้ไปยังสคีมาผู้ใช้ของ Logto แนะนำให้เตรียมข้อมูลที่แมปแล้วในรูปแบบ JSON ตัวอย่างข้อมูลผู้ใช้:

    [
      {
        "username": "user1",
        "passwordDigest": "password-encrypted",
        "passwordAlgorithm": "SHA256"
      },
      {
        "username": "user2",
        "passwordDigest": "password-encrypted",
        "passwordAlgorithm": "SHA256"
      }
    ]

  2. สร้าง Logto tenant คุณต้องตั้งค่า tenant ใน Logto สามารถใช้ Logto Cloud หรือ Logto OSS ก็ได้ หากยังไม่ได้ตั้งค่า โปรดดูคู่มือ Set up Logto cloud

  3. ตั้งค่าการเชื่อมต่อ Management API เราจะใช้ Management API ในการนำเข้าข้อมูลผู้ใช้ ดูรายละเอียดวิธีตั้งค่าการเชื่อมต่อในสภาพแวดล้อมพัฒนาของคุณได้ที่ Management API

  4. นำเข้าข้อมูลผู้ใช้ แนะนำให้เตรียมสคริปต์สำหรับนำเข้าข้อมูลผู้ทีละคน โดยจะเรียก API create user เพื่อเพิ่มข้อมูลผู้ใช้ ตัวอย่างสคริปต์:

    const users = require('./users.json');

    const importUsers = async () => {
      for (const user of users) {
        try {
          await fetch('https://[tenant_id].logto.app/api/users', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              Authorization: 'Bearer [your-access-token]',
            },
            body: JSON.stringify(user),
          });
          // หน่วงเวลาเพื่อหลีกเลี่ยง rate limit
          await new Promise((resolve) => setTimeout(resolve, 200));
        } catch (error) {
          console.error(`นำเข้าผู้ใช้ ${user.username} ไม่สำเร็จ: ${error.message}`);
        }
      }
    };

    importUsers();

โปรดทราบว่า API นี้มีการจำกัดอัตรา (rate limit) ควรเพิ่มการหน่วงเวลาระหว่างแต่ละคำขอเพื่อหลีกเลี่ยง rate limit โปรดตรวจสอบหน้า rate limits สำหรับรายละเอียด

หากคุณมีข้อมูลผู้ใช้จำนวนมาก (100,000+ users) สามารถ ติดต่อเรา เพื่อขอเพิ่ม rate limit ได้

แนวทางทั่วไปสำหรับการย้ายฐานข้อมูลผู้ใช้เดิมของคุณไปยัง Logto