解决 MongoDB 中常见的 SCRAM 身份验证错误

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

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

理解 MongoDB 中的 SCRAM

SCRAM 是 MongoDB 基于密码的挑战响应身份验证机制。MongoDB 长期以来一直支持 SCRAM-SHA-1，现代部署通常在服务器和客户端都支持时使用 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. 缺少或错误的角色

一个常见的混淆来源是成功连接，但发现用户无法执行所需的操作（例如，无法读取数据，无法写入）。这不是身份验证失败，而是授权失败，通常对最终用户来说表现相似。

授权故障排除：

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

如果用户尝试从 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-SHA-256 的 URI 可能会破坏旧的驱动程序或在该机制可用之前创建凭据的用户。从另一个环境复制的部署文件也可能包含与此集群不匹配的设置。

从最简单的有效连接字符串开始，然后仅在知道为什么需要时才添加选项。如果当前的 mongosh 会话有效但应用程序失败，请在更改服务器端用户之前比较驱动程序版本和 URI 选项。

我首先使用的实用调试路径

当遇到 SCRAM 错误时，请克制住同时更改三件事的冲动。从与应用程序相同网络运行的最小登录测试开始。如果应用程序在 Kubernetes 中运行，请 exec 进入一个临时调试 pod 或应用程序 pod 本身。如果它在 EC2 实例上运行，请从该实例进行测试，而不是从您的笔记本电脑。

mongosh "mongodb://[email protected]:27017/myappdb?authSource=admin" --password

如果因此出现网络错误，则密码可能还不相关。检查 DNS、防火墙规则、服务名称、端口映射、安全组和 net.bindIp。如果它到达服务器并失败并显示 Authentication failed，则转向用户位置和凭据。

接下来我要检查的是用户实际存在的位置。这可以捕获数量惊人的事件：

use admin
db.getUser("app_user")

use myappdb
db.getUser("app_user")

在 admin 中创建的用户必须使用 authSource=admin 进行身份验证。在 myappdb 中创建的用户必须使用 authSource=myappdb 进行身份验证。URI 中的数据库路径（例如 /myappdb）是客户端想要使用的默认数据库。它不自动是存储登录凭据的数据库。

之后，将身份验证与授权分开。成功登录仅证明用户名和密码被接受。它并不证明用户可以读取、写入、创建索引或运行管理命令。首先运行一个无害的检查：

db.runCommand({ connectionStatus: 1 })

然后尝试服务所需的确切操作：

use myappdb
db.orders.findOne()

如果第二个命令因权限错误而失败，请不要轮换密码。授予应用程序所需的最小角色。报告服务通常需要 read，普通应用程序通常需要对一个数据库具有 readWrite 权限，而迁移工具可能需要更广泛的临时权限。避免仅仅为了让错误消失而授予 root 或集群范围的角色。

use myappdb
db.grantRolesToUser("app_user", [
  { role: "readWrite", db: "myappdb" }
])

还要检查秘密处理的繁琐部分。包含 @、/、?、# 或 : 的密码如果未进行百分比编码，可能会破坏 MongoDB URI。从文件复制的环境变量可能包含尾随换行符。Kubernetes Secrets 可能会更新，而旧 pod 仍使用旧值运行。在这些情况下，MongoDB 配置没有问题；应用程序只是没有发送您认为它正在发送的密码。

驱动程序行为也很重要。大多数当前的 MongoDB 驱动程序会自动协商 SCRAM。如果您显式强制使用 authMechanism=SCRAM-SHA-256，请确保驱动程序和存储的用户凭据都支持它。在升级期间，使用 mongosh 和实际的应用程序驱动程序进行测试。如果 shell 有效但应用程序失败，请在更改服务器端用户之前比较驱动程序版本和 URI 选项。

托管的 MongoDB 增加了一个陷阱：提供商网络访问规则。例如，在 MongoDB Atlas 中，有效的数据库用户仍然无法从项目网络设置不允许的 IP 地址连接。从应用程序日志来看，这看起来像是一个连接或身份验证问题，但修复方法在提供商的访问列表或私有网络设置中。

最安全的故障排除节奏是：证明网络可达性，证明用户存在于 authSource 中，证明密码在 shell 中有效，证明角色允许该操作，然后比较应用程序驱动程序的最终连接字符串。这个顺序可以防止您将一行 URI 修复变成完整的凭据轮换。

阅读错误消息而不盲目信任它

MongoDB 客户端错误很有用，但它们并不总是以您需要的级别表述。Authentication failed 足够具体，可以告诉您服务器拒绝了凭据，但通常不足以告诉您是用户名错误、密码错误、authSource 错误还是机制协商失败。MongoServerSelectionError 可能指向应用程序日志中的身份验证，即使驱动程序从未找到合适的服务器。

来自应用程序的良好日志行应包括经过清理的主机、数据库名称、身份验证源、副本集名称（如果使用）以及驱动程序超时。它不应包含密码。如果您的日志只显示“Mongo 连接失败”，请在下次事件发生之前改进它。authSource=admin 和 authSource=app 之间的差异太重要了，不能隐藏。

对于副本集，还要确认 MongoDB 通告的主机名可以从客户端访问。一个常见的本地到生产意外是种子主机可以访问，但副本集返回客户端无法解析的内部名称。然后驱动程序会失败服务器选择，团队会追逐凭据，因为第一个手动 shell 命令针对一个节点有效。使用 rs.status() 并比较成员名称与应用程序网络可以解析的名称。

rs.status().members.map(m => m.name)

如果这些名称是私有 DNS 名称，则应用程序必须在该私有网络内运行，或者使用能够正确解析它们的连接方法。除非您了解故障转移后果，否则不要通过直接连接到辅助节点或单个节点来掩盖这一点。

事件期间的安全修复

如果您需要快速恢复服务，请选择不会比必要更广泛地扩大访问权限的修复方法。使用相同角色重新创建应用程序用户可能比编辑几个不相关的设置更安全。如果您怀疑秘密漂移，轮换密码是合理的，但要与应用程序部署协调，以便旧 pod 不会继续使用过期的凭据重试并填满日志。

避免禁用身份验证作为故障排除快捷方式。它会改变整个部署的安全态势，并可能隐藏原始原因。如果您需要紧急访问路径，请仅在您处于初始设置状态且 MongoDB 允许时，通过 localhost 异常创建临时管理员用户，或者使用托管提供商的文档化恢复过程。在已建立的部署中，使用经过审计的管理员访问权限。

修复后，用简单的语言写下确切原因：“用户存在于 admin，应用程序使用了 authSource=orders”比“Mongo 身份验证问题”要好得多。该注释可以防止在下次环境重建时再次出现相同的停机。

SCRAM 身份验证失败检查清单

进行故障排除时，请按顺序执行以下步骤：

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

通过有条不紊地检查这些配置点，大多数 MongoDB 中的 SCRAM 身份验证错误都可以快速隔离和解决。