Magic link 認證

什麼是魔術鏈接？#

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

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

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

魔術鏈接的組成#

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

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

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

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

魔術鏈接的工作流程#

1. 用戶請求魔術鏈接：用戶在你的應用中輸入電子郵件。
2. 生成一次性 token：伺服器生成一個 token 並通過電子郵件將其作為鏈接發送出去。
3. 用戶點擊鏈接：用戶點擊電子郵件中的鏈接。
4. token 驗證：伺服器檢查 token 是否有效。
5. 用戶被認證：如果 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 支持以下情況的魔術鏈接：

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

目前不支持：

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

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

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

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

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

   

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

3. 如上所述創建並發送魔術邀請鏈接（請求一次性 token，組合魔術鏈接，通過 Logto SDK 觸發驗證）。

   注意：設置邀請鏈接的過期時間。建議使鏈接至少有效一天。使用以下請求正文生成一次性 token：

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

   

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

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

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

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

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

   

3. 按照本指南邀請組織成員。 注意：在邀請成員時，確保請求負載中包含：

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

   示例請求負載：

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

   

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

處理帳戶衝突#

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

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

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

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

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

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

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

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

結論#

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

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