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

什么是预构建账户中心 UI

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

查看和编辑用户资料（姓名、头像和自定义资料字段）
更新电子邮件地址和手机号码
更新用户名
设置或更新密码
管理社交连接（关联和解除关联社交账号）
管理多因素认证 (MFA) 设置（TOTP 认证器应用、通行密钥、备份码）
开启或关闭两步验证
管理活跃会话和已授权应用

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

使用预构建 UI 的优势

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

可用页面

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

路径	描述
`/account/profile`	用户资料页面（姓名、头像和自定义资料字段）
`/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。

如何使用预构建 UI

第一步：启用 Account API

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

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

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

配置资料字段

账户中心会显示一个资料页面，终端用户可以在此查看和管理个人资料信息。要控制该页面显示哪些资料字段：

确保姓名、头像、资料或 自定义数据 字段权限在账户安全 / 用户资料部分被设置为 Edit 或 ReadOnly。
在集成预构建 UI卡片中，从资料字段选择器添加你希望展示的资料字段。这些字段来源于收集用户资料使用的同一目录——任何在那定义的字段也可在账户中心展示。
拖拽排序字段顺序。

只有同时在资料字段列表中且对应字段权限不为 Off 的字段才会显示在资料页面。

第二步：从你的应用链接到预构建页面

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

方式 A：带重定向参数的直接链接

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

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

当用户完成邮箱更新后，会被重定向回 https://your-app.com/settings。用户使用页面的返回按钮离开时也会回到同一 URL。

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

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

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

示例实现：

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

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

      <div>
        <span>邮箱：[email protected]</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>
  );
}

第三步：处理返回你的应用

用户在完成操作或使用返回按钮离开后，都会回到你的 redirect URL，且 URL 相同。不要仅以返回本身作为更改成功的依据；应获取最新的用户数据，例如通过 Account API。

如需向用户确认操作已完成，可在账户中心 URL 添加 show_success=true。账户中心会在操作后显示自己的成功页面，用户点击完成后再返回你的 redirect URL：

https://[tenant-id].logto.app/account/password?redirect=https://your-app.com/settings&show_success=true

支持的 URL 参数

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

参数	描述
`redirect`	用户完成操作或使用返回按钮离开后返回的绝对 URL。仅接受 `http(s)` URL。
`show_success`	设为 `true` 时，账户中心在操作后显示成功页面，用户点击完成后返回你的 `redirect` URL。未设置时用户会立即返回。
`identifier`	预填目标页面（`/account/email`、`/account/phone`、`/account/username`）的标识输入。适用于你已知用户标识时从应用深链跳转。
`ui_locales`	以空格分隔的 BCP-47 语言标签列表（如 `fr-CA fr en`），控制账户中心 UI 语言。若省略则回退到用户浏览器语言。

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

https://[tenant-id].logto.app/account/[email protected]&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）即可隐藏账户删除入口。

从账户中心关联社交账号时，会使用连接器的回调 URL：

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

其中 {connectorId} 是社交连接器的 ID。该地址即控制台 > 连接器 > 社交连接器详情页显示的 回调 URI，你在设置连接器时需在社交平台注册。

安全注意事项

预构建账户中心 UI 包含内置安全措施：

OIDC step-up 认证 (Authentication)：敏感更改（邮箱、手机、用户名、密码、社交账号、MFA、会话和可信设备）要求用户在租户配置的近期认证 (Authentication) 窗口（默认 10 分钟，可在控制台 > 登录与账户 > 账户中心配置为 1 到 120 分钟）内完成最近一次认证 (Authentication)（urn:logto:acr:1fa 或更高）。用户刚用合格方式登录或注册时不会额外提示；若登录不含 1fa（如社交登录）或已超时，账户中心会自动执行 OIDC step-up 认证 (Authentication) 并恢复待处理操作。
验证码：邮箱和手机更新需向新地址/号码发送验证码
会话校验：所有操作均校验用户会话，防止未授权访问

个性化选项

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

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

自定义 CSS

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

预构建账户中心 UI 在关键 UI 元素（布局容器、页面标题、分区、卡片等）上提供以 logto_ac- 为前缀的稳定 CSS 类名，方便你精准定制。这让你无需担心版本升级导致类名变化。

示例：

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

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

如果你需要超出预构建 UI 和自定义 CSS 能力的定制，请考虑使用 Account API 自行开发账户管理页面。

通过 Account API 进行账户设置 - 构建自定义账户管理，完全 API 控制
通过 Management API 进行账户设置 - 管理员级账户管理
MFA 配置 - 设置多因素认证 (MFA)
MFA 可信设备 - 配置和管理限时浏览器信任

什么是预构建账户中心 UI​

使用预构建 UI 的优势​

可用页面​

如何使用预构建 UI​

第一步：启用 Account API​

配置资料字段​

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

方式 A：带重定向参数的直接链接​

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

第三步：处理返回你的应用​

支持的 URL 参数​

账户删除链接​

社交连接回调 URL​

安全注意事项​

个性化选项​

自定义 CSS​

相关资源​