繁體中文（香港）

Magic link
Passwordless
Authentication
Invitation

Magic link 認證

學習如何使用一次性 token 實現無密碼登入、僅限邀請註冊以及組織成員邀請的魔術鏈接。

Ran

Product & Design

6/6/2025

Stop wasting weeks on user auth

Launch secure apps faster with Logto. Integrate user auth in minutes, and focus on your core product.

Get started

什麼是魔術鏈接？

魔術鏈接是一種無密碼認證方法，用戶通過電子郵件（或 SMS）接收一次性登入 URL。點擊鏈接即可登入，而無需密碼。

以下是魔術鏈接的一些關鍵安全特性：

一次性 token：一旦點擊，該 token 即變為無效以防止重複使用。
鏈接過期：為了增加安全性，魔術鏈接應有一個短暫的過期時間（例如 10 分鐘）。
速率限制：通過限制在特定時間內可以發送的魔術鏈接數量來防止濫用。
設備/瀏覽器綁定（可選）：限制鏈接的使用只能在原始設備或 IP 上，以防止截取。

魔術鏈接的組成

一個魔術鏈接由以下部分組成：

URL 路徑：指向應用程序的登陸頁面。
一次性 token：用於無密碼認證的唯一且一次性消耗 token。
用戶電子郵件：用於驗證 token 的真實性和用戶身份。
附加參數：根據應用程序的需求可選。

例如，一個魔術鏈接可能看起來像這樣：

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

魔術鏈接的工作流程

用戶請求魔術鏈接：用戶在你的應用中輸入電子郵件。
生成一次性 token：伺服器生成一個 token 並通過電子郵件將其作為鏈接發送出去。
用戶點擊鏈接：用戶點擊電子郵件中的鏈接。
token 驗證：伺服器檢查 token 是否有效。
用戶被認證：如果 token 有效，用戶被登入。

如何使用 Logto 實現魔術鏈接？

步驟 1：請求一次性 token

使用 Logto 管理 API 來創建一次性 token。

示例請求正文：

步驟 2：組合你的魔術鏈接

在你獲得一次性 token 後，可以組合一個魔術鏈接並將其發送到終端用戶的電子郵件地址。魔術鏈接至少應包含 token 和用戶電子郵件作為參數，並應導航到你自己應用中的登陸頁面。例如 https://yourapp.com/landing-page。

以下是一個簡單的魔術鏈接示例：

注意：

魔術鏈接中的參數名稱可以完全自定義。你可以根據應用程序的需求在魔術鏈接中添加更多信息，並對所有 URL 參數進行編碼。

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

終端用戶點擊魔術鏈接並導航到你的應用後，你可以從 URL 中提取 token 和 email 參數，然後調用 Logto SDK 中的 signIn() 函數來觸發驗證流程。

如需更多詳情，請查看Logto 文檔 - 魔術鏈接（一次性 Token）。

魔術鏈接的使用場景

魔術鏈接可以取代第一步的驗證步驟，但無法繞過多因素身份驗證（MFA）。

在 Logto 中，生成具有一次性 token 的魔術鏈接時，你不需要指定用於登入還是註冊。我們會根據電子郵件的註冊狀態自動決定流程：

未註冊的電子郵件：點擊魔術鏈接會將用戶重定向到帳戶創建流程，跳過電子郵件輸入和驗證。用戶需要設置密碼，添加個人資料信息（例如，全名）或根據您的註冊設置設置 MFA。
已註冊的電子郵件：點擊魔術鏈接會跳過第一步驗證（例如，“電子郵件+密碼”或“電子郵件+驗證碼”）。用戶將直接登入或根據你的設置提示完成 MFA。

Logto 支持以下情況的魔術鏈接：

僅限邀請註冊：對於處於測試階段的內部工具或 AI 產品，你可以禁用公開註冊並通過魔術鏈接邀請特定用戶。
組織成員邀請：對於 SaaS 產品，通過魔術鏈接邀請新成員加入組織，使會員過程更加簡便。
登入/註冊：通過電子郵件發送魔術鏈接以進行登入或註冊。

目前不支持：

通過魔術鏈接進行密碼重置。
使用電話號碼或用戶名作為識別碼。

如果你需要進一步自定義，請告訴我們。

僅限邀請註冊的魔術鏈接

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

