<commit_before>**************
Authentication
**************

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

MongoDB supports a variety of
:manual:`authentication mechanisms </core/authentication/>`.

For more information about configuring your MongoDB server for each of
these authentication mechanisms see MongoDB's
:manual:`online documentation </tutorial/enable-authentication>`.

For more information about users and the Ruby driver's helpers for
user management, see the :ref:`User Management tutorial<user-management>`.


Providing credentials
=====================

If authentication is enabled, provide credentials when creating a new
client:

.. code-block:: ruby

  client = Mongo::Client.new([ '127.0.0.1:27017' ],
                             user: 'test',
                             password: '<PASSWORD>',
                             database: 'mydb' )

  # If using a URI:
  client = Mongo::Client.new("mongodb://test:123@127.0.0.1:27017/mydb")

Authentication credentials can be changed on a client instance to obtain
a new client using the ``Client#with`` method:

.. code-block:: ruby

  authenticated_client = client.with( user: 'another-user',
                                      password: '<PASSWORD>' )

It is also possible to change the client's database and credentials in
one step:

.. code-block:: ruby

  authenticated_music_client = client.with( database: 'music',
                                            user:'test',
                                            password:'<PASSWORD>' )


.. _auth-source:

Auth Source
===========

A user's auth source is the database where that user's authentication
credentials are stored.

The user's auth source may be specified whenever the credentials are specified:

.. code-block:: ruby

  client = Mongo::Client.new([ '127.0.0.1:27017' ],
                             database: 'mydb',
                             user: 'test',
                             password: '<PASSWORD>',
                             auth_source: 'admin' )

  # If using a URI:
  client = Mongo::Client.new("mongodb://test:123@127.0.0.1:27017/mydb?authSource=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`` database is the default
database and hence 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, the ``$external`` database is used as the
auth source. For the ``AWS``, ``GSSAPI`` and ``MONGODB_X509`` mechanisms, the
auth source is always ``$external``.

.. note::

  When changing the database using the ``with`` method, the auth source is
  determined in the new ``Client`` instance using the full set of options
  that applies to it. For example, if the original client had an auth source<commit_msg>RUBY-2293 Document retrieving auth source from TXT records with SRV URIs (#2043)<commit_after>**************
Authentication
**************

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

MongoDB supports a variety of
:manual:`authentication mechanisms </core/authentication/>`.

For more information about configuring your MongoDB server for each of
these authentication mechanisms see MongoDB's
:manual:`online documentation </tutorial/enable-authentication>`.

For more information about users and the Ruby driver's helpers for
user management, see the :ref:`User Management tutorial<user-management>`.


Providing credentials
=====================

If authentication is enabled, provide credentials when creating a new
client:

.. code-block:: ruby

  client = Mongo::Client.new([ '127.0.0.1:27017' ],
                             user: 'test',
                             password: '<PASSWORD>',
                             database: 'mydb' )

  # If using a URI:
  client = Mongo::Client.new("mongodb://test:123@127.0.0.1:27017/mydb")

Authentication credentials can be changed on a client instance to obtain
a new client using the ``Client#with`` method:

.. code-block:: ruby

  authenticated_client = client.with( user: 'another-user',
                                      password: '<PASSWORD>' )

It is also possible to change the client's database and credentials in
one step:

.. code-block:: ruby

  authenticated_music_client = client.with( database: 'music',
                                            user:'test',
                                            password:'<PASSWORD>' )


.. _auth-source:

Auth Source
===========

A user's auth source is the database where that user's authentication
credentials are stored.

The user's auth source may be specified whenever the credentials are specified:

.. code-block:: ruby

  client = Mongo::Client.new([ '127.0.0.1:27017' ],
                             database: 'mydb',
                             user: 'test',
                             password: '<PASSWORD>',
                             auth_source: 'admin' )

  # If using a URI:
  client = Mongo::Client.new("mongodb://test:123@127.0.0.1:27017/mydb?authSource=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`` database is the default
database and hence 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, the ``$external`` database is used as the
auth source. For the ``AWS``, ``GSSAPI`` and ``MONGODB_X509`` mechanisms, the
auth source is always ``$external``.

When a client is constructed using an SRV URI, the driver will look for URI
options in a TXT DNS record that corresponds to the SRV record. Thus, for
example, MongoDB Atlas generally uses the ``admin`` database as its auth
source, but this is not specified in SRV URIs because the database is given
as a URI option on the TXT records.

Note that when using SRV URIs, the SRV query and the TXT query are performed
separately. On systems where DNS resolution is not 100% reliable, the
failure to look up TXT records can cause authentication errors, as the driver
may end up using an incorrect auth source. If reliable DNS resolution cannot
be guaranteed, the auth source can be specified explicitly in SRV URIs as
a URI option:

.. code-block:: ruby

  Mongo::Client.new("mongodb+srv://username:myRealPassword@cluster0.mongodb.net/test?w=majority&authSource=admin")

.. note::

  When changing the database using the ``with`` method, the auth source is
  determined in the new ``Client`` instance using the full set of options
  that applies to it. For example, if the original client had an auth source
{'fraction_non_alphanumeric': 0.10568772217664753, 'fraction_numerical': 0.017500683620453924, 'mean_word_length': 3.0369757174392937, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 17, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 9, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 10, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6951177', 'n_tokens_mistral': 2018, 'n_tokens_neox': 1861, 'n_words': 820}