MongoDB 中 SCRAM 认证常见错误故障排除

配置 MongoDB 的安全性对于保护敏感数据至关重要。现代 MongoDB 部署严重依赖 SCRAM（加盐挑战响应认证机制） 来进行安全的基于密码的认证。然而，实现和管理 SCRAM 有时可能会导致令人沮丧的连接错误和访问拒绝。

本指南旨在成为一个实用的故障排除手册，用于识别和解决在 MongoDB 中设置或使用 SCRAM 认证时遇到的大多数常见问题。通过了解与用户创建、角色分配和客户端配置相关的常见陷阱，您可以快速恢复安全的数据库访问。

理解 MongoDB 中的 SCRAM

SCRAM 是近期 MongoDB 版本（从 MongoDB 3.0+ 开始，并演变为当前的 SCRAM-SHA-256 标准）的默认认证机制。它提供强大的密码哈希功能，并防止密码以明文形式在网络上传输，这比旧方法有了重大的安全改进。

在故障排除时，请记住认证失败通常源于三个区域之一：服务器配置、用户定义或客户端连接语法。

常见错误类别 1：连接被拒绝或认证失败（客户端侧）

这是最常见的症状：客户端无法连接，当强制执行严格认证时，通常会显示类似 Authentication failed.（认证失败）或 Connection refused（连接被拒绝）的消息。

1. 指定了错误的认证机制

如果您的 MongoDB 部署要求 SCRAM，但客户端尝试使用旧的或不支持的机制（如 MONGODB-CR），连接将立即失败。

解决方案： 确保您的连接字符串或驱动程序配置明确指定 SCRAM。

对于支持现代驱动程序的客户端，连接字符串通常会指定认证机制 (authMechanism)。对于使用 SCRAM-SHA-256（推荐）的现代部署：

mongodb://user:password@host:27017/dbname?authSource=admin&authMechanism=SCRAM-SHA-256

提示： 如果您在仅配置为 SCRAM 的服务器上省略 authMechanism，驱动程序应该能够正确默认，但明确设置它消除了歧义。

2. 使用了错误的 `authSource`

在 MongoDB 中，authSource 参数指定定义用户帐户的数据库。如果您的用户存在于 admin 数据库中，但您连接时指定 authSource=myappdb，则服务器将找不到凭据。

示例场景： 用户 app_user 在 admin 数据库中创建。

错误的连接：

mongodb://app_user:password@localhost:27017/myappdb?authSource=myappdb

正确的连接：

mongodb://app_user:password@localhost:27017/myappdb?authSource=admin

3. 网络或绑定问题掩盖了认证失败

有时，连接问题看起来像是认证失败，但实际上是网络绑定问题。如果 mongod 实例仅绑定到 127.0.0.1（localhost），远程客户端将在尝试认证之前就收到连接被拒绝的响应。

操作： 验证 mongod.conf 中的 net.bindIp 是否允许来自客户端 IP 地址的连接（例如，0.0.0.0 表示所有接口，或指定 IP 地址）。

常见错误类别 2：用户创建和角色分配错误

认证失败通常根源于用户的创建方式或分配给用户的权限。

1. 用户创建时未设置密码（或格式不正确）

如果您尝试使用 mongosh 或 mongo shell 创建用户而未提供有效密码，创建过程可能会静默失败，或导致用户无法通过 SCRAM 成功认证。

创建最佳实践： 始终指定一个强密码，并确保在用户创建过程中使用推荐的 SCRAM 机制。

// 先以管理员用户身份连接
use admin

// 使用 SCRAM-SHA-256（推荐）创建用户
db.createUser(
  {
    user: "reader_role",
    pwd: passwordPrompt(), // 安全地提示输入密码
    roles: [ { role: "read", db: "mydatabase" } ]
  }
)

2. 缺少或不正确的角色

一个常见的混淆点是成功连接但发现用户无法执行所需操作（例如，无法读取数据，无法写入）。这不是认证失败，而是授权失败，但它经常以与最终用户相似的方式呈现。

故障排除授权：

验证角色分配： 在正确的数据库（authSource）中使用 show users 来确认用户存在并拥有预期的角色。
检查继承的角色： 如果使用自定义角色，请确保它们正确继承了必要的内置角色（如 read 或 readWrite）。
连接上下文： 请记住，角色仅在创建时指定的数据库（或用于集群级别角色的 admin DB）上有效。

如果用户尝试从 dbA 读取但仅拥有 dbB 上的角色，操作将失败。

3. 升级期间 SCRAM 版本不匹配

升级 MongoDB 时，旧用户可能仍使用旧的 MONGODB-CR 机制进行映射。如果服务器配置为仅接受 SCRAM-SHA-256，这些旧用户将无法登录。

解决方案： 升级服务器配置后，您必须显式地更新现有用户的认证方法。

使用 changePassword 命令，该命令强制使用当前的服务器默认设置重新哈希：

// 更新用户密码，隐含更新机制（如果需要）
db.changePassword(
  "old_user",
  "new_secure_password",
  { authenticationDatabase: "admin" }
)

常见错误类别 3：服务器配置问题

如果多个客户端连接失败，问题很可能出在 mongod 配置文件（mongod.conf）中。

1. 未启用认证

如果完全禁用了认证，不带凭据连接的客户端可能会成功，或者如果客户端仍尝试进行身份验证，可能会意外被阻止。反之，如果需要认证但配置不正确，连接就会失败。

确保 mongod.conf 中的安全部分设置正确：

security:
  authorization: enabled

2. 绑定到不正确的接口

如前所述，如果 net.bindIp 设置过于严格，外部客户端将无法访问认证服务。

mongod.conf 中的示例：

仅本地访问： bindIp: 127.0.0.1（远程连接失败）
推荐用于云/内部网络： bindIp: 0.0.0.0（允许从任何接口连接，但需要强防火墙规则）

3. 使用了不受支持的 SCRAM 版本

如果您显式设置了 setParameter: { authSchemaVersion: 1 }（旧版），您可能会阻止客户端使用 SCRAM-SHA-256，迫使依赖旧的、安全性较低的机制，而这些机制可能不再被现代驱动程序支持。

最佳实践： 对于现代 MongoDB 安装（4.0+），您应该目标是 authSchemaVersion: 4（SCRAM-SHA-256 的默认值）。除非为了向后兼容非常旧的客户端，否则避免显式设置模式版本。

SCRAM 认证失败摘要检查表

在故障排除时，请按此顺序进行：

服务器状态： mongod.conf 中是否启用了 security.authorization？
网络检查： 客户端是否可以访问服务器 IP 和端口（使用 netstat 或 telnet）？
客户端 URI： 是否指定了 authMechanism=SCRAM-SHA-256（如果需要）？
authSource： authSource 是否与创建用户的数据库匹配？
用户是否存在： 用户是否在指定的 authSource 数据库中存在？
密码/角色： 密码是否正确，用户是否拥有执行预期操作所需的最少角色？

通过有条理地检查这些配置点，大多数 MongoDB 中的 SCRAM 认证错误都可以被快速隔离并解决。