Keycloak: 自訂外觀

在 Stackhero 上輕鬆為您的 Keycloak 登入頁面、帳戶控制台及電郵進行品牌化：設定您的顏色、標誌、文字，甚至可利用內置的線上編輯器建立完整自訂主題。

👋 歡迎瀏覽 Stackhero 文件！

Stackhero 提供 Keycloak cloud 服務，讓您只需 2 分鐘即可輕鬆部署一個可用於生產環境的身份認證服務：

  • 無限用戶、realms 及 clients
  • 支援 OpenID Connect、OAuth 2.0、SAML 2.0、社交登入、LDAP 及 Active Directory 聯合
  • 自訂網域名稱，內建 HTTPS，確保安全連線（例如 https://login.your-company.com）
  • 自訂主題：可利用內置的線上編輯器輕鬆為登入頁面、帳戶控制台及電郵加上您的品牌風格
  • 專屬 電郵伺服器，支援 SPF、DKIM 及 DMARC，協助您自動處理帳戶確認及重設密碼
  • 內建 PostgreSQL 資料庫，管理控制台可於獨立且可關閉的連接埠上存取
  • 一鍵更新，讓您的系統隨時保持最新，無需手動操作

專注於開發，無需煩惱設定：您可以在 5 分鐘內體驗 Stackhero 的 Keycloak cloud 解決方案。

自訂您的 Keycloak 外觀

登入頁面是用戶最先看到的介面之一。透過 Stackhero，您只需幾分鐘即可打造專屬風格：設定您的顏色、標誌，以及支援語言的文字。Keycloak 發送的電郵也可用同樣方式自訂。

您的服務包含兩個主要工具：

  • 主題編輯器：一個線上檔案編輯器，您的主題就儲存在這裡。
  • Quick Theme：內建於 Keycloak 管理控制台的視覺化主題設計工具，讓您無需編輯 CSS 也能選擇顏色與品牌元素。

無需 SSH、重建或重新部署。

開啟主題編輯器

在 Stackhero 控制台 的服務頁面，您會在管理控制台旁找到 Themes editor 的網址：

https://your-domain.com:4443/stackhero_themes/

請使用您的 Keycloak 管理員憑證登入，這與您登入管理控制台時相同。

請注意以下兩點：

  • 編輯器運行於管理埠，而非您的應用程式所用的埠。如果您在 Stackhero 防火牆中關閉該埠，管理控制台及編輯器都將無法存取，但您的應用程式仍可正常驗證。
  • 您在這裡的所有更改都儲存在服務磁碟上，會包含於備份中，並可於重啟及更新後保留。

您會看到兩個目錄：

目錄用途
themes/控制登入頁、帳戶控制台及電郵的外觀。
providers/Java 擴充（.jar 檔案），用於進階 Keycloak 客製化。

每個目錄都包含一個 README.md 檔案，內容為符合您服務版本的最新說明。

您的主題已可立即編輯

打開 themes/，您會看到一個 default/ 目錄。這就是您的啟用主題，已被您的 Keycloak 實例使用。無需選擇，只需直接編輯其檔案，變更會即時反映。

您無需具備 Keycloak 主題的先前知識。**每個檔案內都已列出常見可調整設定，並以註解方式顯示目前 Keycloak 的預設值作為範例。**如要更新值，只需移除註解符號，調整數值並儲存即可。

若某行仍為註解，Keycloak 會採用其預設值。這可確保您的服務即使更新後，仍維持標準 Keycloak 行為。

要更改的項目編輯此檔案
顏色、標誌、背景、登入字型default/login/resources/css/stackhero.css
登入頁文字default/login/messages/messages_en.properties
電郵主旨與內容default/email/messages/messages_en.properties
明亮或深色主題default/login/theme.properties
帳戶/管理控制台標誌default/account/theme.properties, default/admin/theme.properties
登入頁 HTML 結構從 Keycloak 複製 .ftl 檔到 default/login/，然後編輯

更新您的標誌

打開 default/login/resources/img/。您會看到目前登入頁所用的兩個圖片。請以上傳與現有檔名相同的檔案（keycloak-logo-text.svg）來替換您的標誌，然後用 Ctrl+F5（macOS 請用 Cmd+Shift+R）重新整理登入頁。

這樣就完成了。無需編輯其他檔案或重啟服務，儲存後即時生效。如要更換背景圖片，請在同一資料夾內更新 keycloak-bg-darken.svg。

若您想用不同檔名，可在 default/login/resources/css/stackhero.css 的「Your logo」區段更新引用。

設定您的顏色

在 stackhero.css 中，您會看到已寫入目前值的變數：

