Keycloak如何自定义过期操作令牌页面并添加重发邮件等操作？

存在官方支持的方式来实现这个需求，主要分为主题自定义、SPI扩展两种核心方案，以下是具体操作：

一、自定义主题错误页模板 #

Keycloak的主题系统允许直接修改错误页面的渲染逻辑，步骤如下：

1. 复制Keycloak默认主题（比如base或keycloak主题）到自定义主题目录，找到错误页模板error.ftl（FreeMarker格式）。
2. 在模板中通过${error.errorMessage}或${error.errorSummary}判断当前错误是否为操作过期（比如匹配中文的“操作已过期”或英文的"Action expired"）。
3. 针对该错误类型添加自定义操作按钮：
   • 返回登录：直接链接到Keycloak登录端点，示例代码：

     <#if error.errorMessage?contains("操作已过期")>
         <a href="${url.loginUrl}" class="kc-button kc-button-primary">返回登录</a>
     </#if>
     

   • 重发邮件：如果是邮箱验证类操作过期，可引导用户进入账户管理页面触发重发流程；若需直接触发，可在模板中添加表单提交到Keycloak的账户REST API端点（需处理权限，确保用户身份合法）。

二、通过SPI扩展错误处理逻辑 #

Keycloak提供ErrorPageProvider SPI，允许完全自定义错误页的渲染逻辑：

1. 实现org.keycloak.error.ErrorPageProvider接口，在createErrorPage方法中判断错误类型是否为ACTION_EXPIRED（可通过error.getError()获取错误标识）。
2. 针对该错误类型，构建自定义的HTML响应，包含“重发邮件”“返回登录”按钮，甚至可以直接调用Keycloak的Admin API触发重发邮件操作（需配置合适的权限）。
3. 将扩展打包为JAR文件，部署到Keycloak的providers目录，然后在Keycloak管理控制台的“Providers”页面启用该扩展。

三、前端拦截处理（非侵入式方案） #

若不想修改Keycloak服务端，可在前端层面处理：

• 监听Keycloak错误页的URL参数（比如error=action_expired），当检测到该参数时，替换为自定义的前端页面，页面上添加“返回登录”和“重发邮件”按钮。
• 重发邮件功能可通过调用Keycloak的Account REST API实现，需确保用户已登录或完成身份验证。

需要注意的是，默认错误模板暴露的属性确实有限，但通过错误信息匹配或SPI扩展可以获取足够的上下文来实现自定义操作。

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