简体中文
  • 魔法链接
  • 无密码
  • 身份验证
  • 邀请

魔法链接身份验证

学习如何使用一次性令牌实现密码无登录、邀请制注册和组织成员邀请的魔法链接。

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 文档 - 魔法链接(一次性令牌)

魔法链接使用案例

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

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

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

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

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

目前不支持:

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

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

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

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

    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 文档实施组织创建、组织基于角色的访问控制和组织管理:Logto 组织

  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 吗?