透過預建帳號中心 UI 管理帳號設定

什麼是預建帳號中心 UI

Logto 提供預建的帳號中心 UI，為終端使用者提供現成的帳號設定管理頁面。這個預建 UI 由 Logto 託管，處理常見的帳號管理任務，包括：

更新電子郵件地址與手機號碼
更新使用者名稱
設定或更新密碼
管理社交連結（連結與解除連結社交帳號）
管理多重要素驗證 (MFA) 設定（TOTP 驗證器應用程式、通行密鑰、備用代碼）
開啟或關閉兩步驟驗證
管理活躍工作階段與已授權應用程式

預建帳號中心 UI 設計上可與你的應用程式無縫整合，提供一致的使用者體驗，無需你自行開發帳號管理頁面。

使用預建 UI 的好處

零開發成本：現成可用的頁面，開箱即用
一致體驗：與 Logto 登入體驗風格一致
內建安全性：所有驗證流程與安全措施自動處理
自動更新：新功能與安全性改進自動獲得

可用頁面

預建帳號中心 UI 提供以下頁面，皆可透過你的 Logto 租戶端點下的 /account 路徑存取：

路徑	說明
`/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

步驟 1：啟用 Account API

預建帳號中心 UI 依賴 Account API。請前往主控台 > 登入與帳號 > 帳號中心並啟用 Account API。

根據需求設定欄位權限：

欄位設為 Edit 允許使用者修改
欄位設為 ReadOnly 僅允許檢視
欄位設為 Off 完全隱藏

步驟 2：從你的應用程式連結到預建頁面

要使用預建帳號中心 UI，你需將使用者從應用程式導向適當的 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>
  );
}

步驟 3：處理成功導回

使用者完成操作後，會被導回你指定的 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 後加上下列查詢參數，以調整體驗：

參數	說明
`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`），控制帳號中心 UI 語言。若未指定則回退至使用者瀏覽器語言。

範例 — 以目前電子郵件預填並以法文顯示的電子郵件更新頁深度連結：

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 會使用與一般登入流程不同的 redirect URI。帳號中心回呼 URL 格式如下：

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

其中 {connectorId} 為社交連接器 ID（可於主控台 > 連接器 > 社交連接器查詢）。

警告:

你必須將此 URL 加入社交服務商（Google、GitHub、Facebook 等）開發者主控台的 授權 redirect URI（或同等設定）清單，且需額外於標準登入回呼 URL https://[your-tenant-endpoint]/callback/{connectorId} 之外。否則連結流程會因 redirect URI 不符而失敗。

安全性考量

預建帳號中心 UI 內建多項安全措施：

身分驗證：進行敏感變更（電子郵件、手機、密碼、MFA）前，使用者必須以現有密碼或驗證方式驗證身分
驗證碼：電子郵件與手機更新需輸入發送至新地址／號碼的驗證碼
工作階段驗證：所有操作都會驗證使用者的工作階段，防止未授權存取

客製化選項

預建帳號中心 UI 會繼承你的登入體驗設定品牌，包括：

標誌與配色
深色／淺色模式
語言設定

自訂 CSS

你可以進一步透過自訂 CSS 客製帳號中心 UI 外觀。請前往主控台 > 登入與帳號 > 帳號中心，於 自訂 CSS 編輯器新增你的 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)

什麼是預建帳號中心 UI​

使用預建 UI 的好處​

可用頁面​

如何使用預建 UI​

步驟 1：啟用 Account API​

步驟 2：從你的應用程式連結到預建頁面​

方式 A：直接連結並帶上 redirect 參數​

方式 B：嵌入於你的帳號設定流程​

步驟 3：處理成功導回​

支援的 URL 參數​

帳號刪除連結​

社交連結回呼 URL​

安全性考量​

客製化選項​

自訂 CSS​

相關資源​