Keycloak事件日志移除敏感字段（如用户名）的最佳实践

先明确日志来源 #

你提到的user_not_found、resolve_required_actions这类事件日志，主要来自Keycloak的两个核心模块：

• 认证端点的请求处理日志（由org.keycloak.authentication包下的组件输出）
• 内置的jboss-logging事件监听器，会将事件详情（含用户名）写入日志

移除敏感信息的具体方案 #

1. 通过日志配置直接过滤敏感字段

根据Keycloak版本不同，调整对应配置文件：

• Quarkus版本（Keycloak 17+）
  编辑conf/quarkus.properties，添加精准的日志过滤规则：

  # 过滤user_not_found事件中的用户名
  quarkus.log.filter."user-not-found-filter".pattern=user_not_found.*username=.*
  quarkus.log.filter."user-not-found-filter".level=OFF
  # 过滤resolve_required_actions事件中的用户名
  quarkus.log.filter."resolve-actions-filter".pattern=resolve_required_actions.*username=.*
  quarkus.log.filter."resolve-actions-filter".level=OFF
  

  若需要全局屏蔽含用户名的日志行，可替换为更通用的规则：

  quarkus.log.filter."sensitive-data-filter".pattern=.*username=.*
  quarkus.log.filter."sensitive-data-filter".level=OFF
  

  注意：全局过滤可能会影响正常日志排查，建议优先用事件类型精准过滤。

• WildFly传统版本（Keycloak 16及以下）
  编辑standalone/configuration/standalone.xml，在日志子系统中添加过滤器：

  <subsystem xmlns="urn:jboss:domain:logging:8.0">
      <!-- 添加敏感字段过滤器 -->
      <filter-spec name="sensitive-filter">
          <not>
              <match pattern=".*username=.*"/>
          </not>
      </filter-spec>
      <!-- 将过滤器绑定到控制台和文件处理器 -->
      <console-handler name="CONSOLE">
          <filter-ref name="sensitive-filter"/>
          <!-- 原有配置 -->
      </console-handler>
      <file-handler name="FILE">
          <filter-ref name="sensitive-filter"/>
          <!-- 原有配置 -->
      </file-handler>
  </subsystem>
  

2. 自定义事件监听器替换默认监听器

默认的jboss-logging监听器会输出完整事件详情，你可以自定义监听器屏蔽敏感字段：

1. 编写实现EventListenerProvider的Java类，在事件处理时移除用户名：

   public class SensitiveFilterEventListener implements EventListenerProvider {
       @Override
       public void onEvent(Event event) {
           // 针对目标事件移除用户名参数
           if (EventType.USER_NOT_FOUND.equals(event.getType()) 
               || EventType.RESOLVE_REQUIRED_ACTIONS.equals(event.getType())) {
               event.getDetails().remove("username");
           }
           // 调用原日志输出逻辑或自定义输出
           Logger.getLogger(getClass()).info(event.toString());
       }
   
       @Override
       public void onEvent(AdminEvent event, boolean includeRepresentation) {
           // 如需屏蔽管理事件中的敏感信息，可在此处理
       }
   
       @Override
       public void close() {}
   }
   

2. 将类打包成JAR放入Keycloak的providers目录，重启服务。
3. 在管理控制台的Events > Config页面，移除默认的jboss-logging监听器，添加自定义监听器。

3. 隐藏管理控制台中的敏感信息

管理控制台的事件详情页面默认会显示用户名，可通过自定义主题隐藏：

1. 复制默认keycloak主题到themes/custom目录。
2. 编辑themes/custom/admin/resources/partials/events/event-detail.html，删除或注释显示用户名的代码块：

   <!-- 移除该块内容 -->
   <div class="form-group">
       <label>Username</label>
       <p>{{event.detail.username}}</p>
   </div>
   

3. 在Realm Settings > Themes中，将Admin Theme切换为custom，刷新控制台即可生效。

4. 额外安全强化

• 开启内置敏感数据屏蔽：在配置文件中添加

  # Quarkus版本
  keycloak.mask-sensitive-data=true
  # WildFly版本
  <system-properties>
      <property name="keycloak.mask-sensitive-data" value="true"/>
  </system-properties>
  

  该配置会自动屏蔽部分敏感字段，可与上述方案配合使用。
• 定期检查日志输出，确保没有其他渠道泄露敏感信息。

内容的提问来源于stack exchange，提问作者Moritz Schmitz v. Hülst