Docs 主页 → 开发应用程序 → MongoDB 驱动程序 → Ruby MongoDB 驱动程序
身份验证
MongoDB 支持多种 身份验证机制。
有关为每种身份验证机制配置 MongoDB 服务器的更多信息，请参阅 MongoDB 的在线文档。
有关用户和用于用户管理的 Ruby 驱动程序助手的更多信息，请参阅用户管理教程。
提供凭证
如果已启用身份验证，请在创建新客户端时提供凭据：
client = Mongo::Client.new([ '127.0.0.1:27017' ], user: 'test', password: '123', database: 'mydb' ) # If using a URI: client = Mongo::Client.new("mongodb://test:123@127.0.0.1:27017/mydb")
可以使用 Client#with方法在客户端实例上更改身份验证档案，以获得新客户端：
authenticated_client = client.with( user: 'another-user', password: '123' )
还可以一步更改客户端的数据库和档案：
authenticated_music_client = client.with( database: 'music', user:'test', password:'123' )
authSource
用户的身份验证源是存储该用户身份验证档案的数据库。
只要指定档案，就可以指定用户的身份验证源：
client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'mydb', user: 'test', password: '123', auth_source: 'admin' ) # If using a URI: client = Mongo::Client.new("mongodb://test:123@127.0.0.1:27017/mydb?authSource=admin")
如果未指定身份验证源，客户端将采用默认值。 默认身份验证源取决于用于连接的身份验证机制。
对于MONGODB-CR 、 SCRAM-SHA-1和SCRAM-SHA-256身份验证机制，默认身份验证源是客户端连接到的数据库；如果未指定数据库，则admin数据库是默认数据库，因此也是默认身份验证源。 对于PLAIN机制 (LDAP)，默认身份验证源是客户端要连接的数据库；如果未指定数据库，则使用$external数据库作为身份验证源。 对于AWS 、 GSSAPI和MONGODB_X509机制，身份验证源始终为$external 。
使用 SRV URI 构建客户端时，驱动程序将在 TXT DNS 记录中查找与 SRV 记录相对应的 URI 选项。 因此，举例来说，MongoDB Atlas 通常使用admin数据库作为其身份验证源，但 SRV URI 中并未指定这一点，因为该数据库是作为 TXT 记录上的 URI 选项给出的。
请注意，使用 SRV URI 时，SRV 查询和 TXT 查询是分开执行的。 在 DNS 解析并非 100% 可靠的系统上，查找 TXT 记录失败可能会导致身份验证错误，因为驱动程序最终可能会使用不正确的身份验证源。 如果无法保证可靠的 DNS 解析，则可以在 SRV URI 中将身份验证源显式指定为 URI 选项：
Mongo::Client.new("mongodb+srv://username:myRealPassword@cluster0.mongodb.net/test?w=majority&authSource=admin")
注意
使用with方法更改数据库时，将使用适用于该实例的完整选项集在新的Client实例中确定身份验证源。 例如，如果原始客户端指定了身份验证源，则此身份验证源将优先于with调用中给出的数据库。 如果原始客户端未指定身份验证源，则新数据库将是新的身份验证源，但须遵守所使用的身份验证机制的规则。
身份验证机制
MongoDB 支持多种身份验证机制，本节将详细介绍这些机制。 可以在创建客户端时显式指定要使用的身份验证机制；如果应用程序未提供身份验证机制，则按以下方式进行选择：
对于 MongoDB 4.0 及更高版本，客户端与服务器执行 SCRAM 机制协商。 如果客户端配置中指定的用户允许使用 SCRAM-SHA-256 进行身份验证，则使用 SCRAM-SHA-256 进行身份验证。 否则使用 SCRAM-SHA-1。
对于 MongoDB 3.0 到 3.6，使用 SCRAM-SHA-1。
对于 MongoDB 2.6，使用 MONGODB-CR。
请注意：
必须始终明确请求 X.509、AWS、LDAP 和 Kerberos 身份验证机制。
如果客户端连接的 MongoDB Server 支持 SCRAM，则在未显式指定身份验证机制的情况下，客户端将尝试使用 SCRAM 进行身份验证。要使用 MONGODB-CR 对 MongoDB 3.0 及更高版本的服务器进行身份验证，必须显式请求 MONGODB-CR 机制。
SCRAM
SCRAM 身份验证是 MongoDB 的默认身份验证机制。 MongoDB 中有两种 SCRAM 机制：SCRAM-SHA- 1 （从 MongoDB 3开始提供。 0 ）和 SCRAM-SHA- 256 （从 MongoDB 4开始提供。 0 ）。如果未指定身份验证机制，但指定了用户档案，则驱动程序将尝试在服务器3上使用 SCRAM 身份验证。 0或更高版本，并将根据服务器版本和为特定用户定义的机制协商要使用的机制（可以将服务器中的用户配置为仅允许 SCRAM-SHA- 1机制、仅允许 SCRAM -SHA- 256机制或两者兼有）。
要显式指定 SCRAM-SHA-1 作为身份验证机制，请使用auth_mech: :scram Ruby 客户端选项或使用SCRAM-SHA-1作为authMechanism URI 选项的值，如下所示：
client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'mydb', user: 'test', password: '123', auth_mech: :scram ) client = Mongo::Client.new("mongodb://test:123@127.0.0.1:27017/mydb?authMechanism=SCRAM-SHA-1")
要显式指定 SCRAM-SHA-256 作为身份验证机制，请使用auth_mech: :scram256 Ruby 客户端选项或使用SCRAM-SHA-256作为authMechanism URI 选项的值，如下所示：
client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'mydb', user: 'test', password: '123', auth_mech: :scram256 ) client = Mongo::Client.new("mongodb://test:123@127.0.0.1:27017/mydb?authMechanism=SCRAM-SHA-256")
客户端证书 (X.509)
驱动程序在 TLS 协商期间提供 X.509 证书。 MONGODB-X509 身份验证机制对从此证书的标识主题名称中检索的用户名进行身份验证。
注意
由于用户名是从证书中检索的，因此无需指定用户名。 如果指定了用户名，则会将其逐字发送到服务器。如果提供了密码，则会引发错误。
此身份验证方法需要使用带证书验证的 TLS 连接。
要对客户端进行身份验证，您需要有效的 TLS 证书和私有加密密钥。 它们可以存储在单独的文件中，也可以一起存储在一个文件中（PEM 格式）。 即使证书和私钥存储在同一文件中，您也必须通过将ssl_cert和ssl_key选项传递给客户端来指定该文件的路径。
有关在 MongoDB 中配置 X. 509身份验证的更多信息，请参阅MongoDB 手册中的 X. 509教程。
client = Mongo::Client.new([ '127.0.0.1:27017' ], auth_mech: :mongodb_x509, ssl: true, ssl_cert: '/path/to/client.pem', ssl_key: '/path/to/client.pem', ssl_ca_cert: '/path/to/ca.pem' )
AWS
需要 MongoDB Enterprise 版和服务器 4.4 或更高版本。
AWS 身份验证机制使用 AWS Identity and Access Management (IAM) 和 AWS Security Token Service (STS) 向 MongoDB 服务器证明客户端的身份。简而言之，AWS 身份验证的工作原理如下：
客户端使用 Amazon Web Services IAM 档案创建发送到 MongoDB Server 的签名。
服务器使用客户端签名向 Amazon Web Services STS 发送请求。
成功的 STS 请求会返回与客户端使用的档案相对应的用户名（从技术上讲，IAM 用户或角色的 ARN）。 服务器使用 IAM 用户 ARN 来查找定义的用户，并且客户端被视为已作为该用户进行身份验证。
注意
与其他身份验证机制不同，应用程序在创建客户端时提供的用户名和服务器用户的用户名不同：客户端上的用户名是 Amazon Web Services 访问密钥 ID，但服务器上的用户名是 IAM 用户的 ARN或与访问密钥 ID 对应的角色。
Amazon Web Services 凭证由以下部分组成：
访问密钥 ID。
秘密访问密钥。
可选的会话令牌。
使用 AWS IAM 档案进行身份验证 ，使用访问密钥 ID 和秘密访问密钥。使用 临时 AWS IAM 凭证 进行身份验证 使用所有三个组件。
注意
驱动程序从不通过网络发送秘密访问密钥或会话令牌。
临时凭证用于：
Ruby 驱动程序允许将常规和临时凭证显式提供为 Ruby 选项或 URI 选项。 如果未显式提供凭证，驱动程序将尝试从下述环境变量以及 EC2 实例和 ECS 任务元数据端点中检索凭证。
显式提供档案
常规（非临时）IAM 档案可作为 Ruby 选项提供，如下所示：
client = Mongo::Client.new(['mongodb.example.com'], auth_mech: :aws, user: '<AWS-ACCESS-KEY-ID>', password: '<AWS-SECRET-ACCESS-KEY>', database: 'mydb', )
它们也可以通过 URI 提供：
client = Mongo::Client.new( 'mongodb://<AWS-ACCESS-KEY-ID>:<AWS-SECRET-ACCESS-KEY>@mongodb.example.com/mydb?authMechanism=MONGODB-AWS')
注意
通过 URI 提供凭证时，必须对它们进行百分比转义。
要提供临时凭证，请在身份验证机制属性中指定会话令牌，如下所示：
client = Mongo::Client.new(['mongodb.example.com'], auth_mech: :aws, user: '<AWS-ACCESS-KEY-ID>', password: '<AWS-SECRET-ACCESS-KEY>', auth_mech_properties: { aws_session_token: '<AWS-SESSION-TOKEN>', }, database: 'mydb', )
临时凭证也可以通过 URI 提供：
client = Mongo::Client.new( 'mongodb://<AWS-ACCESS-KEY-ID>:<AWS-SECRET-ACCESS-KEY>@mongodb.example.com/mydb?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<AWS-SESSION-TOKEN>')
自动检索档案
客户端可以从环境或 EC2 或 ECS 元数据端点检索档案。 要自动检索凭证，请指定 AWS 身份验证机制，但不要指定用户名和密码：
client = Mongo::Client.new(['mongodb.example.com'], auth_mech: :aws, database: 'mydb', ) # Using a URI: client = Mongo::Client.new( 'mongodb://mongodb.example.com/mydb?authMechanism=MONGODB-AWS')
驱动程序将尝试按指定顺序从以下来源获取档案：
AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY和AWS_SESSION_TOKEN环境变量。 这些环境变量可由各种与 AWS 相关的库和工具识别，例如官方 AWS Ruby SDK 和 AWS CLI。 它们也是在 Amazon Web Services Lambda 环境中运行时定义的。AWS STS AssumeRoleWithWebIdentity 操作 。这将返回与服务帐户令牌关联的凭证。此机制需要设置以下环境变量：
AWS_WEB_IDENTITY_TOKEN_FILE— 包含服务帐户令牌的文件的路径。AWS_ROLE_ARN- 调用者所担任角色的 Amazon 资源名称 (ARN)。AWS_ROLE_SESSION_NAME（可选）- 假定角色会话的标识符。 如果省略，驱动程序将生成一个随机名称。
AWS ECS 任务元数据端点 。这将返回与分配给容器的 ECS 任务角色关联的档案。
AWS EC2 实例元数据端点 。这将返回与分配给该实例的 EC2 实例角色关联的档案。
注意
提供任何档案的档案源必须提供一组完整的档案。 例如，如果只填充了AWS_ACCESS_KEY_ID或AWS_SECRET_ACCESS_KEY环境变量之一，而没有填充另一个，则驱动程序将引发错误。
注意
如果应用程序在 EC2 实例上的 ECS 容器中运行，并且 允许该容器访问实例元数据 ，驱动程序将尝试从 EC 实例元数据端点检索 AWS2 身份验证机制的档案，如果无法检索 ECS 任务角色档案，则可能会作为分配给 EC2 实例的 IAM 角色进行身份验证从 ECS 任务端点。
LDAP (SASL PLAIN)
需要 MongoDB Enterprise 版。
MongoDB Enterprise 版支持 LDAP 身份验证机制，该机制允许您使用轻量级目录访问协议 LDAP 委托身份验证 服务器。
警告
使用 LDAP 时，密码会以纯文本形式发送到服务器。 因此，强烈建议在使用 LDAP 作为身份验证机制时启用 TLS。
有关在 MongoDB 中配置 LDAP 身份验证的更多信息，请参阅MongoDB 手册中的 SASL/LDAP 教程。
client = Mongo::Client.new([ '127.0.0.1:27017' ], auth_mech: :plain, ssl: true, ssl_verify: true, ssl_cert: '/path/to/client.pem', ssl_ca_cert: '/path/to/ca.pem' )
Kerberos (GSSAPI)
需要 MongoDB Enterprise 版。
要将 MongoDB 服务器配置为使用 Kerberos，请参阅服务器 Kerberos 文档。
要将 Kerberos 身份验证机制与 Ruby MongoDB 驱动程序结合使用，需要实现 Kerberos 身份验证器的附加库 - mongo_kerberos - 必须安装并加载。为此，请在Gemfile 中添加：
gem 'mongo', '~> 2' gem 'mongo_kerberos', '~> 2'
...并添加到您的应用程序代码中：
require 'mongo' require 'mongo_kerberos'
如果将 Kerberos 身份验证与 MRI 结合使用，则驱动程序配置中不会指定密码，驱动程序也不会将密码发送到 MongoDB Server。相反，必须在驱动程序外部建立 Kerberos 会话，驱动程序使用此会话向服务器证明用户的身份。要建立此会话，需要将主机系统配置为支持 Kerberos 身份验证；请参阅 Kerberos 文档 或操作系统文档以了解详细信息。使用 kinit 实用程序 建立 Kerberos 会话。
如果将 Kerberos 身份验证与 JRuby 一起使用，则可以使用上述 MRI 过程在驱动程序外部建立 Kerberos 会话；或者，可以通过客户端配置直接向驱动程序提供密码，或者可以通过java.security.auth.login.config 系统属性中存储的配置提供密钥表文件的路径。此外，必须为 Kerberos 配置 Java 运行时环境；请参阅 MongoDB Java 驱动程序 Kerberos 文档 以了解更多信息。
注意
根据服务器 Kerberos 文档，在使用 Kerberos 身份验证时，必须指定运行 MongoDB 的主机的 FQDN。
注意
如果使用 MongoDB URI，请确保在用户名中出现特殊字符（例如/和@时）进行百分比转义。
# Authenticate as appuser@MYREALM: client = Mongo::Client.new("mongodb://appuser%40MYREALM@myserver.mycompany.com:27017/mydb?authMechanism=GSSAPI") # Authenticate as myapp/appuser@MYREALM: client = Mongo::Client.new("mongodb://myapp%2Fappuser%40MYREALM@myserver.mycompany.com:27017/mydb?authMechanism=GSSAPI") # Authenticate using Ruby options: client = Mongo::Client.new(['myserver.mycompany.com:27017'], auth_mech: :gssapi, user: 'myapp/appuser@MYREALM')
MONGODB-CR
已弃用：从 MongoDB 3开始，MONGODB-CR 机制已弃用。 6并从 MongoDB 4开始已删除。 0 。请改用SCRAM 身份验证。
MONGODB-CR 是 MongoDB 2.6 及更高版本的默认身份验证机制。
可以使用以下档案显式设置该机制：
client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'mydb', user: 'test', password: '123', auth_mech: :mongodb_cr )
注意
如果客户端连接的 MongoDB Server 支持 SCRAM，则在未显式指定身份验证机制的情况下，客户端将尝试使用 SCRAM 进行身份验证。要使用 MONGODB-CR 对 MongoDB 3.0 及更高版本的服务器进行身份验证，必须显式请求 MONGODB-CR 机制。