跳到主要内容

自定义登录体验错误页面

在登录流程中，终端用户有时可能会看到默认的错误页面。常见场景包括：

  • 会话过期：用户登录耗时过长，导致会话超时。
  • 直接访问登录 URL：用户打开了书签或分享了 /sign-in URL（绕过了正常的登录按钮）。
  • 不存在的路由：用户访问了你的认证 (Authentication) 流程中不存在的路径。
  • 社交登录回调问题：在社交回调页面找不到社交会话。
  • 无效的魔法链接：用于组织邀请或无密码登录等场景的一次性令牌 (magic link)已过期或已被使用。

默认情况下，Logto 会在这些场景下显示通用错误页面（例如，404 “未知会话”页面）。为了提升用户在遇到错误时的体验，你需要设置以下参数：

  • 未知会话重定向 URL：当找不到用户会话时，将用户重定向到的备用 URL。
  • 支持邮箱 & 支持网站：在错误页面上显示的联系方式。

未知会话重定向 URL​

Logto 使用 OpenID Connect (OIDC) 流程进行认证 (Authentication)。有效的 OIDC 授权 (Authorization) 流程必须由你的应用程序发起，例如，点击你应用的“登录”按钮会向 Logto 发送 OIDC 授权 (Authorization) 请求，随后 Logto 会建立安全会话（cookie）。

然而，如果用户直接访问 /sign-in，绕过了会话校验，则会在以下情况下导致“未知会话”404 错误：

  • 会话过期
  • 用户收藏 / 分享登录链接
  • 授权 (Authorization) 上下文缺失

为了解决这个问题，Logto 引入了 unknownSessionRedirectUrl 设置。当你设置了该 URL 后，Logto 会自动将用户重定向到指定页面以重新发起新的登录流程，而不是显示 404 错误。

设置方法：

  1. 前往 控制台 > 登录体验 > 注册与登录 > 高级设置
  2. 将“未知会话重定向 URL”设置为你的服务地址或产品首页。例如，Logto Cloud 会设置为 "https://cloud.logto.io"。

支持联系方式​

如果发生其他错误（如访问无效路径、社交回调无会话或打开过期的魔法链接），Logto 会显示默认错误页面。为了帮助用户，你可以在这些不可避免的错误页面上显示联系方式。

认证 (Authentication) 错误页面及支持联系方式

设置方法：

  1. 前往 控制台 > 登录体验 > 内容 > 支持
  2. 设置你的支持邮箱地址
  3. 设置你的支持或官方网站 URL

这样即使出现问题，用户也能清楚地获得帮助途径。