Fix RUBY-2055 Driver sends null pwd field in createUser when password is not specified (#1609)

* Shorten lines to 79 columns

* RUBY-2055 fix user creation without password

* Use dashes for second level headings

* Give an example for creating an x.509 user

Co-authored-by: Oleg Pudeyev <p@users.noreply.github.com>

Author: p-mongo

docs/tutorials/ruby-driver-authentication.txt

@@ -55,6 +55,8 @@ Alternatively, setting the current database and credentials can be done in one s
                                            user:'test',
                                            password:'123' )
 
+.. _auth-source:
+
 Auth Source
 ```````````
 

docs/tutorials/user-management.txt

@@ -12,18 +12,21 @@ User Management
    :depth: 1
    :class: singlecol
 
-The Mongo Ruby Driver provides a set of methods for managing users in a MongoDB deployment.
-All of these methods are defined on the ``Mongo::Auth::User::View`` class, which defines the
-behavior for performing user-related operations on a database. You can access a database's
-user view by calling the ``users`` method on the correpsonding ``Mongo::Database`` object:
+The Mongo Ruby Driver provides a set of methods for managing users in a
+MongoDB deployment. All of these methods are defined on the
+``Mongo::Auth::User::View`` class, which defines the behavior for
+performing user-related operations on a database. You can access a database's
+user view by calling the ``users`` method on the correpsonding
+``Mongo::Database`` object:
 
 .. code-block:: ruby
 
   client.database.users
 
-Note that this will open a view on the database to which the client is already connected.
-To interact with the users defined on a different database, call the client's ``use`` method
-and pass in the name of the database with which you want to connect:
+Note that this will open a view on the database to which the client is already
+connected. To interact with the users defined on a different database, call
+the client's ``use`` method and pass in the name of the database with which
+you want to connect:
 
 .. code-block:: ruby
 
@@ -34,12 +37,39 @@ In this example, all operations would be performed on the ``users`` database.
 For more information about users and user management, see MongoDB's
 :manual:`online documentation </core/security-users>`.
 
-Creating a user
-```````````````
+
+Users and Databases
+-------------------
+
+When a client connects to the server, MongoDB distinguishes the database
+that the client will perform operations on from the `auth source <auth-source>`_
+which is the database storing the user that the client is authenticating as.
+
+In many cases, the auth source is the same as the database. When they differ,
+user management operations must be done on the auth source database. For
+example, to create a user authenticating with X.509 certifcate, which must be
+defined on the ``$external`` database:
+
+.. code-block:: ruby
+
+  client.use('$external').database.users.create(
+    'C=US,ST=New York,L=New York City,O=MongoDB,OU=x509,CN=localhost',
+    roles: [{role: 'read', db: 'admin'}],
+  )
+
+Note that the auth source is not specified for creating the user - auth source
+is only used during the authentication process. If ``#create`` is invoked with
+a ``User`` object with ``auth_source`` set, the auth source is ignored for
+the purposes of user management.
+
+
+Creating Users
+--------------
+
 There are two ways to create a new database user with the Ruby Driver.
 
-The simplest way to create a new user is to use the ``create`` method, passing in a username,
-password, and roles:
+The simplest way to create a new user is to use the ``create`` method,
+passing in a username, password, and roles:
 
 .. code-block:: ruby
 
@@ -49,32 +79,34 @@ password, and roles:
     roles: [ Mongo::Auth::Roles::READWRITE ]
   )
 
-Another way to create a user is to first create a ``Mongo::Auth::User`` object with all the
-user information and then pass that object into the ``create`` method instead.
+Another way to create a user is to first create a ``Mongo::Auth::User`` object
+with all the user information and then pass that object into the ``create``
+method instead.
 
 .. code-block:: ruby
 
-  user = Mongo::User.new({
+  user = Mongo::User.new(
     user: 'alanturing',
     password: 'enigma',
     roles: [ Mongo::Auth::Roles::READWRITE ]
-  })
+  )
 
   client.database.users.create(user)
 
-Note that your new user's credentials will be stored in whatever database your ``client``
-object is currently connected to. This will be your user's ``auth_source``, and you must
-be connected to that same database in order to update, remove, or get information about
-the user you just created in the future.
+Note that your new user's credentials will be stored in whatever database your
+``client`` object is currently connected to. This will be your user's
+``auth_source``, and you must be connected to that same database in order to
+update, remove, or get information about the user you just created in the future.
 
 The ``create`` method takes a ``Hash`` of options as an optional second argument.
 The ``:roles`` option allows you to grant permissions to the new user.
