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

ลิงก์วิเศษ (Magic link) (โทเค็นใช้ครั้งเดียว; One-time token)

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

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

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

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

Logto รองรับสถานการณ์ต่อไปนี้ด้วยลิงก์วิเศษ:

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

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

An email template for invitation only registration

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

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

โฟลว์โทเค็นใช้ครั้งเดียว​

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

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

Logto มีชุด Management API และ Experience API เพื่อช่วยให้คุณใช้งานลิงก์วิเศษได้ง่ายขึ้น

ก่อนเริ่มต้น ให้แน่ใจว่าคุณมี 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"]
  }
}

สำหรับลิงก์วิเศษรีเซ็ตรหัสผ่าน ให้จำกัดโทเค็นสำหรับโฟลว์ลืมรหัสผ่าน:

{
  "email": "user@example.com",
  "expiresIn": 3600,
  "context": {
    "interactionEvent": "ForgotPassword"
  }
}

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

ตัวอย่างลิงก์วิเศษที่อาจมีหน้าตาดังนี้:

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

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

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

ลงชื่อเข้าใช้หรือสมัครสมาชิก​

หลังจากผู้ใช้ปลายทางคลิกลิงก์วิเศษและเข้าสู่แอปของคุณแล้ว คุณสามารถดึง 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 จากลิงก์วิเศษ
    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 <>กรุณารอสักครู่...</>;
};

รีเซ็ตรหัสผ่าน​

สำหรับลิงก์วิเศษรีเซ็ตรหัสผ่าน ให้เริ่มคำขอยืนยันตัวตนโดยตั้งค่า first_screen เป็น reset_password ส่งผ่านโทเค็นใช้ครั้งเดียวผ่าน one_time_token หากคุณมีอีเมลของผู้ใช้จาก landing page แล้ว ให้ส่งผ่าน login_hint ด้วย; หากไม่มีก็ไม่ต้องใส่ Logto จะขอให้ผู้ใช้กรอกอีเมลก่อนตรวจสอบโทเค็น

ResetPasswordTokenLandingPage.tsx
// ตัวอย่าง React
import { useLogto } from '@logto/react';
import { useEffect } from 'react';
import { useSearchParams } from 'react-router-dom';

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

  useEffect(() => {
    const oneTimeToken = searchParams.get('token');
    const email = searchParams.get('email');

    if (oneTimeToken) {
      signIn({
        redirectUri: 'https://yourapp.com/callback',
        extraParams: {
          'one_time_token': oneTimeToken,
          'first_screen': 'reset_password',
          ...(email && { 'login_hint': email }),
        },
      });
    }
  }, [searchParams, signIn]);

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

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

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

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

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

หากคุณกำหนด clearTokens: false ในฟังก์ชัน sign-in คุณต้องลบโทเค็นด้วยตนเองในหน้าคอลแบ็กของ 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 <>กรุณารอสักครู่...</>;
};

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

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

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

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

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

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

ได้ คุณยังสามารถใช้ลิงก์วิเศษเชิญผู้ใช้ได้ แม้ว่าจะปิดการลงทะเบียนผู้ใช้ใน "Sign-up and sign-in" แล้วก็ตาม

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

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