FerretDB v1.21 发布解读：实验性 SCRAM-SHA-1/SCRAM-SHA-256 认证机制实战

后端数据库文档数据库【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址https://gitcode.com/gh_mirrors/fe/FerretDB点击查看免费下载本文基于 FerretDB 官方 v1.21 版本发布说明深入讲解该版本引入的实验性SCRAM-SHA-1/SCRAM-SHA-256认证机制如何通过--test-enable-new-auth启用、如何用createUser创建用户并完成带认证的连接并结合当前仓库源码剖析 SCRAM 握手在saslStart/saslContinue中的实现细节。同时梳理该版本对upsert与 capped collection 清理逻辑的修复以及 v1.x 末期到 v2.0 的架构演进背景。读完本文你将掌握 FerretDB 认证模式的基本原理、启用方式与排查思路。版本背景为什么 v1.21 需要新的认证机制FerretDB 一直以 MongoDB 协议兼容为使命认证是其中至关重要的一环。在 v1.21 之前FerretDB 主要依赖外部数据库PostgreSQL/SQLite自身的账号体系来模拟 MongoDB 的用户认证这在很多场景下体验割裂用户管理命令支持有限、凭据无法由 FerretDB 独立管理。v1.21 是 1.x 系列的重要节点官方在该版本中加入了实验性的SCRAM-SHA-1/SCRAM-SHA-256认证机制。SCRAMSalted Challenge Response Authentication Mechanism是 RFC 5802/7677 定义的挑战-响应认证协议也是 MongoDB 原生驱动默认使用的认证方式。FerretDB 引入该机制后可以让驱动以与 MongoDB 一致的方式完成认证握手从而显著提升兼容性。需要说明的是该功能在 v1.21 中标记为实验性需要显式开启后续版本v1.24 及 v2.x在此基础上进一步演化最终成为默认认证路径。本文以 v1.21 发布说明为主线同时结合当前仓库中可验证的源码与测试进行佐证。启用实验性认证模式v1.21 中新认证模式默认关闭需要通过专用开关显式打开。官方文档见 version-v1.24 的 flags 文档明确给出了对应关系命令行 Flag环境变量默认值--test-enable-new-authFERRETDB_TEST_ENABLE_NEW_AUTHfalse启用方式很简单任选其一# 通过命令行 flag ferretdb --test-enable-new-authtrue # 通过环境变量 FERRETDB_TEST_ENABLE_NEW_AUTHtrue ferretdb注意事项该 flag 在 v1.21 时期属于测试用途的隐藏参数可能不会出现在--help输出中开启后FerretDB 将自行管理用户账号并解锁更多用户管理命令只有在此模式下才支持在连接串中使用createUser创建的用户凭据完成 SCRAM 认证。在 Docker Compose 部署场景中典型配置如下Postgres 后端services: postgres: image: postgres environment: - POSTGRES_USERusername - POSTGRES_PASSWORDpassword - POSTGRES_DBferretdb volumes: - ./data:/var/lib/postgresql/data ferretdb: image: ghcr.io/ferretdb/ferretdb:1 restart: on-failure ports: - 27017:27017 environment: - FERRETDB_POSTGRESQL_URLpostgres://username:passwordpostgres:5432/ferretdb - FERRETDB_TEST_ENABLE_NEW_AUTHtrue - FERRETDB_SETUP_USERNAMEuser - FERRETDB_SETUP_PASSWORDpass - FERRETDB_SETUP_DATABASEferretdb networks: default: name: ferretdb其中FERRETDB_SETUP_USERNAME/FERRETDB_SETUP_PASSWORD/FERRETDB_SETUP_DATABASE用于在首次启动时创建初始账号与初始数据库这一能力在 v1.22 的用户设置功能中被正式完善。启动后用docker compose up -d即可通过mongosh mongodb://user:passferretdb/ferretdb完成带认证的连接。创建用户并连接启用新认证模式后就可以使用标准的createUser命令创建用户。其命令入口在仓库 internal/handler/msg_createuser.go 中实现核心逻辑是解析文档、补充默认角色后调用documentdb.CreateUser将用户持久化到后端。// mongosh 中创建用户 use admin db.runCommand({ createUser: user, pwd: pass, roles: [{ role: clusterAdmin, db: admin }, { role: readWriteAnyDatabase, db: admin }], mechanisms: [SCRAM-SHA-256] // 可选默认机制为 SCRAM-SHA-256 })关于mechanisms参数从源码看msg_createuser.go 中会先移除客户端传入的mechanisms字段再交给底层存储处理实际生效的机制以存储层返回为准。仓库中的集成测试如 integration/auth/create_user_test.go覆盖了EmptyMechanism、BadAuthMechanism等用例验证了机制为空、机制非法等边界行为integration/auth/usersinfo_test.go 则验证了usersInfo返回的机制列表既有纯SCRAM-SHA-256的情况也有[SCRAM-SHA-1, SCRAM-SHA-256]的组合情况。创建完成后即可在连接串中直接使用该用户凭据连接mongosh mongodb://user:passlocalhost:27017/?authSourceadminauthMechanismSCRAM-SHA-256新认证模式同时支持以下用户管理命令dropUser/dropAllUsersFromDatabase删除用户updateUser修改用户密码与角色usersInfo查询用户信息与支持的认证机制。这些命令分别对应仓库 internal/handler/msg_dropuser.go、msg_dropallusersfromdatabase.go、msg_updateuser.go、msg_usersinfo.go 中的实现。SCRAM 认证握手源码级流程解析新认证模式的核心是一次标准的 SCRAM 挑战-响应握手客户端与服务器之间通过saslStart和saslContinue两个 MongoDB 命令完成。下面结合仓库源码说明四个阶段。阶段一saslStart开启对话入口在 internal/handler/msg_saslstart.go 的saslStart方法中从请求中读取mechanism若不为SCRAM-SHA-256则返回ErrMechanismUnavailable见 msg_saslstart.go。也就是说v1.21 实验模式下握手阶段实际以SCRAM-SHA-256为默认机制解析payload中的客户端首条消息client-first从中提取用户名通过documentdb_api_internal.ScramSha256GetSaltAndIterations向后端获取该用户的 salt 与迭代次数生成服务端首条消息server-first连同conversationId一并返回客户端。阶段二saslContinue验证客户端证明客户端收到 server-first 后计算客户端证明client proof再次通过saslContinue提交。入口在 internal/handler/msg_saslcontinue.go从连接上下文中取出之前保存的 SCRAM 会话Conv若无会话则报ErrProtocolErrorNo SASL session state found调用conv.ClientFinal解析客户端最终消息计算认证消息auth message调用documentdb_api_internal.AuthenticateWithScramSha256校验证明成功后返回服务端签名server signature作为 server-final完成双向认证。阶段三会话状态管理Conv结构体定义在 internal/util/scram/conv.go 中它完整保存 client-first、server-first、client-final、server-final 四类消息并用sync.RWMutex保证并发安全。值得注意的是会话不可重启——每个连接必须新建一个Conv实例且非当前对话的重复消息会被拒绝。连接级会话存放在conninfo中由saslContinue在结束时清理。阶段四SCRAM 消息解析消息解析在 internal/util/scram/message.go 的parseMessage中实现其安全校验值得关注客户端非cer长度不得小于 16 字节服务端 salts长度不得小于 12 字节且推荐使用 28 字节与 DocumentDB 创建的用户凭据保持一致否则会打印告警日志迭代次数i不得小于 4096防止弱迭代导致的口令爆破风险仅支持cbiws即n,,的 base64 编码即不支持 channel binding属性顺序需符合 RFC 5802 第 5.1 节的规定。scram包的整体定位在 internal/util/scram/scram.go 的包注释中有明确说明Package scram provides an implementation of SCRAM-SHA-256 subset即实现的是 SCRAM-SHA-256 子集。兼容性细节从 internal/handler/msg_hello.go 可以看到hello命令会返回saslSupportedMechs: [SCRAM-SHA-256]而 internal/handler/msg_getparameter.go 中authenticationMechanisms参数的返回值为[SCRAM-SHA-1, SCRAM-SHA-256]这正是 v1.21 发布说明所称支持两种机制的组合体现。本版本的缺陷修复upsert处理重构修复过滤字段被忽略的问题v1.21 对update与findAndModify命令中的upsert处理进行了重构修复了upsert: true时过滤字段query 字段被错误忽略、未拼接到新文档的问题。仓库中的集成测试可以佐证该修复覆盖的行为例如 integration/query/findandmodify_test.go 中的TestFindAndModifyCommandUpsert表驱动测试UpsertNoSuchDocumentNoIdInQuery: { command: bson.D{ {query, bson.D{{ $and, bson.A{ bson.D{{v, bson.D{{$gt, 0}}}}, bson.D{{v, bson.D{{$lt, 0}}}}, }, }}}, {update, bson.D{{$set, bson.D{{v, 43.13}}}}}, {upsert, true}, }, lastErrorObject: bson.D{ {n, int32(1)}, {updatedExisting, false}, }, },该用例验证了查询条件不存在任何匹配文档、且 query 中没有_id时的 upsert 行为。UpsertExpressionKeyquery 使用_id: {$exists: false}、UpsertDocumentKeyquery 使用嵌套文档_id等用例则验证了不同类型的查询键在 upsert 时被正确保留。update 命令侧的类似场景由 integration/update_field_test.go 覆盖其中通过find结果比对确认了 upsert 生成的_id及字段内容。capped collection 清理逻辑改进v1.21 同时改进了 capped collection固定大小集合的清理逻辑当集合只配置了size参数、未配置max选项时删除旧文档的逻辑现在能正确处理。此前该场景下文档删除行为存在偏差此次修复保证了按大小限制滚动淘汰旧文档的语义符合预期。注capped collection 在 FerretDB 中的支持状态可在 website/docs/migration/compatibility.md 的兼容性矩阵中查询如convertToCapped、cloneCollectionAsCapped尚未实现create支持等。展望v2.0 的架构变革v1.21 发布时官方明确表示1.x 的迭代目标——提供生产可用的 MongoDB 开源替代品、收集多场景反馈——已经阶段性达成而性能是房间里的大象。v2.0 作为架构级的分水岭将彻底改变底层架构以换取大幅的性能与兼容性提升当前仓库v2系列正是这一演进的结果。对于计划从 MongoDB 迁移或正在评估 FerretDB 的用户官方建议关注版本升级路径见 website/docs/migration/migrating-from-v1.md迁移前的兼容性预检见 website/docs/migration/premigration-testing.md。小结启用实验认证--test-enable-new-authtrue或FERRETDB_TEST_ENABLE_NEW_AUTHtrue创建用户使用createUser命令配合dropUser、updateUser、usersInfo等命令管理账号连接在连接串中直接携带用户名密码按 MongoDB 驱动习惯指定authMechanismSCRAM-SHA-256原理完整的 SCRAM 四阶段握手由saslStart/saslContinue驱动底层scram包负责消息解析与会话状态安全校验nonce 长度、salt 长度、迭代次数下限在 internal/util/scram/message.go 中严格把关。v1.21 是 FerretDB 认证体系走向成熟的起点从实验性 SCRAM 支持到 v1.22 的用户初始化设置、v1.24 的 SQLite 认证支持直至 v2 中认证成为默认能力——这条演进脉络清晰地展示了 FerretDB 如何一步步把认证这一 MongoDB 兼容性的关键拼图补齐。赞分享后端数据库文档数据库【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址https://gitcode.com/gh_mirrors/fe/FerretDB点击查看免费下载相关推荐EMQX Dashboard JSON API 的 SCRAM-SHA-256 挑战-响应认证接入指南EMQX Dashboard JSON API 的 SCRAM SHA 256 挑战 响应认证接入指南 本指南介绍 EMQX 5.x Dashboard JSO后端物联网消息队列通信EMQX Dashboard 登录启用 SCRAM-SHA-256 挑战-响应认证从密码登录到 SCRAM 的安全迁移指南EMQX Dashboard 登录启用 SCRAM SHA 256 挑战 响应认证从密码登录到 SCRAM 的安全迁移指南 EMQX Dashboard 的后端物联网消息队列通信MongoDB用户认证终极指南Robo 3T快速配置SCRAM-SHA-256加密MongoDB用户认证终极指南Robo 3T快速配置SCRAM SHA 256加密 在现代数据库管理中 MongoDB用户认证机制 是保障数据安全的重要屏障数据库客户端桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考