Logto 登录流程全景解析：从五种入口到 OIDC 回调的完整链路

Logto 登录流程全景解析：从五种入口到 OIDC 回调的完整链路

【免费下载链接】logto🧑‍🚀 Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto

Logto 的端到端登录流程（Sign-in flow）以 OIDC 授权交互（Interaction）为状态机核心，涵盖标识符登录、企业 SSO、社交登录、Passkey 直登与一次性令牌五种入口，并在用户识别完成后串接自适应 MFA、资料补全、Passkey 绑定、MFA 处理与可信设备登记等安全闸门，最终通过提交 interaction 完成 OIDC 回调。读完本文，你可以完整掌握 Logto 登录体验的分支决策逻辑、各验证记录（VerificationRecord）的底层设计，以及 核心交互类 中各校验环节的实现位置，便于在定制 Sign-in Experience 或排查登录链路问题时快速定位。

一、流程总览

Logto 将登录流程建模为一张状态转移图：所有入口分支先汇聚到“用户已被识别（User identified）”这一节点，再统一经过安全与资料校验闸门，最后以Submit interaction → OIDC redirect收尾。完整流程图（源自 end-user-flows/sign-in-flow.md）如下：

这张图可以拆成三段来理解：入口识别段（五种入口各自完成“证明你是谁”）、识别后闸门段（MFA 决策与资料补全）、收尾段（Passkey 绑定、MFA 处理、可信设备登记，最后提交 interaction）。

二、五种登录入口及其前端页面映射

图中EntryPoints子图定义了五种入口。前端应用@logto/experience的 页面目录 与每种入口一一对应：

登录页首屏渲染逻辑见 SignIn/Main.tsx：它根据租户的signInMethods与社交连接器列表决定展示形态——仅配置了社交连接器时只渲染社交按钮列表；仅密码方式时渲染PasswordSignInForm；否则渲染IdentifierSignInForm，即图中“first screen password / identifier type”分支的前端体现。

三、标识符登录：两步验证与方式切换

首屏分流

图中第一步判断“Password input shown on first screen?”，对应 use-identifier-sign-in-methods 中对租户登录方式的解析：

• 用户名（username）/手机号（phone）：直接进入提交标识符流程；
• 邮箱（email）：先检查“企业 SSO 是否应接管（enterprise SSO should take over）”——若该邮箱命中 SSO 连接器规则，则重定向到企业 IdP 认证（进入第四节）；未命中则继续本地登录。

第二步验证：方式优先级与切换

提交标识符后进入second_step，用户按“首选验证方式”分流，且可随时切换：

1. 验证码优先（verification code first）：若启用了验证码（Captcha），先完成人机校验再下发验证码——图中vc_captcha分支。验证码页面为 VerificationCode。
2. Passkey 优先（passkey first）：若该标识符已绑定 Passkey，则唤起浏览器 WebAuthn 验证（对应 SignInPasskeyVerification 页面）；未绑定则提示切换到其他方式。
3. 密码优先（password first）：进入第二屏密码表单，同样受“是否启用 Captcha”分支约束。

三个验证分支的密码校验都统一走Verify password节点；验证码分支中“代码校验通过但找不到用户”（Code verified and user found = no）会被导向注册路径，明确不属于本登录流程（Register path outside this sign-in flow），即登录与注册流程的边界由用户是否存在来划定。

后端：验证记录（VerificationRecord）机制

上述每个分支在后端都会落到一条验证记录上。verifications/index.ts 定义了与流程图分支对应的验证类型：

• 标识符侧：Password（密码）、EmailVerificationCode/PhoneVerificationCode（邮箱/手机验证码）、Social（社交）、EnterpriseSso（企业 SSO）、SignInPasskey（Passkey 直登）、WebAuthn、OneTimeToken；
• MFA 侧：TOTP、BackupCode、MfaEmailVerificationCode/MfaPhoneVerificationCode。

每条记录以verificationId关联到当前交互，核心交互类 ExperienceInteraction 通过consumeForIdentify(verificationId)将“已验证的记录”消费为用户识别凭证——流程图里所有分支汇聚到identified节点，在实现上就是这条记录被消费后调用了identifyUser()。

四、企业 SSO 登录：识别、自动关联与注册接管

企业 SSO 分支（图中EnterpriseSSO子图）有两条进入路径：标识符登录页的 SSO 接管重定向（sso_redirect），以及 IdP 认证完成后的回调（sso0）。回调后的决策链为：

1. 已有企业身份→ 直接通过企业身份识别用户；
2. 无企业身份，但存在已验证邮箱关联的用户→ 自动关联（auto-link）企业身份并继续登录，无需用户确认；
3. 完全没有关联→ 检查是否允许注册：允许则携带“已验证的企业身份”切换到注册流程（Switch to register flow with verified enterprise identity）；不允许则停留在登录页并报错。

这一决策链对应后端的 enterprise-sso-verification.ts，其EnterpriseSsoVerification记录同时承担“验证”与“识别”双重角色——这也解释了为什么流程图中企业 SSO 登录在识别后直接提交 interaction（sso_sign_in = yes → Submit interaction）：企业 IdP 已完成强认证，后端在 MFA 校验时对EnterpriseSso类型记录豁免了二次 MFA 要求（见 experience-interaction.ts 中 MFA 校验的注释：“EnterpriseSso verified interaction does not require MFA verification”）。

五、社交登录：回调验证与账号关联页

社交分支（Social子图）的决策链：

