通过预构建账户中心界面进行账户设置

什么是预构建账户中心界面

Logto 提供了一个预构建的账户中心界面，为终端用户提供了可直接使用的账户设置管理页面。这个预构建界面由 Logto 托管，处理常见的账户管理任务，包括：

更新邮箱地址和手机号
更新用户名
设置或更新密码
管理社交连接（关联和解除关联社交账户）
管理多因素认证 (MFA) 设置（TOTP 认证器应用、通行密钥、备份码）
开启或关闭两步验证
管理活跃会话和已授权应用

预构建账户中心界面旨在与你的应用无缝协作，提供一致的用户体验，无需你自行开发自定义账户管理页面。

使用预构建界面的优势

零开发成本：开箱即用的页面
一致体验：与 Logto 登录体验风格一致
内置安全：所有验证流程和安全措施自动处理
始终保持最新：新功能和安全改进自动可用

可用页面

预构建账户中心界面提供以下页面，均可通过你的 Logto 租户端点下的 /account 路径访问：

Path	Description
`/account/security`	安全设置中心（两步验证、社交账户、会话）
`/account/email`	更新或移除主邮箱地址
`/account/phone`	更新或移除主手机号
`/account/username`	更新用户名
`/account/password`	设置或更新密码
`/account/passkey/add`	添加新通行密钥（WebAuthn）
`/account/passkey/manage`	查看和管理现有通行密钥
`/account/authenticator-app`	设置 TOTP 认证器应用
`/account/authenticator-app/replace`	替换现有 TOTP 认证器应用
`/account/backup-codes/generate`	生成新的备份码
`/account/backup-codes/manage`	查看和管理备份码

例如，如果你的租户端点是 https://example.logto.app，邮箱更新页面的地址就是 https://example.logto.app/account/email。

如何使用预构建界面

第一步：启用 Account API

预构建账户中心界面依赖于 Account API。前往控制台 > 登录与账户 > 账户中心并启用 Account API。

根据你的需求配置字段权限：

将字段设置为 Edit 允许用户修改
将字段设置为 ReadOnly 仅允许用户查看
将字段设置为 Off 完全隐藏字段

第二步：从你的应用跳转到预构建页面

要使用预构建账户中心界面，你需要将用户从你的应用重定向到相应的 Logto 页面。有两种方式：

方式 A：直接链接并带上 redirect 参数

在你的应用中添加链接，跳转到预构建页面。包含一个 redirect 查询参数，用户完成操作后会返回你的应用：

https://[tenant-id].logto.app/account/email?redirect=https://your-app.com/settings

当用户完成邮箱更新后，会被重定向回 https://your-app.com/settings。

方式 B：嵌入到你的账户设置流程中

你可以将预构建页面集成到你现有的账户设置流程中：

在你的应用账户设置页展示用户当前信息
提供“编辑”或“更新”按钮，链接到对应的预构建页面
用户完成操作后会被重定向回你的应用

示例实现：

function AccountSettings() {
  const tenantEndpoint = 'https://example.logto.app';
  const redirectUrl = encodeURIComponent(window.location.href);

  return (
    <div>
      <h2>账户设置</h2>

      <div>
        <span>邮箱：user@example.com</span>
        <a href={`${tenantEndpoint}/account/email?redirect=${redirectUrl}`}>更新邮箱</a>
      </div>

      <div>
        <span>密码：••••••••</span>
        <a href={`${tenantEndpoint}/account/password?redirect=${redirectUrl}`}>修改密码</a>
      </div>

      <div>
        <span>MFA：未配置</span>
        <a href={`${tenantEndpoint}/account/authenticator-app?redirect=${redirectUrl}`}>
          设置认证器
        </a>
      </div>
    </div>
  );
}

第三步：处理成功重定向

用户完成操作后，会被重定向到你指定的 URL，并带有可选的 show_success 查询参数。你可以用它来展示成功提示：

function SettingsPage() {
  const searchParams = new URLSearchParams(window.location.search);
  const showSuccess = searchParams.get('show_success');

  return (
    <div>
      {showSuccess === 'email' && <div>邮箱更新成功！</div>}
      {showSuccess === 'password' && <div>密码更新成功！</div>}
      {/* ... 你的设置页面其他内容 */}
    </div>
  );
}

