Keycloak v26组织功能自定义登录页主题显示异常问题

核心原因 #

你的自定义主题没覆盖分步登录流程的第一步模板文件，或者受Organization功能的模板扩展影响，导致初始用户名页面 fallback 到了Keycloak默认主题。

具体解决步骤 #

• 补全分步登录的模板文件
  Keycloak的分步登录对应两个核心模板：

  1. 初始用户名页：username-login.ftl
  2. 密码输入页：password-login.ftl
     你大概率只复制/修改了password-login.ftl，没处理username-login.ftl。从Keycloak默认的keycloak主题（安装目录themes/keycloak/login下）把username-login.ftl复制到自定义主题的login目录，再根据需求调整样式即可。

• 适配Organization功能的扩展模板
  启用Organization后，Keycloak会加载带organization-前缀的专属模板（比如organization-username-login.ftl），同样需要从默认主题复制这个文件到自定义主题的login目录，确保组织场景下的初始登录页用自定义主题。

• 检查主题继承配置
  打开自定义主题的theme.properties，确认继承设置正确：

  parent=keycloak
  

  这样自定义主题缺失的模板会继承默认，但你已经补全了分步登录的模板，就会优先使用自定义版本。

• 清理Keycloak缓存
  修改主题文件后，要么重启Keycloak服务，要么在Admin Console的「Realm设置」→「主题」里点击「清除缓存」，避免旧缓存导致模板不生效。

• 验证IDP显示逻辑
  在自定义的username-login.ftl里，确保保留默认模板里的IDP选择器引用：

  <#include "includes/idp-selector.ftl"/>
  

  这样用户在初始页面就能看到IDP选项，直接走SSO登录。

内容的提问来源于stack exchange，提问作者Sonal Shinde