如何在Keycloak中添加自定义模板及自定义标签页

Keycloak新增自定义标签页实现方案 #

以下是两种常用的落地方式，可根据你的使用场景选择：

方案1：自定义主题扩展（适用于用户账户端、登录端新增标签，无需后端代码开发） #

• 在自定义主题目录下创建对应模块的文件夹，例如要给账户控制台加标签，就新建themes/<自定义主题名>/account/目录
• 复制Keycloak原生模板中的page.ftl到上述目录，找到标签导航的代码块，新增自定义标签项，示例代码如下：

<li<#if section == 'custom-tab'> class="active"</#if>>
    <a href="${url.accountUrl}?tab=custom-tab">自定义标签名称</a>
</li>

• 新增对应标签的模板文件custom-tab.ftl，直接在文件内编写你需要的页面内容，Keycloak内置的用户信息、路径等变量可以直接参考原生模板的用法调用
• 进入Keycloak管理后台，在对应领域的「主题」设置页，把对应模块的主题切换为你自定义的主题，保存后刷新即可生效

方案2：Admin Console SPI扩展（适用于给管理控制台新增自定义标签，需要Java开发） #

• 新建Maven项目，引入keycloak-admin-ui-spi等核心Keycloak依赖
• 实现AdminPage接口，定义自定义标签页的路由、显示名称、对应前端资源路径
• 实现AdminConsoleSpi接口，注册你刚才编写的自定义页面
• 将项目打包为jar包，放入Keycloak的providers/目录
• 执行kc.sh build（Quarkus版Keycloak）或重启WildFly版Keycloak，启动完成后即可在管理控制台看到新增的标签页
• 如果需要后端交互逻辑，可以同步实现REST SPI提供对应接口给自定义页面调用

注意事项 #

• Keycloak大版本升级时需要检查自定义模板、SPI扩展的兼容性，版本变动可能导致模板语法或SPI接口变更
• 自定义页面需要做好权限校验，避免未授权用户访问敏感内容

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