-For example, the ``Mongo::Auth::Roles::READ_WRITE`` role grants the user the ability to both
-read from and write to the database in which they were created. Each role can be specified
-as a ``String`` or as a ``Hash``. If you would like to grant permissions to a user on a database
-other than the one on which they were created, you can pass that database name in the role ``Hash``.
-To create a user ``alanturing`` with permission to read and write on the ``machines`` database,
-you could execute the following code:
+For example, the ``Mongo::Auth::Roles::READ_WRITE`` role grants the user the
+ability to both read from and write to the database in which they were created.
+Each role can be specified as a ``String`` or as a ``Hash``. If you would like
+to grant permissions to a user on a database other than the one on which they
+were created, you can pass that database name in the role ``Hash``. To create
+a user ``alanturing`` with permission to read and write on the ``machines``
+database, you could execute the following code:
 
 .. code-block:: ruby
 
@@ -84,54 +116,59 @@ you could execute the following code:
     roles: [{ role: Mongo::Auth::Roles::READWRITE, db: 'machines' }]
   )
 
-For more information about roles in MongoDB, see the :manual:`Built-in roles</reference/built-in-roles/>`
-documentation.
+For more information about roles in MongoDB, see the
+:manual:`Built-in roles</reference/built-in-roles/>` documentation.
 
-In addition to the ``:roles`` option, the ``create`` method supports a ``:session`` option,
-which allows you to specify a ``Mongo::Session`` object to use for this operation,
-as well as a ``:write_concern`` option, which specifies the write concern of this operation
-when performed on a replica set.
+In addition to the ``:roles`` option, the ``create`` method supports a
+``:session`` option, which allows you to specify a ``Mongo::Session`` object
+to use for this operation, as well as a ``:write_concern`` option, 
+which specifies the write concern of this operation when performed on a
+replica set.
 
 .. seealso::
   :manual:`Built-in roles</reference/built-in-roles/>`
   :manual:`Write Concerns</core/replica-set-write-concern/>`,
   :ref:`Sessions<sessions>`,
 
-User Info
-`````````
-To view information about a user that already exists in the database, use the ``info`` method:
+
+User Information
+----------------
+
+To view information about a user that already exists in the database, use the
+``info`` method:
 
 .. code-block:: ruby
 
   client.database.users.info('alanturing')
 
-If the user exists, this method will return an ``Array`` object
-containing a ``Hash`` with information about the user, such as
-their id, username, the database they were created on, and their
-roles. If the user doesn't exist, this method will return an
-empty Array.
+If the user exists, this method will return an ``Array`` object containing a
+``Hash`` with information about the user, such as their id, username, the
+database they were created on, and their roles. If the user doesn't exist,
+this method will return an empty Array.
 
-The ``info`` method also takes an optional ``Hash`` of options
-as a second argument. Currently, the only supported option is ``:session``,
-which allows you to specify a ``Mongo::Session`` object to use for this
-operation.
+The ``info`` method also takes an optional ``Hash`` of options as a second
+argument. Currently, the only supported option is ``:session``, which allows
+you to specify a ``Mongo::Session`` object to use for this operation.
 
-The Ruby Driver does not have a method that lists all of the users
-that currently exist in a database.
+The Ruby Driver does not have a method that lists all of the users that
+currently exist in a database.
 
 .. seealso::
   :ref:`Sessions <sessions>`
 
-Updating a user
-```````````````
-To update a user that already exists in the database, you can use the ``update`` method in
-one of two ways. The first way is to specify the name of the user you wish to update,
-along with a new set of options.
+
+Updating Users
+--------------
+
+To update a user that already exists in the database, you can use the
+``update`` method in one of two ways. The first way is to specify the name of
+the user you wish to update, along with a new set of options.
 
 .. warning::
 
-  You must include all user options in the options ``Hash``, even those options whose values
-  will remain the same. Omitting an option is the same as setting it to an empty value.
+  You must include all user options in the options ``Hash``, even those options
+  whose values will remain the same. Omitting an option is the same as setting
+  it to an empty value.
 
 .. code-block:: ruby
 