:root {
  /* ---------- Colors ---------- */
  /* The buttons */
  /* --pf-v5-global--primary-color--100: #06c; */
  /* The buttons, while hovered */
  /* --pf-v5-global--primary-color--200: #004080; */
  /* The links */
  /* --pf-v5-global--link--Color: #06c; */
  /* The colored line on top of the login box */
  /* --keycloak-card-top-color: #06c; */

要套用變更，移除註解符號，設定您的顏色，儲存並重新載入頁面即可。

編輯時注意： 您的瀏覽器會將主題 CSS、圖片及腳本快取一小時。測試時請務必用 Ctrl+F5 強制重新載入，以看到最新變更。訪客會在一小時內看到更新。

您擁有完全控制權：這是純 CSS 檔案，最後載入，可覆蓋任何樣式。請用瀏覽器 DevTools（F12）檢查元素。Keycloak 26 採用 PatternFly design system，大多數顏色變數為 --pf-v5-global--*，可於 :root 重新定義。

設定您的公司名稱

這不需編輯主題。在管理控制台中，打開 Realm settings > General，設定 Display name。此名稱將顯示於登入頁及電郵中。

多語言文字變更

您可不需動 CSS 或 HTML 直接修改文字。在 default/login/messages/messages_en.properties 內，您會找到所有登入表單的預設文字。要更改，只需移除 #，輸入您的內容並儲存：

loginAccountTitle=Sign in to Acme
doLogIn=Sign in
doForgotPassword=I forgot my password

如需支援法文、德文等，新增如 messages_fr.properties、messages_de.properties 等檔案，並於管理控制台 Realm settings > Localization 啟用相關語言。

提示：Localization 分頁亦設有 Realm overrides 區段，讓您可直接於控制台內變更文字，無需編輯檔案或重啟。請選擇最適合您工作流程的方法。

為電郵加上品牌

Keycloak 會發送電郵以進行地址確認、密碼重設及用戶邀請。在 default/email/messages/messages_en.properties 內，您可自訂標準主旨與內容：

emailVerificationSubject=Confirm your Acme account
passwordResetSubject=Reset your Acme password

編輯電郵內容時請注意：

  • 保留 {0}、{1}、{2} 這些 placeholder（Keycloak 會自動填入連結、顯示名稱及延遲時間）。
  • 單引號需用兩個（如 don''t）來跳脫。

如要覆蓋電郵 HTML，請從 Keycloak base email theme 複製所需模板到 default/email/html/，再編輯您的副本。

Stackhero 已為您設定好電郵發送，包括 SPF、DKIM 及 DMARC。請於 Realm settings > Email 以服務頁提供的主機及埠號設定。

若需重設主題

如遇問題，您可刪除整個 default 目錄並重啟服務。Stackhero 會自動建立全新預設主題，還原標準 Keycloak 外觀。

您的 realms、用戶及 clients 均儲存在資料庫中，不會受影響。

以 Quick Theme 視覺化設計主題

在 Keycloak 管理控制台內，您會找到 Quick Theme，Keycloak 的視覺化主題設計工具。您可上傳標誌、選擇顏色、預覽登入及帳戶控制台，並將完成的主題下載為 .jar 檔案。

安裝方式：將檔案放入 themes/ 目錄（透過編輯器），然後重啟服務。.jar 會自動解壓到主題目錄，原始壓縮檔會被移除：

themes/acme.jar        becomes     themes/acme/

新主題會出現在 Realm settings > Themes。您可繼續手動編輯其檔案。

此方法同樣支援以 Keycloakify 製作或設計師提供的主題。任何包含主題的 .jar 或 .zip 檔案皆可用此方式安裝。如已有同名主題，新主題會以 acme-1 安裝，確保不會覆蓋現有內容。若檔案不是主題，則會被忽略，Keycloak 會如常啟動。

每個 realm 一個品牌：支援白標方案

主題可於 Realm settings > Themes 依 realm 選擇，並可針對每種頁面類型（登入、帳戶、管理、電郵）分別設定。個別應用程式亦可於 client 設定中指定專屬登入主題。

如您經營多品牌或提供白標解決方案，請為每個品牌建立一個 realm，並分配專屬主題：

  1. 在編輯器中複製 default 目錄並重新命名（如 acme）。
  2. 重啟服務。
  3. 在管理控制台打開相關 realm，並選擇 acme 作為其登入主題。

未特別設定的 realm 會繼續使用您的 default 主題。

Keycloak 主題結構說明

主題是一個目錄，內含各頁面類型的子目錄：

themes/
  acme/
    login/                             # 用戶登入頁
      theme.properties                 # 主題繼承與 CSS 引用
      resources/css/stackhero.css      # 您的 CSS
      resources/img/logo.svg           # 您的圖片
      messages/messages_en.properties  # 您的文字
    account/                           # 用戶資料管理
    admin/                             # 管理控制台外觀
    email/                             # 電郵模板

主題會繼承標準 Keycloak 主題，只需覆蓋所需部分。典型的 login/theme.properties 如下：

parent=keycloak.v2
styles=css/styles.css css/stackhero.css
  • parent 設定基礎主題。
  • styles 列出要載入的 CSS 檔案。請將您的 CSS 放在最後，以確保變更生效。

styles 列表會取代父主題的列表，而非擴充。請務必包含父主題的樣式表（css/styles.css），否則頁面將失去預設樣式。

只有在需要更改 HTML 結構時，才需 FreeMarker 模板（.ftl 檔案）。如只需調整顏色、標誌、背景、文字及語言，無需編輯模板。詳情請參閱 Keycloak 主題官方文件。

Java 擴充（providers）

providers/ 目錄用於主題無法實現的功能：自訂認證器、用戶儲存、事件監聽器或協定映射器等。

將您的 .jar 檔案放入此目錄並重啟服務。這次重啟會較久（約一分鐘），因 Keycloak 需重建以納入新擴充。如要移除擴充，刪除檔案並再次重啟。

您亦可將主題 .jar 檔案放在這裡，但建議主題仍放於 themes/：這樣無需重建，且可隨時編輯檔案。

Keycloak 的其他文章

  1. 使用 CLI 自動化操作
    透過 Stackhero CLI 程式化啟動 Keycloak、取得其認證資料，以及變更其設定