Apereo CAS Groovy 审计（Groovy Audits）：用 Groovy 模板完全定制审计记录的输出

后端认证鉴权单点登录【免费下载链接】casApereo CAS - Identity Single Sign On for all earthlings and beyond.项目地址https://gitcode.com/gh_mirrors/ca/cas点击查看免费下载Apereo CAS 内置了多种审计Audit记录实现其中 Groovy 审计是灵活性最高的一种它允许通过一段 Groovy 模板脚本来接收审计上下文中的全部参数操作者、被操作资源、时间、IP、HTTP 请求头、自定义附加信息等并按任意文本格式拼装最终的审计记录再交给日志框架以INFO级别输出。读完本文你将掌握如何启用cas.audit.groovy配置、编写可用的 Groovy 审计模板、理解脚本各参数的来源与含义并从源码与测试用例层面洞悉该功能的底层实现原理。什么是 Groovy 审计在 CAS 中每次登录、登出、票据颁发等关键动作都会产生一个可审计的事件上下文AuditActionContext审计记录管理器AuditTrailManager负责把这些上下文转换成可持久化、可检索的记录。默认情况下CAS 使用内置的文本/JSON 格式化器输出固定格式的日志而Groovy 审计则把格式化这一步完全交给用户自定义的 Groovy 脚本脚本可以访问审计引擎收集到的全部上下文参数输出格式完全由脚本决定可以是纯文本、JSON、CSV 或任何你想要的表示形式最终生成的审计记录会被交给日志框架通常以INFO级别记录Slf4jLoggingAuditTrailManager 中的record方法直接调用LOG.info(toString(auditActionContext))。从源码结构看GroovyAuditTrailManager 继承自Slf4jLoggingAuditTrailManagerorg.apereo.inspektr.audit.support包自 7.0.0 版本起提供因此它本质上是日志型审计管理器 Groovy 模板渲染器的组合。前置条件启用 Apache Groovy 脚本支持在使用 Groovy 审计之前需要确保 CAS 运行环境已集成 Apache Groovy 脚本引擎。CAS 对 Groovy 脚本能力的整体说明包括如何引入依赖、脚本引擎如何被复用见 Apache-Groovy-Scripting 指南。模板渲染在运行时通过ExecutableCompiledScriptFactory完成见下文源码分析因此该模块是 Groovy 审计的硬性依赖。配置 Groovy 审计Groovy 审计的配置前缀为cas.audit.groovy配置模型定义在 AuditGroovyProperties 中标注了RequiresModule(name cas-server-core-audit)即该功能随cas-server-core-audit模块提供。该配置仅有一个嵌套属性template类型为SpringResourceProperties用于指向构造审计记录的 Groovy 模板文件。一个典型的application.yml配置如下cas: audit: groovy: template: location: file:/etc/cas/config/audit/GroovyAudit.groovytemplate.location支持 Spring 资源定位语法file:/path/to/GroovyAudit.groovy引用文件系统路径classpath:/GroovyAudit.groovy引用 classpath 下的资源测试用例即采用此方式见下文。在 CasCoreAuditAutoConfiguration 中配置装配逻辑如下通过BeanCondition.on(cas.audit.groovy.template.location).exists()判断是否定义了该属性——只要配置了template.locationGroovy 审计管理器就会被注册到审计执行计划中注册的 Bean 名为casGroovyAuditTrailExecutionPlanConfigurer带RefreshScope意味着模板位置变更可以通过配置刷新热生效被ConditionalOnMissingGraalVMNativeImage修饰说明该特性在当前版本的 GraalVM Native Image 编译场景下不受支持这是运行时环境的适用前提。注意Groovy 审计管理器被注册后会参与审计执行计划与cas.audit.slf4j等日志型审计可以共存。若只想保留 Groovy 审计可像测试用例那样将cas.audit.slf4j.enabledfalse关闭其他输出见 GroovyAuditTrailManagerTests。脚本可用的参数当每次审计记录被触发时CAS 会把以下参数绑定到 Groovy 模板的上下文中参数说明applicationContext代表 Spring 应用上下文的对象ApplicationContext可在脚本中按需获取任意 Bean。logger负责输出日志消息的对象例如logger.info(...)、logger.debug(...)。clientIpAddress客户端 IP 地址。serverIpAddress服务端 IP 地址。what被操作/被访问的资源例如目标服务 URL 或票据 ID。who执行操作的主体通常是认证后的 principal。when操作发生的时间。action执行的动作例如TICKET_GRANTING_TICKET_CREATED、AUTHENTICATION_SUCCESS。userAgent客户端浏览器/用户代理字符串。application应用代码/来源标识。geoLocation客户端地理位置信息若配置了地理位置服务。HTTP 请求头收集到的所有请求头按各自名称传入例如customHttpRequestHeader。Extra Info审计引擎从各组件收集的任意键/值附加信息。这些参数的来源可以从 AbstractStringAuditTrailManager.getMappedAuditActionContext 中逐一印证who、what、action、application、when、clientIpAddress、serverIpAddress、userAgent、headers、geoLocation、deviceFingerprint、tenant等均来自AuditActionContext及其携带的ClientInfo对象HTTP 请求头与附加信息则来自ClientInfo.getHeaders()与getExtraInfo()。编写 Groovy 审计模板最小示例原文档给出的示例脚本如下${logger.info(Hello, World)} who: ${who}, what: ${what}, when: ${when}, ip: ${clientIpAddress}, trace: ${customHttpRequestHeader}该模板展示了两个要点${...}为模板占位符语法在渲染时会被替换为对应参数的值模板可以直接调用logger输出额外的日志也可以引用任意 HTTP 请求头此处以名为customHttpRequestHeader的请求头为例。从测试资源看更丰富的用法仓库测试资源中提供了一个更完整的真实模板 GroovyAudit.groovy演示了在脚本中获取 Spring Bean 的姿势${logger.info(Groovy audit manager running...)} ${ def bean applicationContext.getBean(org.apereo.cas.audit.AuditTrailExecutionPlan.BEAN_NAME) logger.debug(bean.class.name) } who: ${who}, what: ${what}, when: ${when}, ip: ${clientIpAddress}从中可以学到的进阶技巧通过applicationContext.getBean(...)在模板中按需访问 CAS 内部 Bean例如审计执行计划AuditTrailExecutionPlan从而实现动态、可编程的审计记录生成多行${...}代码块可以包含任意 Groovy 逻辑声明变量、调用方法、循环等模板本质上是一段可执行的 Groovy 脚本片段模板中声明的变量、打印的输出与占位符混排最终字符串即为审计记录内容。由于渲染是先把整个模板渲染为字符串、再交给日志框架输出你完全可以在此字符串中拼装 JSON${logger.debug(Building JSON audit record)} {who: ${who}, what: ${what}, when: ${when}, clientIp: ${clientIpAddress}, action: ${action}}底层实现原理GroovyAuditTrailManager.toString 揭示了完整的渲染流水线收集上下文把ClientInfo的 HTTP 请求头getHeaders()与附加信息getExtraInfo()合并进一个HashMap叠加审计字段通过getMappedAuditActionContext(...)注入who/what/action/application/when/clientIpAddress/serverIpAddress/userAgent/headers/geoLocation等标准字段注入基础设施放入applicationContextSpring 应用上下文与logger即Slf4jLoggingAuditTrailManager的LOG实例渲染模板调用ExecutableCompiledScriptFactory.createTemplate(groovyTemplate, map)以模板文件 上下文 Map 渲染出最终字符串输出日志由于继承自Slf4jLoggingAuditTrailManager渲染结果通过LOG.info(...)输出到 CAS 的审计日志。因此你在脚本中见到的每一个${...}占位符本质上都是从这个上下文Map中按名字取值而applicationContext与logger两个对象是框架额外注入的特权参数这正是模板既能查 Spring Bean、又能直接打日志的原因。用测试用例验证行为GroovyAuditTrailManagerTests 是该功能的单元级验证展示了完整的使用姿势测试配置了cas.audit.groovy.template.locationclasspath:/GroovyAudit.groovy并关闭cas.audit.slf4j.enabled测试构造了一个AuditActionContext携带 principalcasuser、动作TEST、资源TEST、应用码CAS、时间以及ClientInfoIP 为1.2.3.4附加信息Hello - World请求头H1 - V1调用auditTrailManager.record(ctx)后模板会被渲染并通过INFO日志输出日志中应能看到who: casuser、what: TEST、when: ...、ip: 1.2.3.4等字段。这个测试同时证明ClientInfo的 headers 与 extra info 会被合入模板上下文因此任意 HTTP 请求头按名引用与Extra Info 按名引用在实现上是成立的。实践建议与注意事项模板位置生产环境建议使用file:指向外部文件系统便于运维在不重新打包 WAR 的情况下修改审计格式改动后利用RefreshScope通过配置刷新生效。日志级别审计记录以INFO输出而模板内的logger.debug(...)只会在 DEBUG 级别可见合理利用级别区分审计正文与调试辅助信息。字段可裁剪AbstractStringAuditTrailManager支持auditableFieldsAuditableFields枚举集合裁剪注入的字段若不需要地理位置等字段可通过相应配置减少上下文体积空集合表示输出全部字段。GraalVM 限制Groovy 审计管理器被ConditionalOnMissingGraalVMNativeImage修饰在 Native Image 运行模式下不会被装配部署时需留意该前提。故障排查脚本中的 Groovy 语法错误会在渲染阶段抛出并被FunctionUtils.doUnchecked包装为运行时异常可关注 CAS 审计相关日志定位模板问题修改模板后建议先用少量请求验证输出格式再全量放开。赞分享后端认证鉴权单点登录【免费下载链接】casApereo CAS - Identity Single Sign On for all earthlings and beyond.项目地址https://gitcode.com/gh_mirrors/ca/cas点击查看免费下载相关推荐Apereo CAS 文件型审计File-based Audits实践cas_audit.log 输出配置与源码实现解析Apereo CAS 文件型审计File based Audits实践cas_audit.log 输出配置与源码实现解析 导读 Apereo CAS 的审后端认证鉴权单点登录Apache Groovy数据库操作Groovy SQL模块完全解析Apache Groovy数据库操作Groovy SQL模块完全解析 Apache Groovy SQL模块是JVM平台上最强大的数据库操作工具之一为开发者编程语言编译器语言运行时Spring Framework中的Groovy Markup模板引擎解析Spring Framework中的Groovy Markup模板引擎解析 什么是Groovy Markup模板引擎 Groovy Markup Templat后端Web框架依赖注入上一篇突破硬件限制OpenCore Legacy Patcher企业级部署指南下一篇终极指南如何使用Universal Android Debloater彻底移除Simple Mobile Tools应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考