魔法链接身份验证
学习如何使用一次性令牌实现密码无登录、邀请制注册和组织成员邀请的魔法链接。
什么是魔法链接?
魔法链接是一种无密码的身份验证方法,用户通过电子邮件(或短信)收到一个一次性登录 URL。点击该链接即可登录,无需密码。
以下是魔法链接的一些关键安全特性:
- 单次使用令牌:一旦点击,令牌就会失效,以防止重复使用。
- 链接过期:魔法链接应具有较短的过期时间(例如,10 分钟)以增加安全性。
- 请求限制:通过限制能在特定时间段内发送的魔法链接数量来防止滥用。
- 设备/浏览器绑定(可选):限制链接的使用仅限于原设备或 IP,以防止拦截。
魔法链接的组成
魔法链接由以下部分组成:
- URL 路 径:指向你的应用程序的着陆页。
- 一次性令牌:用于无密码身份验证的独特且一次性使用的令牌。
- 用户电子邮件:用于验证令牌的真实性和用户身份。
- 附加参数:根据你的应用程序需求,可选。
例如,一个魔法链接可能如下所示:
要创建魔法链接,你需要生成一次性令牌,并安全地将其发送给用户,然后在用户点击链接时进行验证。
魔法链接的工作流程
- 用户请求魔法链接:用户在你的应用程序中输入他们的电子邮件。
- 生成一次性令牌:服务器生成令牌,并通过电子邮件将其作为链接发送。
- 用户点击链接:用户点击电子邮件中的链接。
- 令牌验证:服务器检查令牌是否有效。
- 用户被认证:如果令牌有效,用户即可登录。
如何使用 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 支持以下魔法链接场景:
- 仅限邀请注册:对于内部工具或处于测试阶段的 AI 产品,你可以禁用公共注册并通过魔法链接邀请特定用户。
- 组织成员邀请:对于 SaaS 产品,使用魔法链接来邀请新成员加入组织,从而简化成员身份流程。
- 登录/注册:通过电子邮件发送魔法链接进行登录或注册。
目前不支持:
如果你需要进一步的自定义,请告诉我们。
使用魔法链接进行仅限邀请的注册
对于处于内部测试的新产品(例如,AI 工具)或内部工具,你可能希望禁用公共注册,并仅允许特定用户访问你的应用程序。使用 Logto 来实现这一点:
-
前往 控制台 > 登录体验 > 登录和注册 > 高级选项,然后关闭“启用用户注册”,以关闭公共注册。
-
收集你想要邀请的用户的电子邮件地址(例如,通过你的网站或现有用户的推荐)。
-
如上所述创建并发送魔法邀请链接(请求一次性令牌,合成魔法链接,通过 Logto SDK 触发身份验证)。
注意:为邀请链接设置过期时间。建议将链接设置为有效至少一天。使用以下请求体生成一次性令牌:
-
将魔法链接发送到用户的电子邮件(例如
https://yourapp.com/landing-page?type=registrationInvitation&token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]
)。定制你的电子邮件模板,例如:当用户点击“接受邀请”时,即使公共注册已关闭,他们也将自动注册你的服务。这被称为“目标用户邀请”。
使用魔法链接进行组织成员邀请
对于多租户产品(如 Slack、GitHub、Vercel 等 SaaS 应用程序),提供无缝的成员邀请过程以管理组织成员身份。使用魔法链接可以提高成员邀请的转化率。
-
按照 Logto 文档实施组织创建、组织 基于角色的访问控制和组织管理:Logto 组织。
-
在你的产品中设置 "邀请成员" 工作流程。示例:
-
按照本指南 邀请组织成员。注意:邀请成员时,确保请求负载包含:
context: jitOrganizationIds
,以指定用户将加入的组织。- 设置较长的
expiresIn
时间(例如,2 天或 1 周),以便用户有足够时间接受邀请。
示例请求负载:
-
将邀请链接发送到用户的电子邮箱(例如
https://yourapp.com/landing-page?type=organizationMemberInvitation&token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]
)。定制你的电子邮件模板,例如:当用户点击 "接受邀请" 时,他们将自动登录或注册并自动加入组织。
处理账户冲突
如果用户已经登录并点击另一个魔法链接,该如何处理账户冲突?
要正确处理账户冲突,请确保以下事项:
- 避免在“登录提示”中添加
login
:不要在登录提示中设置包含login
的项。如果设置不当,Logto 将自动使用与魔法链接令牌关联的账户登录,绕过账户切换提示。 - 保留现有令牌:在调用
signIn()
方法时,指定clearTokens: false
参数以防止清除现有令牌。如果使用此选项,请确保在登录回调页面中 手动清除令牌。
进行适当配置后,用户体验如下:
- 当前账户的魔法链接:如果用户已登录并点击相同账户的魔法链接,Logto 将验证一次性令牌,并如有需要将用户配置到指定的组织。
- 不同账户的魔法链接:如果用户已登录并点击不同账户的魔法链接,Logto 将提示用户:
- 继续新账户:Logto 经令牌验证后切换到新账户。
- 保持当前账户:Logto 跳过令牌验证并将用户返回到当前账户。
处理魔法链接失效的错误页面
当用户点击无效魔法链接时,他们将被重定向到错误页面,并清楚解释问题。以下是可能的错误场景及其消息:
名称 | 描述 |
---|---|
token_not_found | 找不到与给定电子邮件和令牌的活动令牌。 |
email_mismatch | 电子邮件与给定令牌不匹配。 |
token_expired | 令牌已过期。 |
token_consumed | 令牌已被使用。 |
token_revoked | 令牌已被撤销。 |
cannot_reactivate_token | 不能重新激活令牌。 |
每个错误页面将提供具体的信息,帮助用户了解无效魔法链接的原因,并指导他们下一步该怎么做。例如:
结论
Logto 通过灵活的无密码验证流程使用魔法链接提供企业级安全性。这是一种简单而强大的方法,可以创建流畅的用户体验——无论你是在邀请用户加入组织、让他们轻松创建账户,还是提供无缝的身份验证。并且,因为 Logto 处理复杂情况如账户冲突和过期令牌,你的用户每次都能获得安全且无挫折的过程。
准备好通过坚不可摧的身份验证来现代化你的 IAM 吗?