繁體中文（台灣）
  • Magic link
  • Passwordless
  • Authentication
  • Invitation

魔術連結身份驗證

學習如何使用一次性代碼實現無密碼登入、僅邀請註冊和組織成員邀請。

Ran
Ran
Product & Design

不要在使用者認證上浪費數週時間
使用 Logto 更快地發布安全應用程式。幾分鐘內整合使用者認證，專注於您的核心產品。
立即開始
Product screenshot

什麼是魔術連結？

魔術連結是一種無密碼的身份驗證方法，使用者透過電子郵件（或簡訊）接收到一次性登入的 URL。點擊該連結後，可以無需密碼登入。

以下是魔術連結的一些重要安全功能：

  • 一次性代碼：一旦被點擊，代碼就會失效以防止重複使用。
  • 連結過期時間：為了增加安全性，魔術連結應該設定一個較短的過期時間（例如，10 分鐘）。
  • 速率限制：限制在特定時間範圍內發送的魔術連結數量以防止濫用。
  • 裝置/瀏覽器綁定（可選）：限制連結的使用範圍僅限於原始裝置或 IP，以防止攔截。

魔術連結的構成

一個魔術連結包含：

  • URL 路徑：指向應用程序的登陸頁面。
  • 一次性代碼：用於無密碼驗證的唯一且一次性使用的代碼。
  • 用戶電子郵件：用於驗證代碼的真實性和用戶身份。
  • 額外參數：可選，根據您的應用程序需求而定。

例如，一個魔術連結可能如下所示：

要創建一個魔術連結，你需要生成一次性代碼，安全地將其發送給用戶，然後在用戶點擊連結時進行驗證。

魔術連結的工作流程

  1. 用戶請求魔術連結：用戶在您的應用程序中輸入他們的電子郵件。
  2. 一次性代碼生成：服務器生成代碼並通過電子郵件發送作為連結。
  3. 用戶點擊連結：用戶點擊電子郵件中的連結。
  4. 代碼驗證：服務器檢查代碼是否有效。
  5. 用戶被認證：如果代碼有效，用戶登入。

如何使用 Logto 實現魔術連結？

步驟 1：請求一次性代碼

使用 Logto 管理 API創建一次性代碼。

請求範例：

步驟 2：組合您的魔術連結

獲取一次性代碼後，可以組合魔術連結並發送到終端使用者的電子郵件地址。魔術連結至少應包含代碼和用戶電子郵件作為參數，並導航到您應用中的登陸頁面。例如 https://yourapp.com/landing-page。

以下是一個簡單的魔術連結範例：

注意：

魔術連結中的參數名稱可以完全自定義。根據應用程序需求，您可以添加額外信息，也可以對所有 URL 參數進行編碼。

步驟 3：通過 Logto SDK 觸發驗證流程

當終端用戶點擊魔術連結並導航到您的應用程序時，您可以從 URL 中提取 token 和 email 參數，然後調用 Logto SDK 的 signIn() 函數以觸發身份驗證流程。

詳細資訊請查閱 Logto Docs - Magic Link (One-time Token)。

魔術連結的應用案例

魔術連結可以替代使用者身份驗證的第一步，但無法避開 多重身份驗證 (MFA)。

在 Logto 中，當生成具有一次性代碼的魔術連結時，不需指定是用於登入還是註冊。我們會根據電子郵件的註冊狀態，自動確定流程：

  • 未註冊電子郵件：點擊魔術連結會將用戶引導至帳號創建流程，跳過電子郵件輸入和驗證。用戶可以根據註冊設置設置密碼、添加個人資料（例如全名），或設置 MFA。
  • 已註冊電子郵件：點擊魔術連結將跳過驗證的第一步（例如，“電子郵件 + 密碼”或“電子郵件 + 驗證碼”）。該用戶將直接登入或根據登入設置完成 MFA。

Logto 支持以下場景的魔術連結：

  1. 僅邀請註冊：對於內部工具或測試階段的 AI 產品，你可以禁用公開註冊，並通過魔術連結邀請特定用戶。
  2. 組織成員邀請：對於 SaaS 產品，使用魔術連結邀請新成員加入組織，簡化成員資格流程。
  3. 登入/註冊：通過電子郵件發送魔術連結用於登入或註冊。

目前不支持：

如果需要進一步的自訂，請告訴我們。

僅邀請註冊的魔術連結

