:orphan:

==========================================
Authenticate to MongoDB with the C# Driver
==========================================

This page is a brief overview of authenticating to a MongoDB cluster
with the MongoDB C# Driver using version 1.8 and above.

Internal Authentication
-----------------------

Internal authentication refers to accounts stored inside MongoDB.
Currently, the only way to authenticate against internal accounts
is to use the MongoDB Challenge Response mechanism, or ``MONGODB-CR``.
This is the default mechanism.  To authenticate as the user "user1"
with a password of "password1", defined in the "test" database:

.. code-block:: csharp

    var credential = MongoCredential.CreateMongoCRCredential("test", "user1", "password1");

    var settings = new MongoClientSettings
    {
        Credentials = new[] { credential }
    };

    var mongoClient = new MongoClient(settings);

Alternatively, when you only need a single user, it is possible to
specify this in the connection string.

.. code-block:: csharp

    var connectionString = "mongodb://user1:password1@localhost/test";

    var mongoClient = new MongoClient(connectionString);

.. note::

   If you do not specify a database in the the connection string, the
   default database is the "admin" database.

In some cases you may need to authenticate as multiple users in
different databases. For example, imagine a map/reduce job that reads
from the database "first" and writes the results to the database
"second".  You may need to authenticate one user defined in the
"first" database and another in the "second":

.. code-block:: csharp

   var credentialFirst = MongoCredential.CreateMongoCRCredential("first", "user1", "password1");
   var credentialSecond = MongoCredential.CreateMongoCRCredential("second", "user2", "password2");

   var settings = new MongoClientSettings
   {
        Credentials = new[] { credentialFirst, credentialSecond }
   };

   var mongoClient = new MongoClient(settings);

.. note::

   As of the 2.4 MongoDB release, this is no longer necessary, since you
   are able to define a user in one database and delegate privileges
   for that user in another database.

External Authentication
-----------------------

External authentication refers to credentials validated outside of MongoDB.
The external authentication provider currently used is Kerberos.
To authenticate to a MongoDB cluster using Kerberos, you must specify
the GSSAPI mechanism and a user name. On Windows, it is also possible
to provide the password.

Fundamentally, the process for connecting with Kerberos is the same
for Windows and Linux systems; however, Linux systems require the use
of ``kinit`` to acquire the security credentials whereas Windows
systems perform this action transparently using SSPI based on the account
running the current process when a password is not used.

The below examples work on both Windows and Linux systems.

.. code-block:: csharp

   var connectionString = "mongodb://user%40REALM.COM@localhost/?authMechanism=GSSAPI";

   var client = new MongoClient(connectionString);

.. note::

   ``%40`` is the url encoded representation of the '@' character.

Alternatively, you can specify the authentication mechanism in the
code, as in both of the following:

.. code-block:: csharp

   var credential = MongoCredential.CreateGssapiCredential("user@REALM.COM");

   var settings = new MongoClientSettings
   {
       Credentials = new[] { credential }
   };

   var mongoClient = new MongoClient(settings);

Linux Systems
~~~~~~~~~~~~~

Linux does not integrate Kerberos authentication in the operating
system (unlike Windows) and requires the use of an external library.
The MongoDB server and the .NET driver on Linux use the ``libgsasl``
to manage authentication.

Mono, the open source platform used to run the .NET driver on Linux,
provides a way to map the hard-coded names of native libraries to
their actual names, which can be different based on your
distribution. Consider the `documentation from the Mono project
<http://www.mono-project.com/Config_DllMap>`_ for this process.

For the .NET driver, you must map the ``libgsasl-7.dll``
library.  An example configuration for Ubuntu looks like this:

.. code-block:: xml

   <configuration>
     <dllmap dll="libgsasl-7.dll" target="libgsasl.so.7" />
   </configuration>

Name this file ``MongoDB.Driver.dll.config`` and save it in the same
directory as the ``MongoDB.Driver.dll`` assembly. After mapping this
library, always run ``kinit`` before or during your application
startup process.
