Keycloak: 自定义外观

在 Stackhero 上轻松为您的 Keycloak 登录页面、账户控制台和邮件进行品牌定制：设置您的配色、Logo、文本，甚至可通过内置在线编辑器创建完整的自定义主题。

👋 欢迎查阅 Stackhero 文档！

Stackhero 提供 Keycloak 云服务，让您仅需 2 分钟即可轻松部署一套可用于生产环境的身份认证服务：

  • 无限量用户、realm 和 client
  • 支持 OpenID Connect、OAuth 2.0、SAML 2.0、社交登录、LDAP 及 Active Directory 联邦
  • 自定义域名，内置 HTTPS，保障安全访问（例如，https://login.your-company.com）
  • 自定义主题：通过内置在线编辑器，轻松定制登录页面、账户控制台和邮件的品牌风格
  • 专属 邮件服务器，支持 SPF、DKIM 和 DMARC，自动处理账户确认和密码重置
  • 内置 PostgreSQL 数据库，管理控制台可通过独立端口访问并支持关闭
  • 一键升级，系统自动保持最新，无需手动干预

专注于开发，而非配置：您可以在 5 分钟内体验 Stackhero 的 Keycloak 云解决方案。

自定义您的 Keycloak 外观

登录页面是用户首先看到的界面之一。借助 Stackhero，您可以在几分钟内将其个性化：为每种支持的语言设置专属配色、Logo 和文案。Keycloak 发送的邮件同样可以用这种方式进行定制。

您的服务包含两大主要工具：

  • 主题编辑器：一个在线文件编辑器，您的主题文件都在这里管理。
  • Quick Theme：集成在 Keycloak 管理控制台中的可视化主题设计器，无需编辑 CSS 即可选择配色和品牌元素。

无需 SSH、无需重构、无需重新部署。

打开主题编辑器

在 Stackhero 控制台 的服务页面，您会在管理控制台旁边看到一个 Themes editor 链接：

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

请使用您的 Keycloak 管理员凭据 登录（与管理控制台相同的账号密码）。

请注意以下两点：

  • 编辑器运行在管理端口，而不是您的应用程序所用的端口。如果您在 Stackhero 防火墙中关闭了该端口，管理控制台和编辑器都将无法访问，但您的应用程序仍可正常进行身份验证。
  • 您在此处的所有更改都保存在服务磁盘上，包含在备份中，并在重启或升级后依然有效。

您会看到两个目录：

目录用途
themes/登录页面、账户控制台和邮件的外观定制。
providers/用于高级 Keycloak 定制的 Java 扩展（.jar 文件）。

每个目录下都包含一个 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 设计系统，大多数颜色变量以 --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 基础邮件主题 复制所需模板到 default/email/html/，然后编辑副本。

Stackhero 已为您配置好邮件发送，包括 SPF、DKIM 和 DMARC。请在 Realm settings > Email 中，使用服务页面提供的主机和端口进行设置。

需要重置主题时

如遇问题，您可以删除整个 default 目录并重启服务。Stackhero 会自动生成全新默认主题，恢复 Keycloak 标准外观。

您的 realm、用户和客户端信息都存储在数据库中，不会受到影响。

使用 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 选择，并可针对每种页面类型（登录、账户、管理、邮件）分别设置。各应用也可在客户端设置中指定自己的登录主题。

如需管理多个品牌或提供白标服务，可为每个品牌使用一个 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、获取其凭据并更改其配置