支持的 URL 参数

你可以在任何账户中心 URL 后添加以下查询参数，以定制体验：

Parameter	Description
`redirect`	用户完成操作后返回的绝对 URL。只接受 `http(s)` 协议的 URL。
`show_success`	设置为 `true` 时，成功跳转目标（如你的 `redirect` URL）会收到一个 `show_success` 查询参数，你可以用它来展示确认消息。
`identifier`	预填目标页面（`/account/email`、`/account/phone`、`/account/username`）的标识符输入框。当你已知用户标识符时，便于从你的应用深度链接。
`ui_locales`	以空格分隔的 BCP-47 语言标签列表（如 `fr-CA fr en`），控制账户中心界面语言。如果省略，则回退到用户浏览器语言。

示例 — 深度链接到邮箱更新页面，预填当前邮箱并使用法语界面：

https://[tenant-id].logto.app/account/email?identifier=user@example.com&ui_locales=fr&redirect=https://your-app.com/settings

备注:

identifier 的值会在登录重定向前存储到 session storage，并在目标页面被消费一次。

账户删除链接

账户中心不直接处理账户删除。你可以配置一个账户删除 URL，指向你自己的删除流程（通常由 Management API 支持）。配置后，账户中心安全页面会出现删除你的账户入口，用户点击后跳转到你的 URL。

配置方法：前往控制台 > 登录与账户 > 账户中心，设置账户删除 URL字段。你也可以通过 Management API 更新：

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"deleteAccountUrl":"https://your-app.com/delete-account"}'

留空该字段（或将 deleteAccountUrl 设为 null）即可隐藏账户删除入口。

当用户在账户中心关联社交账户时，Logto 使用与常规登录流程不同的重定向 URI。账户中心回调 URL 格式如下：

https://[your-tenant-endpoint]/account/callback/social/{connectorId}

其中 {connectorId} 是社交连接器的 ID（可在控制台 > 连接器 > 社交连接器中找到）。

警告:

你必须将此 URL 添加到你的社交服务商开发者控制台（Google、GitHub、Facebook 等）的授权重定向 URI（或同类）列表中，并且要包含标准登录回调 URL https://[your-tenant-endpoint]/callback/{connectorId}。否则，关联流程会因重定向 URI 不匹配而失败。

安全注意事项

预构建账户中心界面内置了安全措施：

身份验证：在进行敏感更改（邮箱、手机号、密码、MFA）前，用户必须通过当前密码或现有验证方式验证身份
验证码：邮箱和手机号更新需输入发送到新地址/号码的验证码
会话校验：所有操作都会校验用户会话，防止未授权访问

个性化选项

预构建账户中心界面会继承你的登录体验设置中的品牌，包括：

Logo 和配色
深色 / 浅色模式
语言设置

自定义 CSS

你可以通过添加自定义 CSS 进一步个性化账户中心界面。前往控制台 > 登录与账户 > 账户中心，在自定义 CSS编辑器中添加你的样式。

预构建账户中心界面为关键 UI 元素（布局容器、页面头部、分区、卡片等）提供了以 logto_ac- 为前缀的稳定 CSS 类名，方便你精准定制。这让你可以覆盖默认样式，而不用担心版本升级导致类名变化。

示例：

/* 隐藏 Logto 签名 */
.logto_ac-logto-signature {
  display: none;
}

/* 个性化安全分区卡片 */
.logto_ac-security-card {
  border-radius: 12px;
}

如果你需要超出预构建界面和自定义 CSS 能力范围的个性化，可以考虑使用 Account API 自行开发账户管理页面。

通过 Account API 进行账户设置 - 用 API 完全控制自定义账户管理
通过 Management API 进行账户设置 - 管理员级账户管理
MFA 配置 - 设置多因素认证 (MFA)

什么是预构建账户中心界面​

使用预构建界面的优势​

可用页面​

如何使用预构建界面​

第一步：启用 Account API​

第二步：从你的应用跳转到预构建页面​

方式 A：直接链接并带上 redirect 参数​

方式 B：嵌入到你的账户设置流程中​

第三步：处理成功重定向​

支持的 URL 参数​

账户删除链接​

社交连接回调 URL​

安全注意事项​

个性化选项​

自定义 CSS​

相关资源​