@@ -141,8 +178,8 @@ along with a new set of options.
     password: 'turing-test'
   )
 
-The second way to update a user is to pass an updated ``Mongo::Auth::User`` object
-to the ``update`` method in lieu of a username.
+The second way to update a user is to pass an updated ``Mongo::Auth::User``
+object to the ``update`` method in lieu of a username.
 
 .. code-block:: ruby
 
@@ -154,17 +191,19 @@ to the ``update`` method in lieu of a username.
 
   client.database.users.update(user)
 
-Optionally, the ``update`` method takes a ``Hash`` of options as a second argument.
-The two possible options for this method are ``:session``, which allows you to specify
-a ``Mongo::Session`` object on which to perform this operation, and ``:write_concern``,
-which sets a write concern if this operation is performed on a replica set.
+Optionally, the ``update`` method takes a ``Hash`` of options as a second
+argument. The two possible options for this method are ``:session``, which
+allows you to specify a ``Mongo::Session`` object on which to perform this
+operation, and ``:write_concern``, which sets a write concern if this operation
+is performed on a replica set.
 
 .. seealso::
   :ref:`Sessions<sessions>`
   :manual:`Write Concerns</core/replica-set-write-concern/>`,
 
-Removing users
-``````````````
+Removing Users
+--------------
+
 To remove a user from the database, use the ``remove`` method:
 
 .. code-block:: ruby
@@ -183,4 +222,3 @@ from a database.
 .. seealso::
   :ref:`Sessions<sessions>`
   :manual:`Write Concerns</core/replica-set-write-concern/>`,
-

lib/mongo/auth/user.rb

@@ -151,6 +151,8 @@ def sasl_prepped_password
       #   authorized for.
       # @option options [ String ] :user The user name.
       # @option options [ String ] :password The user's password.
+      # @option options [ String ] :pwd Legacy option for the user's password.
+      #   If :password and :pwd are both specified, :password takes precedence.
       # @option options [ Symbol ] :auth_mech The authorization mechanism.
       # @option options [ Array<String>, Array<Hash> ] roles The user roles.
       # @option options [ String ] :client_key The user's client key cached from a previous
@@ -196,7 +198,11 @@ def initialize(options)
       #
       # @since 2.0.0
       def spec
-        { pwd: password, roles: roles }
+        {roles: roles}.tap do |spec|
+          if password
+            spec[:pwd] = password
+          end
+        end
       end
 
       private

spec/lite_spec_helper.rb

@@ -127,6 +127,7 @@
   end
 
   config.expect_with :rspec do |c|
+    c.syntax = [:should, :expect]
     c.max_formatted_output_length = 10000
   end
 end

spec/mongo/auth/user/view_spec.rb

@@ -2,8 +2,10 @@
 
 describe Mongo::Auth::User::View do
 
+  let(:database) { root_authorized_client.database }
+
   let(:view) do
-    described_class.new(root_authorized_client.database)
+    described_class.new(database)
   end
 
   before do
@@ -51,6 +53,39 @@
 
   describe '#create' do
 
+    context 'when password is not provided' do
+
+      let(:database) { root_authorized_client.use('$external').database }
+
+      let(:username) { 'passwordless-user' }
+
+      let(:response) do
+        view.create(
+          username,
+          # https://stackoverflow.com/questions/55939832/mongodb-external-database-cannot-create-new-user-with-user-defined-role
+          roles: [{role: 'read', db: 'admin'}],
+        )
+      end
+
+      before do
+        begin
+          view.remove(username)
+        rescue Mongo::Error::OperationFailure
+          # can be user not found, ignore
+        end
+      end
+
+      it 'creates the user' do
+        view.info(username).should == []
+
+        lambda do
+          response
+        end.should_not raise_error
+
+        view.info(username).first['user'].should == username
+      end
+    end
+
     context 'when a session is not used' do
 
       let!(:response) do

spec/mongo/auth/user_spec.rb

@@ -325,4 +325,16 @@
       end
     end
   end
+
+  describe '#spec' do
+    context 'when no password and no roles are set' do
+      let(:user) do
+        described_class.new(user: 'foo')
+      end
+
+      it 'is a hash with empty roles' do
+        user.spec.should == {roles: []}
+      end
+    end
+  end
 end