魔法链接身份验证

什么是魔法链接？#

魔法链接是一种无密码的身份验证方法，用户通过电子邮件（或短信）收到一个一次性登录 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 文档 - 魔法链接（一次性令牌）。

魔法链接使用案例#

魔法链接可以取代第一步验证因素，但不能绕过 多因素认证 (MFA)。

在 Logto 中，生成具有一次性令牌的魔法链接时，无需指定是用于登录还是注册。我们会根据电子邮件的注册状态自动确定流程：

• 未注册的电子邮件：点击魔法链接将用户重定向到账户创建流程，跳过电子邮件输入和验证。用户根据你的注册设置进行设置密码、添加个人信息（如全名）或设置 MFA。
• 已注册的电子邮件：点击魔法链接会绕过第一步验证（例如，“电子邮件 + 密码”或“电子邮件 + 验证码”）。根据你的登录设置，用户要么直接登录，要么需要完成 MFA。

Logto 支持以下魔法链接场景：

1. 仅限邀请注册：对于内部工具或处于测试阶段的 AI 产品，你可以禁用公共注册并通过魔法链接邀请特定用户。
2. 组织成员邀请：对于 SaaS 产品，使用魔法链接来邀请新成员加入组织，从而简化成员身份流程。
3. 登录/注册：通过电子邮件发送魔法链接进行登录或注册。

目前不支持：

• 使用魔法链接进行 密码重置。
• 使用电话号码或用户名作为 标识符。

如果你需要进一步的自定义，请告诉我们。

使用魔法链接进行仅限邀请的注册#

对于处于内部测试的新产品（例如，AI 工具）或内部工具，你可能希望禁用公共注册，并仅允许特定用户访问你的应用程序。使用 Logto 来实现这一点：

1. 前往 控制台 > 登录体验 > 登录和注册 > 高级选项，然后关闭“启用用户注册”，以关闭公共注册。

   

2. 收集你想要邀请的用户的电子邮件地址（例如，通过你的网站或现有用户的推荐）。

3. 如上所述创建并发送魔法邀请链接（请求一次性令牌，合成魔法链接，通过 Logto SDK 触发身份验证）。

   注意：为邀请链接设置过期时间。建议将链接设置为有效至少一天。使用以下请求体生成一次性令牌：

4. 将魔法链接发送到用户的电子邮件（例如 https://yourapp.com/landing-page?type=registrationInvitation&token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]）。定制你的电子邮件模板，例如：

   

   当用户点击“接受邀请”时，即使公共注册已关闭，他们也将自动注册你的服务。这被称为“目标用户邀请”。

使用魔法链接进行组织成员邀请#

对于多租户产品（如 Slack、GitHub、Vercel 等 SaaS 应用程序），提供无缝的成员邀请过程以管理组织成员身份。使用魔法链接可以提高成员邀请的转化率。

1. 按照 Logto 文档实施组织创建、组织基于角色的访问控制和组织管理：Logto 组织。

2. 在你的产品中设置 "邀请成员" 工作流程。示例：

   

3. 按照本指南 邀请组织成员。注意：邀请成员时，确保请求负载包含：

   • context: jitOrganizationIds，以指定用户将加入的组织。
   • 设置较长的 expiresIn 时间（例如，2 天或 1 周），以便用户有足够时间接受邀请。

   示例请求负载：

4. 将邀请链接发送到用户的电子邮箱（例如 https://yourapp.com/landing-page?type=organizationMemberInvitation&token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]）。定制你的电子邮件模板，例如：

   

   当用户点击 "接受邀请" 时，他们将自动登录或注册并自动加入组织。

处理账户冲突#

如果用户已经登录并点击另一个魔法链接，该如何处理账户冲突？

要正确处理账户冲突，请确保以下事项：

• 避免在“登录提示”中添加 login：不要在登录提示中设置包含 login 的项。如果设置不当，Logto 将自动使用与魔法链接令牌关联的账户登录，绕过账户切换提示。
• 保留现有令牌：在调用 signIn() 方法时，指定 clearTokens: false 参数以防止清除现有令牌。如果使用此选项，请确保在登录回调页面中 手动清除令牌。

进行适当配置后，用户体验如下：

1. 当前账户的魔法链接：如果用户已登录并点击相同账户的魔法链接，Logto 将验证一次性令牌，并如有需要将用户配置到指定的组织。
2. 不同账户的魔法链接：如果用户已登录并点击不同账户的魔法链接，Logto 将提示用户：
   • 继续新账户：Logto 经令牌验证后切换到新账户。
   • 保持当前账户：Logto 跳过令牌验证并将用户返回到当前账户。
   

处理魔法链接失效的错误页面#

当用户点击无效魔法链接时，他们将被重定向到错误页面，并清楚解释问题。以下是可能的错误场景及其消息：

每个错误页面将提供具体的信息，帮助用户了解无效魔法链接的原因，并指导他们下一步该怎么做。例如：

结论#

Logto 通过灵活的无密码验证流程使用魔法链接提供企业级安全性。这是一种简单而强大的方法，可以创建流畅的用户体验——无论你是在邀请用户加入组织、让他们轻松创建账户，还是提供无缝的身份验证。并且，因为 Logto 处理复杂情况如账户冲突和过期令牌，你的用户每次都能获得安全且无挫折的过程。

准备好通过坚不可摧的身份验证来现代化你的 IAM 吗？