Keycloak: 自訂外觀

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

👋 歡迎來到 Stackhero 文件中心！

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

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

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

自訂您的 Keycloak 外觀

登入頁面是使用者首先看到的介面之一。透過 Stackhero，您只需幾分鐘即可打造專屬風格：設定您的顏色、Logo，以及每個支援語言的文字。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 行為。

欲變更項目請編輯此檔案
顏色、Logo、背景、登入字型default/login/resources/css/stackhero.css
登入頁面文字default/login/messages/messages_en.properties
電子郵件主旨與內容default/email/messages/messages_en.properties
明亮或深色主題default/login/theme.properties
帳戶/管理主控台 Logodefault/account/theme.properties, default/admin/theme.properties
登入頁 HTML 結構從 Keycloak 複製 .ftl 檔至 default/login/，再進行編輯

進入 default/login/resources/img/，您會看到目前登入頁所用的兩張圖片。請以上傳相同檔名（keycloak-logo-text.svg）的自家 Logo，然後以 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} 這些佔位符（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 的視覺化主題設計器。可上傳 Logo、選擇顏色、預覽登入與帳戶主控台，並將完成的主題下載為 .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 檔）。顏色、Logo、背景、文字及語言等調整皆無需編輯模板。詳情請參閱 Keycloak 主題官方文件。

Java 擴充套件（providers）

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

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

主題 .jar 檔亦可放於此，但建議主題仍放在 themes/，如此無需重建，且可後續編輯檔案。

Keycloak 的其他文章

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