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 标准外观。

您的 realm、用户和 client 数据都保存在数据库中，不受影响。

用 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、获取其凭证并更改其配置