Apereo CAS 认证事件 MongoDB 持久化指南：配置 `cas-server-support-events-mongo` 与事件仓库实现解析

后端认证鉴权单点登录【免费下载链接】casApereo CAS - Identity Single Sign On for all earthlings and beyond.项目地址https://gitcode.com/gh_mirrors/ca/cas点击查看免费下载Apereo CAS 将认证过程中产生的各类事件登录成功、登录失败、票据创建等封装为统一的事件模型并交由事件仓库CasEventRepository持久化。当事件仓库后端选用 MongoDB 时认证事件会被写入 MongoDB 的指定集合中供审计、监控、事件报表与风险分析使用。读完本文你将掌握如何通过cas-server-support-events-mongo模块启用该能力、完整配置 MongoDB 连接与集合参数并理解事件从产生、落库到被events管理端点查询的底层实现链路。一、模块概述与启用方式MongoDb 认证事件持久化由独立模块 cas-server-support-events-mongo 提供其核心作用正如官方文档所述将认证事件存储到 MongoDB NoSQL 数据库中Stores authentication events into a MongoDb NoSQL database。启用方式是在 CAS 构建配置Gradle 依赖管理中加入该模块坐标信息如下依赖模块cas-server-support-events-mongo 组织org.apereo.cas加入依赖后CAS 会自动装配 CasMongoDbEventsAutoConfiguration 中定义的三个核心 BeanBean 名称类型职责persistenceExceptionTranslationPostProcessorPersistenceExceptionTranslationPostProcessor将 MongoDB 数据访问异常转换为 Spring 持久化异常体系mongoEventsTemplateMongoTemplate面向事件集合的 MongoDB 操作模板负责建集合与读写casEventRepositoryCasEventRepository事件仓库实现MongoDbCasEventRepository供 CAS 全局事件发布与消费使用该自动配置类同时具备两个重要的装配前提通过ConditionalOnFeatureEnabled(feature CasFeatureModule.FeatureCatalog.Events, module mongo)限定只有 CAS 的Events 功能特性与mongo 模块特性均被启用时才生效。该特性开关通常由cas.feature-flags相关配置或模块自动推导控制。mongoEventsTemplate与mongoEventRepositoryFilter均标注ConditionalOnMissingBean意味着开发者可以覆盖这些 Bean自定义连接模板或事件过滤策略。casEventRepository通过Qualifier(mongoEventsTemplate)注入 MongoDB 模板通过Qualifier(mongoEventRepositoryFilter)注入事件过滤器。1.1 从源码看事件入库链路在 MongoDbCasEventRepository 中事件写入与查询全部基于 Spring Data MongoDB 的MongoOperations写入saveInternal(CasEvent event)调用mongoTemplate.save(event.assignIdIfNecessary(), collectionName)先为事件分配 ID若未设置则取System.currentTimeMillis()见 CasEvent.assignIdIfNecessary再写入指定集合。清空removeAll()使用mongoTemplate.remove(new Query(), CasEvent.class, collectionName)删除集合内全部事件。读取load()使用mongoTemplate.stream(...)以流式方式读取全部事件load(ZonedDateTime)则在查询条件中追加creationTime dateTime.toInstant()的时间过滤。二、配置参数详解cas.events.mongo.*模块的全部配置项统一挂在cas.events.mongo前缀之下对应的配置模型是 MongoDbEventsProperties它继承自SingleCollectionMongoDbProperties与BaseMongoDbProperties。注意该属性类上的RequiresModule(name cas-server-support-events-mongo)注解未引入对应模块时这些配置不会生效。2.1 集合相关配置配置项默认值说明cas.events.mongo.collectionMongoDbCasEventRepositoryMongoDB 中存放认证事件的集合名称。构造函数中通过setCollection(MongoDbCasEventRepository)预置可覆盖cas.events.mongo.drop-collectionfalse启动时是否先删除drop再重新创建集合。测试场景或需要清空历史数据时设为true集合的创建发生在 CasMongoDbEventsAutoConfiguration#mongoEventsTemplateMongoDbConnectionFactory.createCollection(mongoTemplate, mongo.getCollection(), mongo.isDropCollection())会在应用启动装配模板时按需创建集合。2.2 连接相关配置以下参数定义在 BaseMongoDbProperties 中是 MongoDB 连接的基础设置配置项默认值说明cas.events.mongo.client-uri空MongoDB 连接 URI形如mongodb://user:pswds135522.somewhere.com:35522/db。一旦指定将接管其他连接设置优先级最高cas.events.mongo.hostlocalhostMongoDB 主机地址。多个地址用逗号分隔若每个主机都自带端口则端口以此为准cas.events.mongo.port27017MongoDB 端口cas.events.mongo.user-id空MongoDB 认证用户名cas.events.mongo.password空MongoDB 认证密码cas.events.mongo.database-name空MongoDB 数据库实例名事件写入的目标数据库cas.events.mongo.authentication-database-name空用于认证的数据库名称cas.events.mongo.timeoutPT5S连接超时ISO-8601 时长格式如PT5S表示 5 秒cas.events.mongo.write-concernACKNOWLEDGED写关注级别描述 MongoDB 对写操作要求确认的程度cas.events.mongo.read-concernAVAILABLE读关注级别可选LOCAL、MAJORITY、LINEARIZABLE、SNAPSHOT、AVAILABLEcas.events.mongo.read-preferencePRIMARY读偏好可选PRIMARY、SECONDARY、SECONDARY_PREFERRED、PRIMARY_PREFERRED、NEARESTcas.events.mongo.retry-writesfalse写操作因网络错误失败时是否自动重试cas.events.mongo.ssl-enabledfalse连接是否启用 SSLcas.events.mongo.replica-set空副本集名称。副本集提供冗余与高可用是生产部署的基础此外连接池相关参数由嵌套属性cas.events.mongo.pool.*提供MongoDbConnectionPoolProperties用于控制连接池大小、等待时间等。2.3 完整配置示例YAMLcas: events: mongo: client-uri: mongodb://cas:secretmongodb.example.org:27017/cas-events # 或使用分散参数 # host: localhost # port: 27017 # user-id: cas # password: secret # authentication-database-name: admin database-name: events collection: MongoDbCasEventRepository drop-collection: false timeout: PT5S write-concern: ACKNOWLEDGED read-concern: AVAILABLE read-preference: PRIMARY retry-writes: false ssl-enabled: false以上配置与仓库测试用例 MongoDbCasEventRepositoryTests 中使用的参数一一对应可作为最小可运行配置的参考cas.events.mongo.user-idroot cas.events.mongo.passwordsecret cas.events.mongo.hostlocalhost cas.events.mongo.port27017 cas.events.mongo.authentication-database-nameadmin cas.events.mongo.database-nameevents cas.events.mongo.drop-collectiontrue测试类还标注了EnabledIfListeningOnPort(port 27017)即只有在本地27017端口存在 MongoDB 实例时才会执行这提示了该功能的运行前置条件必须有一个可连接的 MongoDB 实例。三、事件数据模型MongoDB 集合中的文档结构写入 MongoDB 的事件文档对应 CasEvent 实体位于api/cas-server-core-api-events模块其字段结构如下JSON 字段类型说明idlong事件唯一标识写入时若小于等于 0 则以System.currentTimeMillis()填充typeString事件类型如CasAuthenticationTransactionSuccessfulEvent、CasAuthenticationTransactionFailureEvent等非空principalIdString与该事件关联的用户主体 ID非空creationTimeInstant事件创建时间非空propertiesMapString, String事件扩展属性键值对单值最长 4000 字符properties映射中常见的语义字段通过常量定义timestamp事件时间戳毫秒eventId事件 IDclientip/serverip客户端 / 服务端 IPagent用户代理浏览器/设备信息tenant多租户场景下的租户标识geoLatitude、geoLongitude、geoAccuracy、geoTimestamp、geoAddress地理位置相关putGeoLocation统一写入deviceFingerprint设备指纹。这些扩展属性通过put(...)链式方法写入空值会被移除事件创建方如认证成功/失败监听器在发布事件前会填充 IP、Agent、地理位置等信息MongoDB 仓库会将这些字段原样保存在文档的properties内嵌对象中。3.1 查询字段与索引语义MongoDbCasEventRepository 在查询时使用以下三个顶层字段构造CriteriacreationTime时间范围过滤gte(dateTime.toInstant())type事件类型精确匹配principalId主体 ID 精确匹配。仓库提供了 8 种查询组合按类型、按主体、按时间及其任意组合全部返回Stream? extends CasEvent流式结果。若需要在大数据量下保证查询性能可以考虑在 MongoDB 中为creationTime、type、principalId建立合适的索引。值得注意的是基类 AbstractCasEventRepository 中带时间参数的查询默认采用内存过滤load().filter(...)而 MongoDB 实现则全部下推到数据库端执行见MongoDbCasEventRepository中对load(ZonedDateTime)、getEventsOfType(type, dateTime)等方法的覆写因此在大数据量场景下 MongoDB 后端的查询效率更高。四、保存流程从事件发布到落库CAS 的认证事件遵循发布-订阅模型。事件被发布后casEventRepository的save(...)方法被调用其流程定义在 AbstractCasEventRepository#save 中调用eventRepositoryFilter.shouldSaveEvent(event)判断该事件是否需要持久化默认过滤器为noOp()即全部保存见 CasMongoDbEventsAutoConfiguration#mongoEventRepositoryFilter通过则调用子类实现的saveInternal(event)即MongoDbCasEventRepository.saveInternal将事件保存进 MongoDB 集合保存成功后若配置了ApplicationEventPublisher还会额外发布一个 Spring Boot Actuator 的AuditApplicationEvent审计事件其属性中包含CasEventRepository.PARAM_SOURCE CAS从而与 CAS 的审计机制打通。五、通过 Actuator 端点查询与管理事件认证事件持久化到 MongoDB 后可通过 CAS 的 Actuator 管理端点events进行查询与管理该端点定义在 CasEventsReportEndpoint 中端点 ID 为events默认访问权限为Access.NONE需显式开放GET /actuator/events?limit1000以 JSON 数组形式返回事件列表按timestamp倒序排列默认最多 1000 条GET /actuator/events/aggregate以 NDJSON 流式返回聚合事件报表DELETE /actuator/events清空事件仓库对应MongoDbCasEventRepository.removeAll()POST /actuator/events导入单个事件请求体为CasEventJSON或上传 ZIP 压缩包包内为多个.json事件文件批量导入。通过该端点可以直观验证 MongoDB 后端是否正常工作写入几条认证事件后访问GET /actuator/events应能看到来自 MongoDB 集合的完整事件数据。六、快速验证与测试仓库自带的集成测试 MongoDbCasEventRepositoryTests 继承自AbstractCasEventRepositoryTests覆盖了事件保存、按类型/主体/时间查询、清空等全部仓库接口行为。若要在本地复现需要在localhost:27017启动 MongoDB 实例测试通过EnabledIfListeningOnPort(port 27017)检测端口准备测试库events及认证账号测试用例使用root/secret认证库admin运行该测试类观察CasMongoDbEventsAutoConfiguration的装配与增删查改流程。该测试同时验证了drop-collectiontrue的行为每次启动都会先 drop 集合再重建适用于开发调试生产环境建议保持false避免启动时误清历史事件数据。七、小结与使用建议模块先行使用前必须在构建中引入cas-server-support-events-mongo否则cas.events.mongo.*配置不会生效连接配置推荐直接使用client-uri完成连接其余参数作为精细化兜底database-name决定事件写入哪个库collection决定写入哪个集合默认MongoDbCasEventRepository生产建议保持drop-collection: false按type、principalId、creationTime的查询模式为集合建立索引结合eventsActuator 端点做日常巡检生态定位该模块是 CAS 事件仓库的 MongoDB 后端实现之一与 JDBC、Redis、DynamoDb、Kafka 等后端实现并列见 api/cas-server-core-api-configuration-model/src/main/java/org/apereo/cas/configuration/model/core/events 下的事件配置模型选择 MongoDB 可获得 NoSQL 的灵活文档结构与流式读取能力适合与现有 MongoDB 基础设施复用的部署场景。赞分享后端认证鉴权单点登录【免费下载链接】casApereo CAS - Identity Single Sign On for all earthlings and beyond.项目地址https://gitcode.com/gh_mirrors/ca/cas点击查看免费下载相关推荐Apereo CAS 认证事件 Kafka 发布指南使用 cas-server-support-events-kafka 将认证事件写入 Kafka TopicApereo CAS 认证事件 Kafka 发布指南使用 cas server support events kafka 将认证事件写入 Kafka Topi后端认证鉴权单点登录gh_mirrors/cas/cas与GitLab集成代码仓库的SSO认证实现终极指南gh_mirrors/cas/cas与GitLab集成代码仓库的SSO认证实现终极指南 在当今企业级开发环境中 统一身份认证 已成为提升开发效率和保障代码安后端认证鉴权单点登录Apereo CAS集成Google Authenticator实现多因素认证指南Apereo CAS集成Google Authenticator实现多因素认证指南 概述 在当今网络安全环境中多因素认证 MFA 已成为保护敏感系统的必备措施后端认证鉴权单点登录上一篇EvoDiff高级技巧如何通过条件MSA生成新的蛋白质家族成员下一篇Udeler代码注释规范提升团队协作效率的文档实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考