Add information about user auth_source to the Ruby Driver documentation (#1593)

* provide info about the user auth source

* add info about auth source to user-management docs

Author: Emily Giurleo

docs/tutorials/ruby-driver-authentication.txt

@@ -32,8 +32,6 @@ client.
                              user: 'test',
                              password: '123' )
 
-For MongoDB 2.6 and later, ``:auth_source`` defaults to **admin**,
-otherwise the current database is used.
 
 The current database can be changed with the client's ``use`` method.
 
@@ -57,6 +55,30 @@ Alternatively, setting the current database and credentials can be done in one s
                                            user:'test',
                                            password:'123' )
 
+Auth Source
+```````````
+
+A user's auth source is the database where that user's authentication credentials are stored.
+
+When creating a client with authentication credentials, you may specify an auth source
+for the user:
+
+.. code-block:: ruby
+
+  client = Mongo::Client.new([ '127.0.0.1:27017' ],
+                             user: 'test',
+                             password: '123',
+                             auth_source: 'admin' )
+
+If no auth source is specified, then a default will be assumed by the client. The default
+auth source depends on the authentication mechanism that is being used to connect.
+
+For the ``MONGODB-CR``, ``SCRAM-SHA-1``, and ``SCRAM-SHA-256`` authentication mechanisms, the default
+auth source is the database to which the client is connecting; if no database is specified,
+`admin` becomes the default auth source. For the ``PLAIN`` mechanism (LDAP), the default auth source
+is the database to which the client is connecting; if no database is specified, ``$external`` is
+used as the auth source. For the ``GSSAPI`` and ``MONGODB_X509`` mechanisms,
+the auth source is always ``$external``.
 
 MONGODB-CR Mechanism
 ````````````````````

docs/tutorials/user-management.txt

@@ -62,6 +62,11 @@ user information and then pass that object into the ``create`` method instead.
 
   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.
+
 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