1. 校验社交回调（Verify social callback）；
2. 找到已有社交身份 → 直接识别用户；
3. 找到已验证邮箱或手机号关联的用户 → 检查是否启用“自动账号关联”：启用则直接绑定并继续；未启用则进入账号关联页（SocialLinkAccount），用户二选一：
   • 绑定已有账号 → 继续登录；
   • 改为创建新账号 → 检查注册是否允许，允许则携验证后的社交身份进入注册流程，否则停留报错。

对应前端的 SocialSignInWebCallback 与后端 social-verification.ts。

六、Passkey 直登与一次性令牌登录

• Passkey 直登（PasskeyDirect子图）：点击 Passkey 登录按钮后向浏览器发起发现型WebAuthn 请求（Ask browser for discoverable passkey），不依赖任何标识符输入，浏览器凭本地凭据即可定位用户。后端以SignInPasskeyVerification记录完成验证并识别用户。图中同样体现：Passkey 登录的用户在识别后跳过 MFA 闸门（源码注释“Users signing in with passkey does not require MFA verification”），仅走资料补全检查。
• 一次性令牌登录（MagicLink子图）：落地页校验 token 与邮箱提示（Validate token and email hint，见 one-time-token-verification.ts）；命中已知用户则识别成功，否则转入注册路径。

七、识别之后的闸门：自适应 MFA 与 SIE MFA 策略

所有入口汇聚到identified后，先做两级 MFA 决策（图中identified之后的菱形节点）：

• 自适应 MFA（Adaptive MFA）：若启用，则判断“自适应 MFA 要求验证且用户已拥有 MFA 因子”，满足则强制 MFA 验证。其规则引擎在 adaptive-mfa-validator 中，内置四条风控规则，分别对应不同异常信号：
  • geo-velocity.ts：地理速度异常（不可能位移）；
  • new-country.ts：新国家/地区登录；
  • long-inactivity.ts：长期未活动后登录；
  • untrusted-ip.ts：不受信任 IP。
• SIE 固定策略：未启用自适应 MFA 时，回退检查“Sign-in Experience 登录策略是否要求已存在的 MFA 验证”（sie_mfa_gate），命中则同样进入 MFA 验证。
• 豁免规则：企业 SSO 与 Passkey 登录跳过此闸门，直接进入资料补全（profile_skip_sso判断“是否为 SSO 跳过必填资料检查”）。

MFA 验证页面见 MfaVerification，支持 TOTP、备用码、MFA 邮箱/手机验证码与 WebAuthn 等多种因子（对应前文验证记录类型）。

八、资料补全、Passkey 绑定与 MFA 收尾

资料补全（Profile fulfillment）

识别后检查“是否有必填资料缺失（如必填的姓名、缺失的标识符）”，缺失则进入 Continue 页面（Continue）收集数据。后端校验逻辑位于 profile-validator.ts。

Passkey 绑定引导

若租户启用了 Passkey 登录且当前用户尚未绑定 WebAuthn 凭据，进入“创建 Passkey”页面（PasskeySetup），用户可选择立即绑定或跳过。

MFA 处理子流程（MfaFlow子图）

这是登录链路中最长的收尾链，决策顺序为：

1. MFA 现在强制，或组织要求 MFA？是 → 直接进入“缺失必需 MFA 因子”检查；否 → 检查是否应展示“可选 MFA 引导（onboarding）”（MfaOnboarding）：
   • 展示 onboarding 且用户选择启用 → 进入因子绑定；
   • 用户选择不启用 → 直接跳到可信设备闸门。
2. 缺失必需 MFA 因子？是 → 进入 MfaBinding 绑定认证器（TOTP 应用、Passkey、邮箱或手机验证码）；否 → 检查“是否建议追加一个 MFA 因子”（Additional MFA factor suggestion），用户可绑定另一个因子或跳过。
3. 备用码（Backup code）闸门：若启用了备用码且尚未生成或为空，则强制生成并保存备用码。

可信设备登记（Trusted device opt-in）

收尾前最后一个闸门：“可信设备策略启用且存在合格 MFA 证明”时，展示“信任此设备”页面（TrustedDevice），用户可登记（Record opt-in）或跳过（Record skip），两种决策都汇入提交节点。后端状态管理见 trusted-device.ts。

九、提交 Interaction 与 OIDC 回调

所有闸门通过后执行Submit interaction。在 Logto 中，前端最终调用 experience 会话的提交接口，后端将验证记录数组（verificationRecordsArray）连同 MFA、资料等状态一并校验后，把结果写回 OIDC Provider 的交互会话。交互会话的存取辅助实现于 oidc/interaction.ts：getInteractionFromProviderByJti负责按jti加载交互并校验会话主体一致性（防止会话 principal 被篡改），assignResultToInteraction将InteractionResults与上次提交合并后写回，TTL 取exp - 当前时间。随后oidc-provider按标准完成重定向——即流程图终点的OIDC redirect，授权码流程闭环。

十、小结

Logto 的登录流程设计上呈现三个特点：

1. 多入口统一汇聚：五种入口各自完成“证明身份”后都归一到验证记录机制，后续闸门对所有入口一致复用；
2. 安全闸门可分层配置：固定 SIE 策略、自适应 MFA（含四条内置风控规则）、可信设备策略层层叠加，且对企业 SSO / Passkey 这类已强认证路径有明确的豁免语义；
3. 登录与注册边界清晰：所有“用户不存在”的分支都被显式划出登录流程之外，转入携带已验证身份的注册流程，避免登录链路中出现半注册的脏状态。

排查实际问题时，可以从 end-user-flows/sign-in-flow.md 的流程图定位分支，再到 ExperienceInteraction、verifications 目录 与对应前端页面目录中找到具体实现，形成“流程图 → 验证记录 → 页面/路由”的可追溯链路。

【免费下载链接】logto🧑‍🚀 Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto