Keycloak自定义密码重置主题报错：无法发送重置邮件

操作回顾 #

为Keycloak配置自定义密码重置邮件主题的步骤：

• 在/opt/keycloak/themes路径下创建myTheme文件夹
• 在myTheme内创建email文件夹
• email目录下新建messages文件夹和theme.properties文件
• theme.properties配置内容：

  parent=base
  import=common/keycloakb
  

• 在messages/messages_en.properties中设置passwordResetSubject=My Custom password recovery（仅修改邮件主题）

报错信息 #

KC-SERVICES0026: 发送密码重置邮件失败: org.keycloak.email.EmailException: 模板邮件处理失败
根源异常：org.keycloak.theme.FreeMarkerException: 处理模板text/password-reset.ftl失败

问题原因 #

1. theme.properties中的import配置拼写错误：keycloakb应为keycloak，导致Keycloak无法加载公共主题的基础模板文件。
2. 自定义主题未正确继承父主题（base）的模板资源，系统找不到password-reset.ftl模板文件。

解决步骤 #

1. 修正theme.properties配置
   将文件内容修改为：

   parent=base
   import=common/keycloak
   

2. 保留现有消息配置
   无需添加额外的FTL模板文件，Keycloak会自动从父主题（base）加载password-reset.ftl模板，仅使用自定义的邮件主题配置。

3. 应用主题配置

   • 登录Keycloak管理控制台，进入目标Realm
   • 导航至领域设置 -> 主题
   • 将邮件主题设置为myTheme，保存更改

4. 重启Keycloak服务（若为生产环境），确保配置生效。

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