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

Magic link (โทเค็นใช้ครั้งเดียว)

คล้ายกับรหัสผ่านใช้ครั้งเดียว (OTP), โทเค็นใช้ครั้งเดียวเป็นอีกหนึ่งวิธีการยืนยันตัวตนแบบไม่ใช้รหัสผ่านที่สามารถใช้ตรวจสอบตัวตนของผู้ใช้ได้ โทเค็นนี้จะมีอายุการใช้งานจำกัด และเชื่อมโยงกับที่อยู่อีเมลของผู้ใช้ปลายทาง

บางครั้งคุณอาจต้องการเชิญผู้ใช้ใหม่เข้าสู่แอปพลิเคชัน / องค์กรของคุณโดยไม่ต้องให้พวกเขาสร้างบัญชีก่อน ในกรณีเช่นนี้ แอปพลิเคชันสามารถส่ง "magic link" ไปยังอีเมลของคุณ และคุณจะได้รับการยืนยันตัวตนทันทีเมื่อคลิกลิงก์นั้น

นักพัฒนาแอปพลิเคชันสามารถใช้โทเค็นใช้ครั้งเดียวเพื่อสร้าง magic link และส่งไปยังอีเมลของผู้ใช้ปลายทาง

กรณีการใช้งาน​

Logto รองรับสถานการณ์ต่อไปนี้ด้วย magic link:

  • การลงทะเบียนแบบเชิญเท่านั้น: สำหรับเครื่องมือภายในหรือผลิตภัณฑ์ AI ที่อยู่ในช่วงทดสอบ คุณสามารถปิดการลงทะเบียนสาธารณะและเชิญผู้ใช้เฉพาะผ่าน magic link
  • เชิญสมาชิกองค์กร: สำหรับผลิตภัณฑ์ SaaS ใช้ magic link เพื่อเชิญสมาชิกใหม่เข้าร่วมองค์กร ช่วยให้กระบวนการ onboarding ราบรื่นขึ้น
  • ลงชื่อเข้าใช้ / ลงทะเบียน: ส่ง magic link สำหรับการลงชื่อเข้าใช้หรือสมัครสมาชิกแบบไม่ใช้รหัสผ่านผ่านอีเมล