對於內部測試的新產品（例如 AI 工具）或內部工具，你可以禁用公開註冊並只允許特定用戶訪問應用。要使用 Logto 實現：

  1. 前往 Console > Sign-in experience > Sign-in and Sign-up > 高級選項，並關閉“啟用用戶註冊”以關閉公開註冊。

    logto_disable_public_registration.png

  2. 收集要邀請用戶的電子郵件地址（例如，通過您的網站或現有用戶推薦）。

  3. 按照上面所述創建並發送魔術邀請連結（請求一次性代碼，組合魔術連結，透過 Logto SDK 觸發身份驗證）。

    注意：設置邀請連結的過期時間。建議將連結設置為至少一天有效。使用以下請求內容來生成一次性代碼：

  4. 將魔術連結發送到用戶的電子郵件中（例如，https://yourapp.com/landing-page?type=registrationInvitation&token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]）。自訂電子郵件模板，例如：

    email_templates_invitation_only_registration.png

    當用戶點擊“接受邀請”時，即使已禁用公開註冊，他們仍會自動註冊您的服務。這被稱為“目標用戶邀請”。

組織成員邀請的魔術連結

對於多租戶產品（例如像 Slack、GitHub、Vercel 的 SaaS 應用），提供無縫的成員邀請過程來管理組織成員資格。使用魔術連結可提高成員邀請的轉換率。

  1. 按照 Logto Docs 實現組織創建、基於組織角色的訪問控制和組織管理：Logto Organizations。

  2. 在產品中設置 “邀請成員” 流程。示例：

    invite_organization_member_in_app.png

  3. 按照此指南 邀請組織成員。 注意：在邀請成員時，請確保請求內容包含：

    • context: jitOrganizationIds 指定用戶將加入的組織。
    • 設置較長的 expiresIn 時間（例如 2 天或 1 週）以便用戶有足夠時間接受邀請。

    請求範例：

  4. 將邀請連結發送到用戶的電子郵件（例如，https://yourapp.com/landing-page?type=organizationMemberInvitation&token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]）。自訂您的電子郵件模板，例如：

    email_templates_join_organization.png

    當用戶點擊 “接受邀請” 時，將會自動登入或註冊並自動加入組織。

處理帳戶衝突

如果用戶已登入並點擊另一個魔術連結會發生什麼？

為正確處理帳戶衝突，請確保以下事項：

  • 避免在“登入提示”中添加 login：不要設置包含 login 的登入提示。如果設置錯誤，Logto 將自動登入與魔術連結代碼相關的帳戶，繞過帳戶切換提示。
  • 保留現有代碼：調用 signIn() 函數時，指定 clearTokens: false 參數以防止清除現有代碼。如果此選項已使用，確保在登入回調頁手動 清除代碼。

經過正確配置後，用戶體驗如下：

  1. 魔術連結為當前帳戶：如果用戶已登入並點擊同一帳戶的魔術連結，Logto 將驗證一次性代碼，必要時將用戶配置到指定組織。
  2. 魔術連結為其他帳戶：如果用戶已登入並點擊其他帳戶的魔術連結，Logto 將提示用戶選擇：
    • 繼續作為新帳戶：在驗證代碼後，Logto 轉換為新帳戶。
    • 保留當前帳戶：Logto 跳過代碼驗證，將用戶返回至當前帳戶。
    magic_link_account_conflicts.png

處理無效魔術連結的錯誤頁面

當用戶點擊無效的魔術連結時，將被重定向到一個錯誤頁面，清晰地解釋問題所在。以下是可能的錯誤場景及其信息：

名稱描述
token_not_found沒有找到符合給定電子郵件和代碼的有效代碼。
email_mismatch電子郵件與給定代碼不匹配。
token_expired代碼已過期。
token_consumed代碼已被使用。
token_revoked代碼已被撤銷。
cannot_reactivate_token無法重新啟用代碼。

每個錯誤頁面將提供一個具體的消息，幫助用戶理解無效魔術連結的原因並指導他們下一步該怎麼做。例如：

magic_link_error_pages.png

結論

Logto 透過靈活的無密碼登入流程，使用魔術連結提供企業級的安全保障。這是一種簡單而強大的方式，可以創造流暢的用戶體驗——無論你是在邀請用戶加入組織，讓他們輕鬆創建帳號，還是提供無憂的身份驗證。由於 Logto 能處理諸如帳戶衝突和代碼過期這樣的棘手問題，讓你的用戶每次都有一個安全且無挫折的過程。

準備好用堅如磐石的身份驗證現代化你的 IAM 嗎？

免費試用 Logto Cloud