前往 Console > Sign-in experience > Sign-in and sign-up > 高級選項，切換關閉“啟用用戶註冊”以關閉公開註冊。
收集你想邀請的用戶的電子郵件地址（例如，通過你的網站或現有用戶的推薦）。
如上所述創建並發送魔術邀請鏈接（請求一次性 token，組合魔術鏈接，通過 Logto SDK 觸發驗證）。

注意：設置邀請鏈接的過期時間。建議使鏈接至少有效一天。使用以下請求正文生成一次性 token：
將魔術鏈接發送到用戶的電子郵件（例如，https://yourapp.com/landing-page?type=registrationInvitation&token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]）。自定義電子郵件模板，例如：

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

使用魔術鏈接進行組織成員邀請

對於多租戶產品（例如，像 Slack、GitHub、Vercel 這樣的 SaaS 應用），提供無縫的成員邀請流程來管理組織會籍。使用魔術鏈接提高成員邀請的轉化率。

按照 Logto 文檔實現組織創建、組織基於角色的訪問控制和組織管理：Logto Organizations。
在產品中設置“邀請成員”工作流。示例：
按照本指南邀請組織成員。注意：在邀請成員時，確保請求負載中包含：
- context: jitOrganizationIds 以指定用戶將加入的組織。
- 設置更長的 expiresIn 時間（例如，2 天或 1 週），以允許用戶有足夠的時間接受邀請。
示例請求負載：
將邀請鏈接發送到用戶的電子郵件（例如，https://yourapp.com/landing-page?type=organizationMemberInvitation&token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]）。自定義你的電子郵件模板，例如：

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

處理帳戶衝突

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

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

避免在“登入提示”中添加login：不要包含login於登入提示中。如果設置不正確，Logto 會自動使用與魔術鏈接 token 關聯的帳戶登入，而不顯示帳戶切換提示。
保留現有 token：在調用signIn()函數時，指定clearTokens: false參數以防止清除現有 token。如果使用此選項，請確保在登錄回調頁面手動清除 token。

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

適用於當前帳戶的魔術鏈接：如果用戶已登入並點擊屬於同一帳戶的魔術鏈接，Logto 會驗證一次性 token，如有必要會將用戶配置到指定的組織。
適用於其他帳戶的魔術鏈接：如果用戶已登入並點擊屬於不同帳戶的魔術鏈接，Logto 會提示用戶：
- 繼續作為新帳戶：經過 token 驗證後，Logto 切換到新帳戶。
- 保持當前帳戶：Logto 跳過 token 驗證並將用戶返回到當前帳戶。

處理魔術鏈接無效的錯誤頁面

當用戶點擊無效的魔術鏈接時，他們將被重定向到帶有明確說明問題的錯誤頁面。以下是可能的錯誤場景及其消息：

名稱	描述
token_not_found	找不到與給定電子郵件和 token 對應的有效 token。
email_mismatch	與給定 token 的電子郵件不匹配。
token_expired	token 已過期。
token_consumed	token 已被使用。
token_revoked	token 已被撤銷。
cannot_reactivate_token	無法重新激活 token。

每個錯誤頁面將提供具體信息，幫助用戶了解無效魔術鏈接的原因並指導他們進行下一步操作。例如：

結論

Logto 通過靈活的魔術鏈接提供企業級安全性，實現無密碼的登入流程。這是一種簡單但強大的方式，無論是邀請用戶加入組織、讓他們輕鬆創建帳戶，還是提供無煩惱的身份驗證，皆能創造出流暢的用戶體驗。而且因為 Logto 處理了帳戶衝突和過期 token 等棘手情況，用戶每次都能獲得安全、無挫折感的過程。

準備好透過堅不可摧的認證來現代化你的 IAM 嗎？

免費試用 Logto Cloud

什麼是魔術鏈接？#

魔術鏈接的組成#

魔術鏈接的工作流程#

如何使用 Logto 實現魔術鏈接？#

步驟 1：請求一次性 token#

步驟 2：組合你的魔術鏈接#

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

魔術鏈接的使用場景#

僅限邀請註冊的魔術鏈接#

使用魔術鏈接進行組織成員邀請#

處理帳戶衝突#

處理魔術鏈接無效的錯誤頁面#

結論#