企业官网建设流程全解析

• 后端
• 认证鉴权
• 单点登录

本文介绍如何在 Apereo CAS 中启用基于 MongoDB 的用户名密码认证：账号数据存储在 MongoDB 集合中，用户提交的用户名/密码将与该集合中的文档进行比对。读完本文，你将掌握cas-server-support-mongo模块的依赖引入方式、cas.authn.mongo.*全套配置参数的含义与默认值、MongoDB 中账户文档的标准结构，以及认证处理器在源码层面的完整执行流程，可直接在 WAR overlay 中落地配置。

认证场景与文档结构

Apereo CAS 的 MongoDb 认证模块用于验证用户凭据并依据 MongoDB 实例中的数据完成认证。账户数据以 JSON 文档形式存储在指定数据库的集合（collection）中，每个文档代表一个账户，其核心字段如下（此结构即原文档给出的标准示例）：

{ "username": "casuser", "password": "34598dfkjdjk3487jfdkh874395", "first_name": "john", "last_name": "smith" }

其中username与password字段的名称并非写死，而是可以通过配置项cas.authn.mongo.username-attribute与cas.authn.mongo.password-attribute灵活指定（默认值恰好就是username与password）。除这两个字段外的其余字段，会被收集并作为认证成功后的 Principal 属性释放给后续流程（如属性解析、服务授权等），例如上面的first_name、last_name。

引入支持模块

该功能由cas-server-support-mongo模块提供。在原文档中，通过 CAS 标准的casmodule模板引入该依赖，在 WAR overlay 的build.gradle中实际写法为：

implementation "org.apereo.cas:cas-server-support-mongo:${project.casVersion}"

引入后，CAS 会通过 CasMongoAuthenticationAutoConfiguration 自动装配 MongoDb 认证相关的三个 Bean：

• mongoPrincipalFactory：用于创建认证后的 Principal；
• mongoAuthenticationHandler：核心认证处理器，即MongoDbAuthenticationHandler；
• mongoAuthenticationEventExecutionPlanConfigurer：将上述处理器与默认PrincipalResolver注册到认证执行计划中。

值得注意的是，该自动配置带有条件开关（@ConditionalOnFeatureEnabled(feature = Authentication, module = "mongo")），并且只有满足cas.authn.mongo.client-uri或cas.authn.mongo.host存在、且cas.authn.mongo.collection已配置时，处理器才会真正被实例化（见 CasMongoAuthenticationAutoConfiguration.java），否则以代理 Bean 占位，不会启动不必要的连接。

配置参数详解

全部配置项以cas.authn.mongo为前缀，对应配置模型类 MongoDbAuthenticationProperties。下面按"连接参数、集合与字段映射、认证行为"三个层次逐项说明。

1. 连接参数（继承自 BaseMongoDbProperties）

这些参数定义如何连接 MongoDB 实例，对应 BaseMongoDbProperties：

从源码看，连接对象由 MongoDbConnectionFactory 构建：自动配置会传入CasSSLContext提供的SSLContext，当ssl-enabled=true时用于建立 TLS 连接，同时工厂内部注册了大量 Spring Data MongoDB 类型转换器（Converter），保证认证流程中的数据类型正确转换。

2. 集合与字段映射（继承自 SingleCollectionMongoDbProperties）

这两个配置项位于 SingleCollectionMongoDbProperties：

3. 认证行为参数（MongoDbAuthenticationProperties 自身）

4. 密码编码器（password-encoder）

认证必然涉及密码比对，cas.authn.mongo.password-encoder.type支持以下取值（详见 PasswordEncoderProperties 的注释）：

• NONE：明文比对（默认）；
• DEFAULT：CAS 默认编码器，基于character-encoding与encoding-algorithm做消息摘要；
• BCRYPT/SCRYPT/PBKDF2/STANDARD：Spring Security 系列编码器；
• SSHA：LDAP SHA/SSHA（base-64 编码并带{SHA}或{SSHA}前缀）；
• GLIBC_CRYPT：基于 glibc crypt 算法；
• 自定义实现类全限定名：实现 Spring SecurityPasswordEncoder接口；
• file:///path/to/script.groovy：指向处理密码编码的 Groovy 脚本。

编码器由PasswordEncoderUtils在自动配置中实例化并注入处理器（见 CasMongoAuthenticationAutoConfiguration.java）。若数据库中密码以哈希形式存储（如 BCrypt），必须将type设置为对应算法，否则认证将因明文比对失败而拒绝登录。

认证流程：源码级原理

认证的核心逻辑位于 MongoDbAuthenticationHandler，它继承自AbstractUsernamePasswordAuthenticationHandler。整体流程如下：

