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

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

Cloud availabilityOSS availability

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

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

นักพัฒนาแอปพลิเคชันสามารถใช้โทเค็นใช้ครั้งเดียวเพื่อสร้าง 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": "[email protected]",
  // ไม่บังคับ ค่าเริ่มต้นคือ 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 protected]
บันทึก:

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

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

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

TokenLandingPage.tsx
// ตัวอย่าง React
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 เพิ่มเติมเพื่อป้องกันการลบโทเค็นที่มีอยู่ หากกำหนดไว้ คุณจะต้องลบโทเค็นด้วยตนเองในหน้า callback ของ sign-in

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

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

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

Callback.tsx
// ตัวอย่าง React
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" ในหน้าแสดงรายละเอียดขององค์กร และกำหนดบทบาทเริ่มต้นสำหรับองค์กรของคุณ

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

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

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

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

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