ตัวอย่างเช่น เมื่อคุณปิดการลงทะเบียนสาธารณะ คุณสามารถส่ง magic link ที่มีโทเค็นใช้ครั้งเดียว (เช่น https://yourapp.com/landing-page?token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&email=user@example.com) ไปยังอีเมลของผู้ใช้เพื่อเชิญให้พวกเขาสร้างบัญชีให้เสร็จสมบูรณ์ คุณสามารถปรับแต่งเทมเพลตอีเมลในบริการส่งอีเมลของคุณเอง เช่น:

An email template for invitation only registration

ปัจจุบันยังไม่รองรับ:

  • การรีเซ็ตรหัสผ่านด้วย magic link
  • การใช้หมายเลขโทรศัพท์หรือชื่อผู้ใช้เป็นตัวระบุ

ขั้นตอนโทเค็นใช้ครั้งเดียว​

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

คู่มือการใช้งาน​

Logto มีทั้ง Management API และ Experience API เพื่อช่วยให้คุณใช้งาน magic link ได้ง่ายขึ้น

ก่อนเริ่มต้น โปรดตรวจสอบให้แน่ใจว่าคุณมี Logto instance พร้อมใช้งาน และได้เชื่อมต่อ Machine-to-Machine ระหว่างเซิร์ฟเวอร์แอปพลิเคชันของคุณกับ Logto endpoint (จำเป็นสำหรับ Management API) ดูเพิ่มเติมเกี่ยวกับ Logto Management API

ขั้นตอนที่ 1: ขอรับโทเค็นใช้ครั้งเดียว​

ใช้ Logto Management API เพื่อสร้างโทเค็นใช้ครั้งเดียว

POST /api/one-time-tokens

ตัวอย่าง payload ของ request body:

{
  "email": "user@example.com",
  // ไม่บังคับ ค่าเริ่มต้นคือ 600 (10 นาที)
  "expiresIn": 3600,
  // ไม่บังคับ ผู้ใช้จะถูกจัดเตรียมเข้าองค์กรที่ระบุเมื่อยืนยันตัวตนสำเร็จ
  "context": {
    "jitOrganizationIds": ["abcdefgh1234"]
  }
}

หลังจากได้รับโทเค็นใช้ครั้งเดียวแล้ว คุณสามารถสร้าง magic link และส่งไปยังอีเมลของผู้ใช้ปลายทาง magic link ควรมีอย่างน้อย token และอีเมลของผู้ใช้เป็นพารามิเตอร์ และควรนำไปยัง landing page ในแอปพลิเคชันของคุณเอง เช่น https://yourapp.com/landing-page

ตัวอย่างง่าย ๆ ของ magic link อาจมีลักษณะดังนี้:

https://yourapp.com/landing-page?token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&email=user@example.com
บันทึก:

ชื่อพารามิเตอร์ใน magic link สามารถปรับแต่งได้อย่างเต็มที่ คุณสามารถเพิ่มข้อมูลเพิ่มเติมลงใน magic link ตามความต้องการของแอปพลิเคชันของคุณ รวมถึงการเข้ารหัสพารามิเตอร์ URL ทั้งหมด

ขั้นตอนที่ 3: เริ่มกระบวนการยืนยันตัวตนผ่าน Logto SDK​

หลังจากผู้ใช้ปลายทางคลิก magic link และเข้าสู่แอปพลิเคชันของคุณแล้ว คุณสามารถดึงพารามิเตอร์ token และ email จาก URL และเรียกใช้ฟังก์ชัน signIn() จาก Logto SDK เพื่อเริ่มกระบวนการยืนยันตัวตน

TokenLandingPage.tsx
// React example
import { useLogto } from '@logto/react';
import { useEffect } from 'react';
import { useSearchParams } from 'react-router-dom';

const TokenLandingPage = () => {
  const { signIn } = useLogto();
  const [searchParams] = useSearchParams();

  useEffect(() => {
    // ดึง token และ email จาก magic link
    const oneTimeToken = searchParams.get('token');
    const email = searchParams.get('email');

    // สมมติว่านี่คือ redirect URI สำหรับ sign-in ของคุณ
    const redirectUri = 'https://yourapp.com/callback';

    if (oneTimeToken && email) {
      signIn({
        redirectUri,
        clearTokens: false, // ไม่บังคับ ดูคำเตือนด้านล่าง
        extraParams: {
          'one_time_token': oneTimeToken,
          'login_hint': email,
        },
      });
    }
  }, [searchParams, signIn]);

  return <>กรุณารอสักครู่...</>;
};
คำเตือน:

หากผู้ใช้ลงชื่อเข้าใช้แล้ว การเรียกใช้ฟังก์ชัน signIn() จาก SDK จะล้างโทเค็นที่แคชไว้ทั้งหมด (ID token, access token, และ refresh token) จาก storage ของ client ซึ่งจะทำให้สถานะการยืนยันตัวตนของผู้ใช้ปัจจุบันหายไป

ดังนั้น คุณควรระบุพารามิเตอร์เพิ่มเติม clearTokens: false เพื่อป้องกันการลบโทเค็นที่มีอยู่ หากระบุไว้ คุณจะต้องลบโทเค็นด้วยตนเองในหน้ากลับจาก sign-in

ข้ามข้อนี้ได้หาก magic link ของคุณไม่ได้ออกแบบมาสำหรับผู้ใช้ที่ลงชื่อเข้าใช้แล้ว

ขั้นตอนที่ 4: (ไม่บังคับ) ลบโทเค็นที่แคชไว้ในหน้ากลับจาก sign-in​

หากคุณระบุ clearTokens: false ในฟังก์ชัน sign-in คุณต้องลบโทเค็นด้วยตนเองในหน้ากลับจาก sign-in

Callback.tsx
// React example
import { useHandleSignInCallback, useLogto } from '@logto/react';
import { useEffect } from 'react';

const Callback = () => {
  const { clearAllTokens } = useLogto();

  useEffect(() => {
    void clearAllTokens();
  }, [clearAllTokens]);

  useHandleSignInCallback(() => {
    // นำทางไปยังหน้าแรกของคุณ
  });

  return <>กรุณารอสักครู่...</>;
};

คำถามที่พบบ่อย​

ได้ คุณสามารถใช้ magic link เพื่อเชิญผู้ใช้ใหม่เข้าสู่แอปพลิเคชันของคุณ รวมถึงองค์กร หากต้องการเชิญผู้ใช้ใหม่เข้าสู่องค์กรของคุณ เพียงระบุ jitOrganizationIds ใน request body

ผู้ใช้จะเข้าร่วมองค์กรโดยอัตโนมัติเมื่อยืนยันตัวตนสำเร็จ และจะได้รับบทบาทองค์กรเริ่มต้น ดูหัวข้อ "Just-in-time provisioning" ในหน้ารายละเอียดองค์กรของคุณ และกำหนดบทบาทเริ่มต้นสำหรับองค์กรของคุณ

กระบวนการยืนยันตัวตนด้วย magic link ยังไม่รองรับการกำหนดบทบาทให้ผู้ใช้โดยตรง แต่คุณสามารถใช้ Webhooks และ Management API เพื่ออัปเดตบทบาทของผู้ใช้หลังจากลงทะเบียนได้เสมอ

โทเค็นใช้ครั้งเดียวหมดอายุหรือไม่?​

ใช่ โทเค็นใช้ครั้งเดียวจะหมดอายุหลังจากเวลาที่ระบุใน expiresIn (หน่วยเป็นวินาที) โดยค่าเริ่มต้นคือ 10 นาที

ได้ คุณยังสามารถใช้ magic link เชิญผู้ใช้ได้ แม้ว่าจะปิดการลงทะเบียนผู้ใช้ใน "ประสบการณ์การลงชื่อเข้าใช้" แล้วก็ตาม

มีหลายสถานการณ์ที่เป็นไปได้:

  1. ผู้ใช้ลงชื่อเข้าใช้แล้ว และคลิก magic link ที่เชื่อมโยงกับบัญชีผู้ใช้ปัจจุบัน ในกรณีนี้ Logto จะตรวจสอบโทเค็นใช้ครั้งเดียว และจัดเตรียมผู้ใช้เข้าสู่องค์กรที่ระบุหากจำเป็น
  2. ผู้ใช้ลงชื่อเข้าใช้แล้ว และคลิก magic link ที่เชื่อมโยงกับบัญชีอื่น ในกรณีนี้ Logto จะถามผู้ใช้ว่าจะดำเนินการต่อในฐานะบัญชีใหม่ หรือกลับไปยังแอปพลิเคชันด้วยบัญชีปัจจุบัน
    1. หากผู้ใช้เลือกดำเนินการต่อในฐานะบัญชีใหม่ Logto จะสลับไปยังบัญชีใหม่หลังจากตรวจสอบโทเค็นสำเร็จ
    2. หากผู้ใช้เลือกใช้บัญชีปัจจุบัน Logto จะไม่ตรวจสอบโทเค็นและกลับไปยังแอปพลิเคชันด้วยบัญชีปัจจุบัน
  3. หาก prompt สำหรับ sign-in ของคุณถูกตั้งค่าเป็น "login" หรือมี "login" อยู่ Logto จะลงชื่อเข้าใช้บัญชีที่เชื่อมโยงกับโทเค็นใช้ครั้งเดียวโดยอัตโนมัติโดยไม่ถามสลับบัญชี เพราะ prompt "login" หมายถึงความตั้งใจที่จะยืนยันตัวตนอย่างชัดเจน ซึ่งจะมีความสำคัญเหนือ session ปัจจุบัน