1. 通过mongoTemplate.getCollection(collection)获取配置指定的集合；
2. 以Filters.eq(usernameAttribute, username)构造精确匹配查询，按提交的用户名查找账户文档；
3. 查无此人：抛出AccountNotFoundException（"Unable to locate user account"）；
4. 文档中不存在密码字段：抛出FailedLoginException（"No password attribute found ..."）；
5. 取出文档中的密码值，交给PasswordEncoder.matches()与用户提交的密码比对，不一致则抛出FailedLoginException；
6. 比对通过后，将文档中除username-attribute与password-attribute之外的所有字段收集为属性集合（键值会被包装成列表结构），由PrincipalFactory构建 Principal；
7. 调用createHandlerResult生成认证成功结果，交还认证执行计划。

值得说明的是属性收集细节：从 MongoDbAuthenticationHandler.java 的实现看，处理器会收集文档中除用户名、密码两个字段外的全部字段作为 Principal 属性；测试中也印证了这一点——插入文档时写入loc与state两个附加字段，认证成功后断言attributes.containsKey("loc")与attributes.containsKey("state")成立。因此原文档示例中的first_name、last_name等自定义字段在认证成功后即可自动进入认证档案，无需额外属性解析配置。

认证通过后，处理器通过mongoAuthenticationEventExecutionPlanConfigurer与默认PrincipalResolver绑定注册，意味着认证产生的 Principal 会交给解析器做进一步的属性充实（如结合 Person Directory 目录源），再进入后续的授权与服务流程。

测试用例验证

仓库提供了完整的单元测试 MongoDbAuthenticationHandlerTests，测试前会真实连接localhost:27017（@EnabledIfListeningOnPort(port = 27017)保证仅在端口可用时执行），并向cas库的users集合插入两类文档：带密码的u1/p1（含loc、state属性）和不带密码字段的userPlain。四个用例分别验证：

测试中的配置即实际配置的最小范例（MongoDbAuthenticationHandlerTests.java）：

cas.authn.mongo.client-uri=mongodb://root:secret@localhost:27017/admin cas.authn.mongo.collection=users cas.authn.mongo.database-name=cas cas.authn.mongo.attributes=loc,state cas.authn.mongo.username-attribute=username cas.authn.mongo.password-attribute=password

生产配置建议与注意事项

最小可用配置示例

在application.properties中按如下方式配置（也可将client-uri拆分为host/port/user-id/password/database-name单项）：

# 依赖：cas-server-support-mongo cas.authn.mongo.client-uri=mongodb://casusr:secret@mongo.example.org:27017/cas cas.authn.mongo.collection=users cas.authn.mongo.username-attribute=username cas.authn.mongo.password-attribute=password # 若密码以 BCrypt 存储： cas.authn.mongo.password-encoder.type=BCRYPT # 可选：认证前对用户名做大小写转换/正则提取 cas.authn.mongo.principal-transformation.pattern=(.+)@example\.org

数据准备

使用mongosh向cas库的users集合插入账户文档：

use cas db.users.insertOne({ "username": "casuser", "password": "$2a$10$...", // BCrypt 哈希 "first_name": "john", "last_name": "smith", "department": "engineering" })

常见问题

• client-uri与单项配置的关系：只要client-uri非空，它即"接管"所有连接设置，其余 host/port 等项失效；排查连接问题时先确认 URI 是否正确、URI 中是否已携带认证库。
• 密码比对失败：优先检查password-encoder.type是否与库中密码的编码方式一致；NONE仅适用于明文存储场景。
• 属性未出现在认证档案中：确认属性字段与username-attribute、password-attribute不重名——这两个字段会被排除在 Principal 属性之外。
• 处理器未生效：mongoAuthenticationHandler的创建同时要求"连接参数（client-uri 或 host）存在"与"collection 已配置"两个条件，缺一不可；若日志中未见 Mongo 连接，先检查这两个前缀是否完整。

小结

MongoDb 认证是 Apereo CAS 中实现"账号库即 MongoDB"场景的最直接方案：只需引入cas-server-support-mongo依赖、配置cas.authn.mongo.*连接与字段映射、保证集合中的账户文档结构正确，即可完成用户名密码认证，并自动将文档中其余字段作为 Principal 属性用于下游流程。其认证处理器的实现路径清晰（精确查询 → 密码校验 → 属性收集 → 构建 Principal），配合仓库内的自动配置类与集成测试，可以很方便地在本地复现、调试并投入生产使用。

• 后端
• 认证鉴权
• 单点登录