透過預建帳號中心 UI 進行帳號設定

什麼是預建帳號中心 UI

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

檢視與編輯使用者個人檔案（姓名、大頭貼、自訂個人欄位）
更新電子郵件地址與手機號碼
更新使用者名稱
設定或更新密碼
管理社交連接（連結與解除連結社交帳號）
管理 MFA 設定（TOTP 驗證器 App、通行密鑰、備用代碼）
開啟或關閉兩步驟驗證
管理活躍工作階段與已授權應用程式

預建帳號中心 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 驗證器 App
`/account/authenticator-app/replace`	更換現有 TOTP 驗證器 App
`/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 則完全隱藏

設定個人檔案欄位

帳號中心會顯示 個人檔案 頁面，讓終端使用者檢視與管理個人資訊。若要控制哪些個人檔案欄位出現在此頁：

確認姓名、大頭貼、個人檔案 或 自訂資料 欄位權限在帳號安全 / 使用者個人檔案區塊設為 Edit 或 ReadOnly。
在 整合預建 UI 卡片中，從個人檔案欄位選擇器新增你想顯示的欄位。這些欄位來自收集使用者個人檔案使用的同一欄位目錄——任何在那裡定義的欄位也可顯示於帳號中心。
拖曳排序欄位順序。

只有同時列於個人檔案欄位且權限非 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>Account Settings</h2>

      <div>
        <span>Email: [email protected]</span>
        <a href={`${tenantEndpoint}/account/email?redirect=${redirectUrl}`}>Update Email</a>
      </div>

      <div>
        <span>Password: ••••••••</span>
        <a href={`${tenantEndpoint}/account/password?redirect=${redirectUrl}`}>Change Password</a>
      </div>

      <div>
        <span>MFA: Not configured</span>
        <a href={`${tenantEndpoint}/account/authenticator-app?redirect=${redirectUrl}`}>
          Set up Authenticator
        </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>Email updated successfully!</div>}
      {showSuccess === 'password' && <div>Password updated successfully!</div>}
      {/* ... rest of your settings page */}
    </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 語言。若未指定則回退至使用者瀏覽器語言。

範例——深度連結到電子郵件更新頁，預先填入目前電子郵件並顯示法文 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）即可隱藏帳號刪除項目。

當使用者從帳號中心連結社交帳號時，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​

相關資源​