Keycloak客户端条件重定向需求：实现维护页跳转功能

1. 给客户端添加自定义控制属性 #

先给目标客户端配置两个自定义属性，用来控制维护模式开关和重定向地址：

• 登录Keycloak管理控制台，进入目标客户端的「属性」标签页
• 添加以下两个属性：
  • maintenance_mode_enabled：值设为true或false，用来切换维护模式
  • maintenance_redirect_url：填写需要重定向到的维护页URL

2. 开发自定义认证器SPI #

通过扩展Keycloak的认证流程，在用户登录环节检查维护状态：

• 编写Java类实现Authenticator接口，核心逻辑在authenticate方法：

  @Override
  public void authenticate(AuthenticationFlowContext context) {
      ClientModel client = context.getClient();
      boolean isMaintenanceOn = Boolean.parseBoolean(client.getAttribute("maintenance_mode_enabled"));
      String redirectUrl = client.getAttribute("maintenance_redirect_url");
  
      if (isMaintenanceOn && redirectUrl != null && !redirectUrl.isEmpty()) {
          // 直接重定向到维护页，终止当前认证流程
          context.redirectUri(redirectUrl);
          return;
      }
      // 未开启维护模式，继续执行正常登录流程
      context.success();
  }
  

• 配套实现AuthenticatorFactory类，将自定义认证器注册到Keycloak，设置好显示名称、适用场景等信息
• 将代码打包为JAR文件，放到Keycloak安装目录的providers文件夹下，重启Keycloak生效

3. 配置客户端的认证流程 #

把自定义认证器加入客户端的登录流程：

• 在管理控制台的「认证」>「流程」页面，复制默认的「浏览器认证流程」，命名为类似「带维护模式检查的浏览器流程」
• 编辑复制后的流程，在「表单之前」节点下添加自定义认证器，设置为「REQUIRED」
• 回到目标客户端的「认证流程」标签页，将「浏览器流程」切换为这个自定义流程

4. 拦截已登录用户的会话 #

若需要让已登录的用户也被重定向到维护页，需开发事件监听器SPI：

• 编写Java类实现EventListenerProvider接口，监听登录和刷新令牌事件：

  @Override
  public void onEvent(Event event) {
      if (EventType.LOGIN.equals(event.getType()) || EventType.REFRESH_TOKEN.equals(event.getType())) {
          try (KeycloakSession session = sessionFactory.create()) {
              ClientModel client = session.clients().getClientById(event.getClientId());
              boolean isMaintenanceOn = Boolean.parseBoolean(client.getAttribute("maintenance_mode_enabled"));
              String redirectUrl = client.getAttribute("maintenance_redirect_url");
  
              if (isMaintenanceOn && redirectUrl != null && !redirectUrl.isEmpty()) {
                  // 找到用户会话并强制登出
                  UserSessionModel userSession = session.sessions().getUserSession(event.getRealmId(), event.getSessionId());
                  if (userSession != null) {
                      session.sessions().removeUserSession(session.realms().getRealm(event.getRealmId()), userSession);
                      // 可结合HttpServletResponse发送302重定向到维护页
                  }
              }
          }
      }
  }
  

• 同样注册监听器的Factory类，打包部署到providers目录

5. 可选：优化控制台操作体验 #

如果不想手动添加属性，可扩展Admin Console的UI：

• 编写前端组件，在客户端详情页添加开关和URL输入框，直接绑定到自定义属性
• 将组件打包为主题扩展，放到Keycloak的themes目录，然后在控制台设置使用该自定义主题

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