Keycloak自定义登录页主题：HTML动态参数修改困惑求助

你犯了一个典型的错误：直接复制浏览器渲染后的静态HTML来做主题是行不通的。Keycloak的页面是基于Freemarker模板生成的，那些带session_code、execution的动态参数都是模板在运行时填充的，硬编码静态值肯定失效。

下面是正确的操作步骤：

1. 搭建自定义主题的基础结构 #

不要从浏览器扒代码，直接复制Keycloak自带的主题作为基础：

• 找到Keycloak安装目录下的themes文件夹，复制base或keycloak主题文件夹，重命名为你的自定义主题名（比如my-custom-theme）。
• 保留主题内的目录结构：login（登录相关模板）、css、js、messages等。

2. 理解Freemarker模板的动态变量 #

登录页的核心模板是my-custom-theme/login/login.ftl，里面用Freemarker变量来动态生成关键内容：

• 你提到的form的action属性，模板里应该写成 ${url.loginAction}，而不是硬编码的URL，Keycloak会自动填充session_code、execution这些动态参数。
• 比如正确的form代码应该是：

<form id="kc-form-login" onsubmit="login.disabled = true; return true;" action="${url.loginAction}" method="post">

• 其他动态内容比如客户端ID、csrf令牌也都是用模板变量（比如${csrf.token}），不要手动写死。

3. 修改HTML结构的正确姿势 #

• 只在login.ftl里调整布局：比如添加自定义logo、调整表单元素顺序、增加额外的提示文本，保留所有Keycloak自带的模板变量和宏（比如<@kc.formData />用来渲染表单字段）。
• 不要删除或修改模板变量，否则会破坏登录流程的动态逻辑。

4. 应用并调试自定义主题 #

• 把自定义主题文件夹放到Keycloak的themes目录下。
• 登录Keycloak管理后台，进入目标Realm的Realm Settings → Themes，在Login Theme下拉框选择你的自定义主题。
• 调试时可以关闭Keycloak的主题缓存：在standalone.xml（或application.properties，如果是Quarkus版本）里设置theme.cache.themes=false和theme.cache.templates=false，修改后刷新页面就能看到效果。

常见误区提醒 #

• 不要复制浏览器渲染后的静态HTML，必须基于Freemarker模板修改。
• 所有动态参数（session_code、execution、csrf令牌等）都由Keycloak的模板引擎自动填充，不需要手动处理。

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