mongo 2.11.0.rc0 → 2.11.0

data/lib/mongo/version.rb

@@ -17,5 +17,5 @@ module Mongo
   # The current version of the driver.
   #
   # @since 2.0.0
-  VERSION = '2.11.0.rc0'.freeze
+  VERSION = '2.11.0'.freeze
 end

data/mongo.gemspec

@@ -9,11 +9,20 @@ Gem::Specification.new do |s|
 
   s.authors           = ['Tyler Brock', 'Emily Stolfo', 'Durran Jordan']
   s.email             = 'mongodb-dev@googlegroups.com'
-  s.homepage          = 'http://www.mongodb.org'
+  s.homepage          = 'https://docs.mongodb.com/ruby-driver/'
   s.summary           = 'Ruby driver for MongoDB'
   s.description       = 'A Ruby driver for MongoDB'
   s.license           = 'Apache-2.0'
 
+  s.metadata = {
+    'bug_tracker_uri' => 'https://jira.mongodb.org/projects/RUBY',
+    'changelog_uri' => 'https://github.com/mongodb/mongo-ruby-driver/releases',
+    'documentation_uri' => 'https://docs.mongodb.com/ruby-driver/',
+    'homepage_uri' => 'https://docs.mongodb.com/ruby-driver/',
+    'mailing_list_uri' => 'https://groups.google.com/group/mongodb-user',
+    'source_code_uri' => 'https://github.com/mongodb/mongo-ruby-driver',
+  }
+
   if File.exists?('gem-private_key.pem')
     s.signing_key     = 'gem-private_key.pem'
     s.cert_chain      = ['gem-public_cert.pem']
@@ -31,5 +40,5 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = ">= 2.3"
 
-  s.add_dependency 'bson', '>=4.4.2', '<5.0.0'
+  s.add_dependency 'bson', '>=4.6.0', '<5.0.0'
 end

data/spec/README.md

@@ -42,7 +42,7 @@ launched as follows:
     # Launch mongod in one terminal
     mkdir /tmp/mdb
     mongod --dbpath /tmp/mdb
-    
+
     # Run tests in another terminal
     rake
 
