自帶 UI（Bring your UI）
除了預設的 UI 客製化選項外，Logto 允許你自帶自己的 UI，完全取代內建的登入體驗介面。此功能讓你可以上傳包含自訂 UI 資產（HTML、CSS、JavaScript、圖片等）的 zip 檔，並將其託管於 Logto Cloud 伺服器上，作為租戶使用者的 登入體驗。
此功能要求你的自訂 UI 必須相容於單頁應用程式（SPA, Single Page Application），並建議始終使用正式環境（production build）版本以獲得最佳效能。
在 Logto Console 體驗自訂 UI 功能
使用官方專案快速開始
最快建立自訂登入 UI 的方式是複製 Logto experience 專案。這是 Logto 內建的登入體驗 UI，涵蓋所有功能並遵循 Logto 最佳實踐。你可以根據需求進行自訂。
檢出程式碼後，只需執行以下指令來建置專案：
pnpm install && pnpm build
整個 Logto 專案為 pnpm monorepo。若你想單獨執行 experience 套件（不使用 pnpm），請將 package.json 中的 workspace: 依賴改為具體版本號（如 ^1.0.0）。
建置完成後，所有編譯後的資產會在 dist 目錄下。請將 dist 目錄壓縮成 ZIP 檔，稍後即可上傳至 Logto Cloud。
自訂 UI 資產要求
上傳自訂 UI 資產前，請確保符合以下要求：
- 上傳資產需打包為單一 zip 檔。
- zip 檔根目錄需包含
index.html檔案。 - zip 檔大小不得超過 20MB。
- zip 檔內單一檔案不得超過 10MB。
- zip 檔內檔案總數不得超過 200 個。
上傳自訂 UI 資產
在正式環境使用此功能時請謹慎，因為會立即影響使用者的登入體驗。
- 前往 Console > 登入與帳號 > 品牌設定 > 自帶 UI（Bring your UI）。
- 點擊選擇或拖曳你在前一步建立的 zip 檔，系統會自動開始上傳。
- 上傳完成後，儲存變更，你的自訂 UI 會立即生效。
- 使用自訂登入 UI 時，「登入預覽」視窗將會停用。不過，你仍可點擊「即時預覽」按鈕，在新分頁測試自訂登入頁面。
設定自訂 CSP 來源
Logto 會對自訂 UI 頁面套用內容安全政策（CSP, Content Security Policy）標頭。若你的自訂 UI 需載入第三方腳本或連接外部服務，請在 Console > 登入與帳號 > 品牌設定 > 自帶 UI 中新增額外來源。
你可以設定：
script-src：允許 JavaScript 模組或腳本來源，例如 CAPTCHA、分析、標籤管理服務。connect-src：允許fetch、XMLHttpRequest、EventSource 及 WebSocket 連線的網路端點。
範例：
{
"scriptSrc": ["https://scripts.example.com"],
"connectSrc": ["https://api.example.com", "wss://events.example.com"]
}
兩者皆請使用 HTTPS 來源。connect-src 也接受 WebSocket 連線的 wss:// 來源。Logto 僅在你的自訂 UI 資產啟用時，才會將這些來源附加到現有安全政策。
設定 Cross-Origin-Opener-Policy 標頭
預設情況下，Logto 不會傳送 Cross-Origin-Opener-Policy（COOP）標頭，因此開啟登入頁的應用程式 popup 可透過 window.opener 與其溝通。若你的應用程式不會透過 popup 登入，可以將自訂登入 UI 與其他瀏覽器視窗隔離。在 Console > 登入與帳號 > 品牌設定 > 自帶 UI 下選擇 Cross-Origin-Opener-Policy 的政策：
| 選項 | 傳送的標頭 | 效果 |
|---|---|---|
| 未設定（無標頭） | 無 | 預設值。所有基於 popup 的整合可正常運作。 |
same-origin-allow-popups | Cross-Origin-Opener-Policy: same-origin-allow-popups | 切斷開啟登入頁的視窗。自訂 UI 開啟的 popup 只要停留在其他網站仍保有 window.opener。 |
same-origin | Cross-Origin-Opener-Policy: same-origin | 也會切斷自訂 UI 開啟的 popup。 |
你也可以透過 更新登入體驗 Management API 設定 crossOriginOpenerPolicy 欄位。可接受 unsafe-none（預設，不傳送標頭）、same-origin-allow-popups 與 same-origin。
選擇政策前，請檢查你的應用程式與自訂 UI 如何使用 popup：
- 會在 popup 開啟登入頁並依賴
window.opener（例如透過postMessage傳遞結果）的應用程式，在啟用任一政策後將無法運作。若有此類應用，請維持預設值，或先改為導向式登入流程。 - 自訂 UI 開啟的 popup 回到自訂 UI（如社交登入 callback 頁）時會失去
window.opener。若 popup 停留在其他網站並從那裡傳送結果（如第三方登入 popup），在same-origin-allow-popups下仍可運作。若選same-origin，popup 一開啟即失去window.opener。
如需設定，建議優先選擇 same-origin-allow-popups。
Logto 僅在自訂 UI 資產被服務時傳送該標頭。內建登入頁、/oidc/* 頁面與帳號中心（/account）皆不會傳送 COOP 標頭，因此安全掃描工具可能仍會在這些頁面報告缺失。
開發你的自訂 UI
與 Experience API 互動
你的自訂 UI 需與 Experience API 互動，以執行登入、註冊、重設密碼、綁定社交帳號、啟用 MFA 等多種操作。為深入瞭解使用者流程與實作細節，建議參考我們的 Experience API 設計 RFC，內含完整技術規格與範例。
你也需要透過 sign-in Experience API endpoint 取得其他登入體驗設定，如品牌色、公司 logo、favicon、密碼政策、本地化語言字串，甚至自訂 CSS。
啟用 CAPTCHA 時的處理方式
Logto 內建登入體驗會自動處理 CAPTCHA。若你的租戶使用自帶 UI 並啟用 CAPTCHA 機器人防護，你的自訂 UI 必須在呼叫 PUT /api/experience 前完成前端 CAPTCHA 整合。
請將驗證服務回傳的 token 作為 captchaToken，放入 PUT /api/experience 請求主體。詳情請參閱各服務提供者指南：
範例專案
我們提供多個範例專案，協助你快速瞭解並開始實作自訂 UI。詳情請參閱 Logto Experience project GitHub 倉庫。
此外，我們將持續推出更多簡化且情境導向的範例專案，涵蓋最常見的使用情境，敬請期待未來更新！
本地開發與除錯
針對本地開發與除錯，我們提供 Logto Tunnel CLI 工具，可：
- 將本機 Experience API 請求代理到 Logto Cloud 端點。
- 在本地測試你的自訂 UI 實作。
這讓你能在上傳至 Logto Cloud 前，於本地測試與除錯自訂 UI。
請參閱 本地除錯與測試自訂 UI 以取得更多資訊。
使用 CLI 上傳自訂 UI 資產
除了透過 Console 上傳外，你也可以使用 Logto CLI 上傳自訂 UI 資產，特別適合自動化部署流程。
詳情請參閱 使用 CLI 上傳自訂 UI 資產。
還原為 Logto 內建登入體驗
若你希望還原為 Logto 內建登入體驗，只需點擊自帶 UI 卡片上的刪除按鈕。儲存變更後，登入體驗 UI 即會回復為 Logto 預設樣式。
相關資源
RFCS：Experience API
Experience samples 將自訂登入 UI 帶到 Logto Cloud