@@ -63,7 +63,7 @@ First, install [mtools](https://github.com/rueckstiess/mtools):
     export PATH=~/.local/bin:$PATH
     # On MacOS:
     export PATH=$PATH:~/Library/Python/2.7/bin
-    
+
 Then, launch a replica set:
 
     mlaunch init --replicaset --name ruby-driver-rs \
@@ -89,6 +89,28 @@ other tests require a sharded cluster with more than one shard. Tests requiring
 a single shard can be run against a deployment with multiple shards by
 specifying only one mongos address in MONGODB_URI.
 
+## Note Regarding SSL/TLS Arguments
+
+MongoDB 4.2 (server and shell) added new command line options for setting TLS
+parameters. These options follow the naming of URI options used by both the
+shell and MongoDB drivers starting with MongoDB 4.2. The new options start with
+the `--tls` prefix.
+
+Old options, starting with the `--ssl` prefix, are still supported for backwards
+compatibility, but their use is deprecated. As of this writing, mlaunch only
+supports the old `--ssl` prefix options.
+
+In the rest of this document, when TLS options are given for `mongo` or
+`mongod` they use the new `--tls` prefixed arguments, and when the same options
+are given to `mlaunch` they use the old `--ssl` prefixed forms. The conversion
+table of the options used herein is as follows:
+
+| --tls prefixed option   | --ssl prefixed option |
+| ----------------------- | --------------------- |
+| --tls                   | --ssl                 |
+| --tlsCAFile             | --sslCAFile           |
+| --tlsCertificateKeyFile | --sslPEMKeyFile       |
+
 ## TLS With Verification
 
 The test suite includes a set of TLS certificates for configuring a server
@@ -114,13 +136,13 @@ The driver's test suite is configured to verify certificates by default.
 If the server is launched with the certificates from the driver's test suite,
 the test suite can be run simply by specifying `tls=true` URI option:
 
-    MONGODB_URI='mongodb://localhost:27017/?tls=true' rake 
+    MONGODB_URI='mongodb://localhost:27017/?tls=true' rake
 
 The driver's test suite can also be executed against a server launched with
 any other certificates. In this case the certificates need to be explicitly
 specified in the URI, for example as follows:
 
-    MONGODB_URI='mongodb://localhost:27017/?tls=true&tlsCAFile=path/to/ca.crt&tlsCertificateKeyFile=path/to/client.pem' rake 
+    MONGODB_URI='mongodb://localhost:27017/?tls=true&tlsCAFile=path/to/ca.crt&tlsCertificateKeyFile=path/to/client.pem' rake
 
 Note that some tests (specifically testing TLS verification) expect the server
 to be launched using the certificates in the driver's test suite, and will
@@ -140,7 +162,7 @@ case a standalone server can be started as follows:
 To run the test suite against such a server, also omitting certificate
 verification, run:
 
-    MONGODB_URI='mongodb://localhost:27017/?tls=true&tlsInsecure=true' rake 
+    MONGODB_URI='mongodb://localhost:27017/?tls=true&tlsInsecure=true' rake
 
 Note that there are tests in the test suite that cover TLS verification, and
 they may fail if the test suite is run in this way.
@@ -153,7 +175,81 @@ mlaunch can configure authentication on the server:
 
 To run the test suite against such a server, run:
 
-    MONGODB_URI='mongodb://dev:dev@localhost:27017/' rake 
+    MONGODB_URI='mongodb://dev:dev@localhost:27017/' rake
+
+## X.509 Authentication
+
+Note: Testing X.509 authentication requires an enterprise build of the MongoDB
+server.
+
+To set up a server configured for authentication with an X.509 certificate,
+first launch a TLS-enabled server with a regular credentialed user.
+
+The credentialed user is required because mlaunch configures `--keyFile`
+option for cluster member authentication, which in turn enables authentication.
+With authentication enabled, `mongod` allows creating the first user in the
+`admin` database but the X.509 user must be created in the `$external`
+database - as a result, the X.509 user cannot be the only user in the deployment.
+
+Run the following command to set up a standalone `mongod` with a bootstrap
+user:
+
+    mlaunch init --single --dir /tmp/mdb-x509 --sslMode requireSSL \
+      --sslPEMKeyFile `pwd`/spec/support/certificates/server.pem \
+      --sslCAFile `pwd`/spec/support/certificates/ca.crt \
+      --sslClientCertificate `pwd`/spec/support/certificates/client.pem \
+      --auth --username bootstrap --password bootstrap
+
+Next, create the X.509 user. The command to create the user is the same
+across all supported MongoDB versions, and for convenience we assign its text
+to a variable as follows:
+
+    create_user_cmd="`cat <<'EOT'
+      db.getSiblingDB("$external").runCommand(
+        {
+          createUser: "C=US,ST=New York,L=New York City,O=MongoDB,OU=x509,CN=localhost",
+          roles: [
+               { role: "dbAdminAnyDatabase", db: "admin" },
+               { role: "readWriteAnyDatabase", db: "admin" },
+               { role: "userAdminAnyDatabase", db: "admin" },
+               { role: "clusterAdmin", db: "admin" },
+          ],
+          writeConcern: { w: "majority" , wtimeout: 5000 },
+        }
+      )
+    EOT
+    `"
+
+Use the MongoDB shell to execute this command:
+
+    mongo --tls \
+      --tlsCAFile `pwd`/spec/support/certificates/ca.crt \
+      --tlsCertificateKeyFile `pwd`/spec/support/certificates/client-x509.pem \
+      -u bootstrap -p bootstrap \
+      --eval "$create_user_cmd"
+
+Verify that authentication is required by running the following command, which
+should fail:
+
+    mongo --tls \
+      --tlsCAFile `pwd`/spec/support/certificates/ca.crt \
+      --tlsCertificateKeyFile `pwd`/spec/support/certificates/client-x509.pem \
+      --eval 'db.serverStatus()'
+
+Verify that X.509 authentication works by running the following command:
+
+    mongo --tls \
+      --tlsCAFile `pwd`/spec/support/certificates/ca.crt \
+      --tlsCertificateKeyFile `pwd`/spec/support/certificates/client-x509.pem \
+      --authenticationDatabase '$external' \
+      --authenticationMechanism MONGODB-X509 \
+      --eval 'db.serverStatus()'
+
+The test suite includes a set of integration tests for X.509 client authentication.
+
+To run the test suite against such a server, run:
+
+    MONGODB_URI="mongodb://localhost:27017/?authMechanism=MONGODB-X509&tls=true&tlsCAFile=spec/support/certificates/ca.crt&tlsCertificateKeyFile=spec/support/certificates/client-x509.pem" rake
 
 ## Compression
 
@@ -165,9 +261,9 @@ Generally, all URI options recognized by the driver may be set for a test run,
 and will cause the clients created by the test suite to have those options
 by default. For example, retryable writes may be turned on and off as follows:
 
-    MONGODB_URI='mongodb://localhost:27017/?retryWrites=true' rake 
+    MONGODB_URI='mongodb://localhost:27017/?retryWrites=true' rake
 
-    MONGODB_URI='mongodb://localhost:27017/?retryWrites=false' rake 
+    MONGODB_URI='mongodb://localhost:27017/?retryWrites=false' rake
 
 Individual tests may override options that the test suite uses as defaults.
 For example, retryable writes tests may create clients with the retry writes
@@ -177,7 +273,7 @@ the entire test run.
 It is also possible to, for example, reference non-default hosts and replica
 set names:
 
-    MONGODB_URI='mongodb://test.host:27017,test.host:27018/?replicaSet=fooset' rake 
+    MONGODB_URI='mongodb://test.host:27017,test.host:27018/?replicaSet=fooset' rake
 
 However, as noted in the caveats section, changing the database name used by
 the test suite is not supported.

data/spec/USERS.md

@@ -0,0 +1,72 @@
+# Test Users
+
+The Mongo Ruby Driver tests assume the presence of two `Mongo::Auth::User` objects:
+`root_user` and `test_user`. This document details the roles and privileges granted
+to those users as well as how they are created and used in the tests.
+
+Both users are defined in the [spec_config](support/spec_config.rb#L376) file.
+
+## root_user
+`root_user` is the test user with the most privileges. It is created with the following roles:
+- userAdminAnyDatabase
+- dbAdminAnyDatabase
+- readWriteAnyDatabase
+- clusterAdmin
+
+By default, `root_user` is given a username of `root-user` and a password of `password`.
+However, you may override these defaults by specifying a username and password in the
+`MONGODB_URI` environment variable while running your tests. For example, if you set `MONGODB_URI` to: `mongodb://alanturing:enigma@localhost:27017/`, the username of `root_user` would be set to `alanturing`, and the password would be set to `enigma`.
+
+## test_user
+`test_user` is the user created with a more limited set of privileges. It is created with the following
+roles:
+- readWrite on the ruby-driver database
+- dbAdmin on the ruby-driver database
+
+It is also granted the following roles against a database called "invalid_database." These permissions are used for the purpose of running tests against a database that doesn't exist.
+- readWrite on the invalid_database database
+- dbAdmin on the invalid_database database
+
+`test_user` also has the following roles, which are exclusively used to test transactions:
+- readWrite on the hr database
+- dbAdmin on the hr database
+- readWrite on the reporting database
+- dbAdmin on the reporting database
+
+The `test_user` has the username `test-user` and the password `password`; these values are not customizable without changing the source code.
+
+## User Creation
+
+Both users are typically created in the [spec_setup](support/spec_setup.rb) script, which can be
+run in two ways: either by running `bundle exec rake spec:prepare`, which only runs spec setup without
+running any actual tests, or by running `rake`, which runs spec setup and the entire test suite.
+
+First, the `spec_setup` script attempts to create the `root_user`. If this user already exists (for example,
+if you have already created this user in your test instance), `spec_setup` will skip this step. Once
+the script has verified the existence of `root_user`, it will create a client authenticated with the `root_user` and use that client to create a second user, `test_user`. Because `root_user` has the `userAdminAnyDatabase` role, it has the permissions necessary to create and destroy users on your MongoDB instance. If you have already created a user with the same credentials as `test_user` prior to running
+the `spec_setup` script, the script will delete this user and re-create it.
+
+The `root_user` is created in the `admin` database, while the `test_user` is created in the `ruby-driver`
+database.
+
+The authentication mechanism used to store the user credentials is going to change depending on the version of MongoDB running on your deployment. If you are running tests against a MongoDB instance with a server version older than 3.0, the users will be created using the `MONGODB-CR` authentication mechanism. If your server version is between 3.0 and 3.6 (inclusive), the test users will be created using the `SCRAM-SHA-1` mechanism, which was introduced as the new default starting in MongoDB version 3.0. If you are running a version of MongoDB newer than 4.0, test users will be authenticated using either `SCRAM-SHA-1` or `SCRAM-SHA-256`.
+
+**Note:** (m-launch)[http://blog.rueckstiess.com/mtools/mlaunch.html], the client tool we use to spin up MongoDB instances for our tests, creates users EXCLUSIVELY with the `SCRAM-SHA-1` mechanism, even when `SCRAM-SHA-256` is enabled on the test server. This should not impact your ability to run the Mongo Ruby Driver test suite.
+
+## Test Usage
+
+`root_user` is used in the Mongo Ruby Driver tests to perform functionality that requires its high-level
+roles and privileges (if your client is set up with authentication), such as creating and destroying users and database administration. To easily set up a `Mongo::Client` object authenticated with the roles and privileges of `root_user`, you can initialize a client using the `ClientRegistry` module as follows:
+
+```
+client = ClientRegistry.instance.global_client('root_authorized')
+```
+
+Of course, not every test will require you to create a client with so many privileges. Often, it is enough
+to have a user who is only authorized to read and write to a specific test database. In this case, it is preferable to use `test_user`. To initialize a `Mongo::Client` object authenticated with the `test_user` object, use the `ClientRegistry` module as follows:
+
+```
+client = ClientRegistry.instance.global_client('authorized')
+```
+
+Once you have initialized these client objects, you may use them to perform functionality required by your tests.

data/spec/integration/auth_spec.rb

@@ -41,7 +41,7 @@ describe 'Auth' do
           it 'indicates scram-sha-1 was used' do
             expect do
               connection.connect!
-            end.to raise_error(Mongo::Auth::Unauthorized, 'User nonexistent_user (mechanism: scram) is not authorized to access admin (used mechanism: SCRAM-SHA-1)')
+            end.to raise_error(Mongo::Auth::Unauthorized, /User nonexistent_user \(mechanism: scram\) is not authorized to access admin.*\(used mechanism: SCRAM-SHA-1\)/)
           end
         end
 
@@ -53,7 +53,7 @@ describe 'Auth' do
           it 'indicates scram-sha-1 was used' do
             expect do
               connection.connect!
-            end.to raise_error(Mongo::Auth::Unauthorized, 'User nonexistent_user (mechanism: scram) is not authorized to access admin (used mechanism: SCRAM-SHA-1)')
+            end.to raise_error(Mongo::Auth::Unauthorized, /User nonexistent_user \(mechanism: scram\) is not authorized to access admin.*\(used mechanism: SCRAM-SHA-1\)/)
           end
         end
       end
@@ -73,7 +73,7 @@ describe 'Auth' do
           it 'indicates scram-sha-1 was used' do
             expect do
               connection.connect!
-            end.to raise_error(Mongo::Auth::Unauthorized, "User existing_user (mechanism: scram) is not authorized to access admin (used mechanism: SCRAM-SHA-1)")
+            end.to raise_error(Mongo::Auth::Unauthorized, /User existing_user \(mechanism: scram\) is not authorized to access admin.*\(used mechanism: SCRAM-SHA-1\)/)
           end
         end
 
@@ -85,7 +85,7 @@ describe 'Auth' do
           it 'indicates scram-sha-256 was used' do
             expect do
               connection.connect!
-            end.to raise_error(Mongo::Auth::Unauthorized, "User existing_user (mechanism: scram256) is not authorized to access admin (used mechanism: SCRAM-SHA-256)")
+            end.to raise_error(Mongo::Auth::Unauthorized, /User existing_user \(mechanism: scram256\) is not authorized to access admin.*\(used mechanism: SCRAM-SHA-256\)/)
           end
         end
       end
@@ -101,7 +101,7 @@ describe 'Auth' do
         it 'indicates scram-sha-1 was requested and used' do
           expect do
             connection.connect!
-          end.to raise_error(Mongo::Auth::Unauthorized, 'User nonexistent_user (mechanism: scram) is not authorized to access admin (used mechanism: SCRAM-SHA-1)')
+          end.to raise_error(Mongo::Auth::Unauthorized, /User nonexistent_user \(mechanism: scram\) is not authorized to access admin.*\(used mechanism: SCRAM-SHA-1\)/)
         end
       end
 
@@ -114,13 +114,27 @@ describe 'Auth' do
         it 'indicates scram-sha-256 was requested and used' do
           expect do
             connection.connect!
-          end.to raise_error(Mongo::Auth::Unauthorized, 'User nonexistent_user (mechanism: scram256) is not authorized to access admin (used mechanism: SCRAM-SHA-256)')
+          end.to raise_error(Mongo::Auth::Unauthorized, /User nonexistent_user \(mechanism: scram256\) is not authorized to access admin.*\(used mechanism: SCRAM-SHA-256\)/)
         end
       end
     end
 
+    context 'when authentication fails' do
+      let(:options) { SpecConfig.instance.ssl_options.merge(
+        user: 'nonexistent_user', password: 'foo') }
+
+      it 'reports auth source used' do
+        expect do
+          connection.connect!
+        end.to raise_error(Mongo::Auth::Unauthorized, /User nonexistent_user.*is not authorized to access admin \(auth source: admin\)/)
+      end
+    end
+
     context 'attempting to connect to a non-tls server with tls' do
       require_no_tls
+      # The exception raised is SocketTimeout on 3.6 server for whatever reason,
+      # run the test on 4.0+ only.
+      min_server_fcv '4.0'
 
       let(:options) { {ssl: true} }
 

data/spec/integration/client_construction_spec.rb

@@ -7,8 +7,10 @@ describe 'Client construction' do
     SpecConfig.instance.test_options.merge(
       server_selection_timeout: 5,
       database: SpecConfig.instance.test_db,
+    ).merge(SpecConfig.instance.credentials_or_x509(
       user: SpecConfig.instance.test_user.name,
-      password: SpecConfig.instance.test_user.password)
+      password: SpecConfig.instance.test_user.password,
+    ))
   end
 
   context 'in single topology' do

data/spec/integration/client_options_spec.rb

@@ -0,0 +1,437 @@
+require 'spec_helper'
+
+describe 'Client options' do
+  let(:uri) { "mongodb://#{credentials}127.0.0.1:27017/#{options}" }
+
+  let(:credentials) { nil }
+  let(:options) { nil }
+
+  let(:client_opts) { {} }
+
+  let(:client) { new_local_client_nmio(uri, client_opts) }
+
+  let(:user) { 'username' }
+  let(:pwd) { 'password' }
+
+  shared_examples_for 'a supported auth mechanism' do
+    context 'with URI options' do
+      let(:credentials) { "#{user}:#{pwd}@" }
+      let(:options) { "?authMechanism=#{auth_mech_string}" }
+
+      it 'creates a client with the correct auth mechanism' do
+        expect(client.options[:auth_mech]).to eq(auth_mech_sym)
+      end
+    end
+
+    context 'with client options' do
+      let(:client_opts) do
+        {
+          auth_mech: auth_mech_sym,
+          user: user,
+          password: pwd,
+        }
+      end
+
+      it 'creates a client with the correct auth mechanism' do
+        expect(client.options[:auth_mech]).to eq(auth_mech_sym)
+      end
+    end
+  end
+
+  shared_examples_for 'auth mechanism that uses database or default auth source' do |default_auth_source:|
+    context 'where no database is provided' do
+      context 'with URI options' do
+        let(:credentials) { "#{user}:#{pwd}@" }
+        let(:options) { "?authMechanism=#{auth_mech_string}" }
+
+        it 'creates a client with default auth source' do
+          expect(client.options['auth_source']).to eq(default_auth_source)
+        end
+      end
+
+      context 'with client options' do
+        let(:client_opts) do
+          {
+            auth_mech: auth_mech_sym,
+            user: user,
+            password: pwd,
+          }
+        end
+
+        it 'creates a client with default auth source' do
+          expect(client.options['auth_source']).to eq(default_auth_source)
+        end
+      end
+    end
+
+    context 'where database is provided' do
+      let(:database) { 'test-db' }
+
+      context 'with URI options' do
+        let(:credentials) { "#{user}:#{pwd}@" }
+        let(:options) { "#{database}?authMechanism=#{auth_mech_string}" }
+
+        it 'creates a client with database as auth source' do
+          expect(client.options['auth_source']).to eq(database)
+        end
+      end
+
+      context 'with client options' do
+        let(:client_opts) do
+          {
+            auth_mech: auth_mech_sym,
+            user: user,
+            password: pwd,
+            database: database
+          }
+        end
+
+        it 'creates a client with database as auth source' do
+          expect(client.options['auth_source']).to eq(database)
+        end
+      end
+    end
+  end
+
+  shared_examples_for 'an auth mechanism with ssl' do
+    let(:ca_file_path) { '/path/to/ca.pem' }
+    let(:cert_path) { '/path/to/client.pem' }
+
+    context 'with URI options' do
+      let(:credentials) { "#{user}:#{pwd}@" }
+      let(:options) { "?authMechanism=#{auth_mech_string}&tls=true&tlsCAFile=#{ca_file_path}&tlsCertificateKeyFile=#{cert_path}" }
+
+      it 'creates a client with ssl properties' do
+        expect(client.options[:ssl]).to be true
+        expect(client.options[:ssl_cert]).to eq(cert_path)
+        expect(client.options[:ssl_ca_cert]).to eq(ca_file_path)
+        expect(client.options[:ssl_key]).to eq(cert_path)
+      end
+    end
+
+    context 'with client options' do
+      let(:client_opts) do
+        {
+          auth_mech: auth_mech_sym,
+          ssl: true,
+          ssl_cert: cert_path,
+          ssl_key: cert_path,
+          ssl_ca_cert: ca_file_path,
+          user: user,
+          password: pwd
+        }
+      end
+
+      it 'creates a client with ssl properties' do
+        expect(client.options[:ssl]).to be true
+        expect(client.options[:ssl_cert]).to eq(cert_path)
+        expect(client.options[:ssl_ca_cert]).to eq(ca_file_path)
+        expect(client.options[:ssl_key]).to eq(cert_path)
+      end
+    end
+  end
+
+  shared_examples_for 'an auth mechanism that doesn\'t support auth_mech_properties' do
+    context 'with URI options' do
+      let(:credentials) { "#{user}:#{pwd}@" }
+      let(:options) { "?authMechanism=#{auth_mech_string}&authMechanismProperties=CANONICALIZE_HOST_NAME:true" }
+
+      it 'raises an exception on client creation' do
+        expect {
+          client
+        }.to raise_error(Mongo::Auth::InvalidConfiguration, /mechanism_properties are not supported/)
+      end
+    end
+
+    context 'with client options' do
+      let(:client_opts) do
+        {
+          auth_mech: auth_mech_sym,
+          user: user,
+          password: pwd,
+          auth_mech_properties: {
+            canonicalize_host_name: true
+          }
+        }
+      end
+
+      it 'raises an exception on client creation' do
+        expect {
+          client
+        }.to raise_error(Mongo::Auth::InvalidConfiguration, /mechanism_properties are not supported/)
+      end
+    end
+  end
+
+  shared_examples_for 'an auth mechanism that doesn\'t support invalid auth sources' do
+    context 'with URI options' do
+      let(:credentials) { "#{user}:#{pwd}@" }
+      let(:options) { "?authMechanism=#{auth_mech_string}&authSource=foo" }
+
+      it 'raises an exception on client creation' do
+        expect {
+          client
+        }.to raise_error(Mongo::Auth::InvalidConfiguration, /invalid auth source/)
+      end
+    end
+
+    context 'with client options' do
+      let(:client_opts) do
+        {
+          auth_mech: auth_mech_sym,
+          user: user,
+          password: pwd,
+          auth_source: 'foo'
+        }
+      end
+
+      it 'raises an exception on client creation' do
+        expect {
+          client
+        }.to raise_error(Mongo::Auth::InvalidConfiguration, /invalid auth source/)
+      end
+    end
+  end
+
+  context 'with MONGODB-CR auth mechanism' do
+    let(:auth_mech_string) { 'MONGODB-CR' }
+    let(:auth_mech_sym) { :mongodb_cr }
+
+    it_behaves_like 'a supported auth mechanism'
+    it_behaves_like 'auth mechanism that uses database or default auth source', default_auth_source: 'admin'
+    it_behaves_like 'an auth mechanism that doesn\'t support auth_mech_properties'
+  end
+
+  context 'with SCRAM-SHA-1 auth mechanism' do
+    let(:auth_mech_string) { 'SCRAM-SHA-1' }
+    let(:auth_mech_sym) { :scram }
+
+    it_behaves_like 'a supported auth mechanism'
+    it_behaves_like 'auth mechanism that uses database or default auth source', default_auth_source: 'admin'
+    it_behaves_like 'an auth mechanism that doesn\'t support auth_mech_properties'
+  end
+
+  context 'with SCRAM-SHA-256 auth mechanism' do
+    let(:auth_mech_string) { 'SCRAM-SHA-256' }
+    let(:auth_mech_sym) { :scram256 }
+
+    it_behaves_like 'a supported auth mechanism'
+    it_behaves_like 'auth mechanism that uses database or default auth source', default_auth_source: 'admin'
+    it_behaves_like 'an auth mechanism that doesn\'t support auth_mech_properties'
+  end
+
+  context 'with GSSAPI auth mechanism' do
+    require_mongo_kerberos
+
+    let(:auth_mech_string) { 'GSSAPI' }
+    let(:auth_mech_sym) { :gssapi }
+
+    it_behaves_like 'a supported auth mechanism'
+    it_behaves_like 'an auth mechanism that doesn\'t support invalid auth sources'
+
+    let(:auth_mech_properties) { { canonicalize_host_name: true, service_name: 'other'} }
+
+    context 'with URI options' do
+      let(:credentials) { "#{user}:#{pwd}@" }
+
+      context 'with default auth mech properties' do
+        let(:options) { '?authMechanism=GSSAPI' }
+
+        it 'correctly sets client options' do
+          expect(client.options[:auth_mech_properties]).to eq({ 'service_name' => 'mongodb' })
+        end
+      end
+    end
+
+    context 'with client options' do
+      let(:client_opts) do
+        {
+          auth_mech: :gssapi,
+          user: user,
+          password: pwd
+        }
+      end
+
+      it 'sets default auth mech properties' do
+        expect(client.options[:auth_mech_properties]).to eq({ 'service_name' => 'mongodb' })
+      end
+    end
+  end
+
+  context 'with PLAIN auth mechanism' do
+    let(:auth_mech_string) { 'PLAIN' }
+    let(:auth_mech_sym) { :plain }
+
+    it_behaves_like 'a supported auth mechanism'
+    it_behaves_like 'auth mechanism that uses database or default auth source', default_auth_source: '$external'
+    it_behaves_like 'an auth mechanism with ssl'
+    it_behaves_like 'an auth mechanism that doesn\'t support auth_mech_properties'
+  end
+
+  context 'with MONGODB-X509 auth mechanism' do
+    let(:auth_mech_string) { 'MONGODB-X509' }
+    let(:auth_mech_sym) { :mongodb_x509 }
+
+    let(:pwd) { nil }
+
+    it_behaves_like 'a supported auth mechanism'
+    it_behaves_like 'an auth mechanism with ssl'
+    it_behaves_like 'an auth mechanism that doesn\'t support auth_mech_properties'
+    it_behaves_like 'an auth mechanism that doesn\'t support invalid auth sources'
+
+    context 'with URI options' do
+      let(:credentials) { "#{user}@" }
+      let(:options) { '?authMechanism=MONGODB-X509' }
+
+      it 'sets default auth source' do
+        expect(client.options[:auth_source]).to eq('$external')
+      end
+
+      context 'when username is not provided' do
+        let(:credentials) { '' }
+
+        it 'recognizes the mechanism with no username' do
+          expect(client.options[:user]).to be_nil
+        end
+      end
+
+      context 'when a password is provided' do
+        let(:credentials) { "#{user}:password@" }
+
+        it 'raises an exception on client creation' do
+          expect {
+            client
+          }.to raise_error(Mongo::Auth::InvalidConfiguration, /password is not supported/)
+        end
+      end
+    end
+
+    context 'with client options' do
+      let(:client_opts) { { auth_mech: :mongodb_x509, user: user } }
+
+      it 'sets default auth source' do
+        expect(client.options[:auth_source]).to eq('$external')
+      end
+
+      context 'when username is not provided' do
+        let(:client_opts) { { auth_mech: :mongodb_x509} }
+
+        it 'recognizes the mechanism with no username' do
+          expect(client.options[:user]).to be_nil
+        end
+      end
+
+      context 'when a password is provided' do
+        let(:client_opts) { { auth_mech: :mongodb_x509, user: user, password: 'password' } }
+
+        it 'raises an exception on client creation' do
+          expect {
+            client
+          }.to raise_error(Mongo::Auth::InvalidConfiguration, /password is not supported/)
+        end
+      end
+    end
+  end
+
+  context 'with no auth mechanism provided' do
+    context 'with URI options' do
+      context 'with no credentials' do
+        it 'creates a client without credentials' do
+          expect(client.options[:user]).to be_nil
+          expect(client.options[:password]).to be_nil
+        end
+      end
+
+      context 'with empty username' do
+        let(:credentials) { '@' }
+
+        it 'raises an exception' do
+          expect {
+            client
+          }.to raise_error(Mongo::Auth::InvalidConfiguration, /empty username is not supported/)
+        end
+      end
+    end
+
+    context 'with client options' do
+      context 'with no credentials' do
+        it 'creates a client without credentials' do
+          expect(client.options[:user]).to be_nil
+          expect(client.options[:password]).to be_nil
+        end
+      end
+
+      context 'with empty username' do
+        let(:client_opts) { { user: '', password: '' } }
+
+        it 'raises an exception' do
+          expect {
+            client
+          }.to raise_error(Mongo::Auth::InvalidConfiguration, /empty username is not supported/)
+        end
+      end
+    end
+  end
+
+  context 'with auth source provided' do
+    let(:auth_source) { 'foo' }
+
+    context 'with URI options' do
+      let(:options) { "?authSource=#{auth_source}" }
+
+      it 'correctly sets auth source on the client' do
+        expect(client.options[:auth_source]).to eq(auth_source)
+      end
+    end
+
+    context 'with client options' do
+      let(:client_opts) { { auth_source: auth_source } }
+
+      it 'correctly sets auth source on the client' do
+        expect(client.options[:auth_source]).to eq(auth_source)
+      end
+    end
+  end
+
+  context 'with auth mechanism properties' do
+    let(:service_name) { 'service name' }
+    let(:canonicalize_host_name) { true }
+    let(:service_realm) { 'service_realm' }
+
+    let(:auth_mechanism_properties) do
+      {
+        service_name: service_name,
+        canonicalize_host_name: canonicalize_host_name,
+        service_realm: service_realm
+      }
+    end
+
+    context 'with URI options' do
+      let(:options) do
+        "?authMechanismProperties=SERVICE_NAME:#{service_name}," +
+          "CANONICALIZE_HOST_NAME:#{canonicalize_host_name}," +
+          "SERVICE_REALM:#{service_realm}"
+      end
+
+      it 'correctly sets auth mechanism properties on the client' do
+        expect(client.options[:auth_mech_properties]).to eq({
+          'service_name' => service_name,
+          'canonicalize_host_name' => canonicalize_host_name,
+          'service_realm' => service_realm
+        })
+      end
+    end
+
+    context 'with client options' do
+      let(:client_opts) { { auth_mech_properties: auth_mechanism_properties } }
+
+      it 'correctly sets auth mechanism properties on the client' do
+        expect(client.options[:auth_mech_properties]).to eq({
+          'service_name' => service_name,
+          'canonicalize_host_name' => canonicalize_host_name,
+          'service_realm' => service_realm
+        })
+      end
+    end
+  end
+end