DOCS: Document Kerberos

source/core/kerberos.txt

@@ -0,0 +1,182 @@
+=======================
+Kerberos Authentication
+=======================
+
+.. default-domain:: mongodb
+
+.. versionadded:: 2.4
+
+.. contents::
+   :backlinks: none
+   :local:
+
+Overview
+--------
+
+MongoDB Enterprise supports authenticating clients, including the
+:program:`mongo` shell, using Kerberos. Kerberos is an industry
+standard authentication protocol for large client/server systems.
+
+To enable kerberos authentication on
+:program:`mongod` and :program:`mongos`, see
+:doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication`.
+and
+:doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication`
+
+To troubleshoot Kerberos on :program:`mongod` or :program:`mongos`,
+please see :doc:`/tutorial/troubleshoot-kerberos` for more information.
+
+Kerberos Components
+-------------------
+
+Users
+~~~~~
+
+You must :ref:`create users <kerberos-create-users>` and grant appropriate
+privileges in the :data:`system.users <admin.system.users>` collection before
+MongoDB will authenticate using Kerberos.
+
+To add users on a running :program:`mongod` instance, use the
+:ref:`localhost authentication exception <localhost-exception>`. See
+the :ref:`kerberos-create-users` section and the
+:doc:`/reference/user-privileges` document for more information.
+
+Keytab Files
+~~~~~~~~~~~~
+
+Under Linux, MongoDB's Kerberos support allows clients to authenticate
+using authentication keys stored in keytab files.
+
+Each :program:`mongod` and :program:`mongos` instance that uses
+kerberos authentication under Linux must have a keytab file containing
+valid authentication keys.
+
+.. warning::
+
+   Only transmit keytab files securely. Keytab file permissions should
+   restrict access to only the user that runs the :program:`mongod`
+   or :program:`mongos` process.
+
+Active Directory
+~~~~~~~~~~~~~~~~
+
+Under Windows, Active Directory uses Kerberos at the back-end. Kerberos
+authentication under Windows happens transparently at login.
+
+.. tip::
+
+   Active Directory can export a keytab file
+   for use in Linux, for example using `Ktpass
+   <http://technet.microsoft.com/en-us/library/cc753771.aspx>`_.
+
+Service Principal
+~~~~~~~~~~~~~~~~~
+
+Configure a Kerberos service principal for each :program:`mongod`
+and :program:`mongos` instance in your MongoDB deployment.
+
+The service principal should be ``mongodb/<hostname>``. Always ensure
+that the service principle matches the name in the keytab file, or
+use the :parameter:`saslHostName` to pass MongoDB the correct hostname.
+
+Initialize a Kerberos Session Under Linux
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Under Linux, Kerberos's ``kinit`` program initializes and authenticates
+a Kerberos session. All MongoDB clients, including :program:`mongod`,
+must use ``kinit``.
+
+Initialize a Kerberos Session Under Windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+mongod and mongos
+`````````````````
+
+Under Windows, to initialize a running :program:`mongod` or
+:program:`mongos` with the process owner's Kerberos credentials,
+you must assign the service principle name (SPN) to the user with the
+``setspn.exe`` program, using the following form:
+
+.. code-block:: sh
+
+   setspn.exe -A <serviceName>/<fqdn> <credentials>
+
+.. example::
+
+   Given a ``mongotest`` user on host ``test.mongo.com``, from a
+   computer joined to the ``MONGO.COM`` domain:
+
+   .. code-block:: sh
+
+      setspn.exe -A mongodb/test.mongo.com mongotest
+
+The Shell and Tools When Not Joined to Kerberos Domain
+``````````````````````````````````````````````````````
+
+Use `Ksetup <http://technet.microsoft.com/en-us/library/hh240190.aspx>`_
+to configure Windows to allow the host to resolve the Kerberos domain.
+
+The Shell and Tools When Joined to Kerberos Domain
+``````````````````````````````````````````````````
+
+When already joined to a Kerberos domain, :program:`mongo` and the
+MongoDB tools automatically authenticate using the credentials of
+the user running MongoDB.
+
+.. tip::
+
+   Even when joined to a Kerberos domain, you can use `Ksetup
+   <http://technet.microsoft.com/en-us/library/hh240190.aspx>`_
+   to authenticate to a different domain.
+
+Operational Considerations
+--------------------------
+
+The HTTP Console
+~~~~~~~~~~~~~~~~
+
+The MongoDB :ecosystem:`HTTP Console
+</tools/http-interface/#http-console>` interface does not support
+Kerberos authentication.
+
+DNS
+~~~
+
+To resolve the components of the Kerberos infrastructure, and to allow
+the Kerberos Key Distribution Center (KDC) to resolve the hosts in
+your MongoDB deployment, each system that runs a :program:`mongod`
+or :program:`mongos` instance must have both ``A`` and ``PTR`` DNS
+records (forward and reverse lookup).
+
+By default, Kerberos attempts to identify hosts using the
+``/etc/kerb5.conf`` file before using DNS to resolve hosts.
+
+System Time Synchronization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To successfully authenticate, the system time for each
+:program:`mongod` and :program:`mongos` instance *must* be within 5
+minutes of the system time of the Kerberos infrastructure.
+
+Kerberized MongoDB Environments
+-------------------------------
+
+Driver Support
+~~~~~~~~~~~~~~
+
+The following MongoDB drivers support Kerberos authentication:
+
+- :ecosystem:`Java </tutorial/authenticate-with-java-driver/>`
+- :ecosystem:`C# </tutorial/authenticate-with-csharp-driver/>`
+- :ecosystem:`C++ </tutorial/authenticate-with-cpp-driver/>`
+- `Python <http://api.mongodb.org/python/current/examples/authentication.html>`_
+
+Traditional MongoDB Authentication Mechanism
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Kerberos (i.e. ``GSSAPI``) authentication mechanism may be used
+alongside the traditional MongoDB challenge/response authentication
+mechanism (i.e. ``MONGODB-CR``) for testing and development. See
+:doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication`
+for more information.
+

source/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication.txt

@@ -0,0 +1,150 @@
+======================================================
+Deploy MongoDB on Windows with Kerberos Authentication
+======================================================
+
+.. default-domain:: mongodb
+
+.. versionadded:: 2.5.3
+
+.. contents::
+   :backlinks: none
+   :local:
+
+Overview
+--------
+
+MongoDB Enterprise supports authentication using a Kerberos service.
+Kerberos is an industry standard authentication protocol for large
+client/server system. With Kerberos MongoDB and application ecosystems
+can take advantage of existing authentication infrastructure and
+processes.
+
+.. see-also:: :doc:`/core/kerberos`
+
+If you encounter problems when trying to start :program:`mongod.exe`
+or :program:`mongos.exe`, see the :ref:`troubleshooting section
+<kerberos-troubleshooting>`.
+
+Procedures
+----------
+
+.. _kerberos-create-users:
+
+Grant User Privileges
+~~~~~~~~~~~~~~~~~~~~~
+
+.. versionchanged:: 2.5.4
+
+To give the Kerberos user principal
+``[email protected]`` read-only access to the
+``records`` database, use the :method:`db.addUser()` method in the
+:program:`mongo.exe` shell, as follows:
+
+.. code-block:: javascript
+
+   use $external
+   db.addUser({
+      user: "[email protected]",
+      roles: [
+         { role: "read", db: "records" }
+      ]
+   })
+
+The :data:`~admin.system.users.userSource` ``$external`` reference
+allows :program:`mongod.exe` to consult an external source (i.e. Kerberos)
+to authenticate this user.
+
+.. seealso:: :doc:`/reference/privilege-documents` and
+   :doc:`/reference/user-privileges`.
+
+Remove User Privileges
+~~~~~~~~~~~~~~~~~~~~~~
+
+Use the :dbcommand:`dropUser()` command to remove access from a user.
+
+To modify a user document, use :doc:`update </core/write-operations>`
+operations on documents in the :data:`system.users
+<admin.system.users>` collection.
+
+.. seealso:: :doc:`/reference/privilege-documents` and
+   :doc:`/reference/user-privileges`.
+
+Start ``mongod.exe`` with Kerberos Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once the user obtains a service principal name, the user may start
+:program:`mongod.exe` with the ``authenticationMechanisms=GSSAPI``
+setting to initialize Kerberos support:
+
+.. code-block:: sh
+
+   mongod.exe --auth --setParameter authenticationMechanisms=GSSAPI --keyFile C:\<path>\mongod.keyfile
+
+Start ``mongos.exe`` with Kerberos Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once the user obtains a service principal name, the user may start
+:program:`mongos.exe` with the ``authenticationMechanisms=GSSAPI``
+setting to initialize Kerberos support:
+
+.. code-block:: sh
+
+   mongos.exe --auth --setParameter authenticationMechanisms=GSSAPI --keyFile C:\<path>\mongod.keyfile
+
+Authenticate a ``mongo.exe`` shell from the command Line
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To authenticate the :program:`mongo.exe` program to the Kerberos principal
+name ``[email protected]``, use the following command:
+
+.. code-block:: sh
+
+   mongo.exe --authenticationMechanism=GSSAPI
+         --authenticationDatabase='$external' \
+         --username [email protected]
+
+.. note::
+
+   In the above example, if you are not joined to the EXAMPLE.NET
+   domain, use ksetup to map EXAMPLE.NET Kerberos Key Distribution
+   Center (KDC) before running the command. In this case, Kerberos
+   authentication also requires a password.
+
+Authenticate a running ``mongo.exe`` Shell
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+From a running :program:`mongo.exe` shell, and use the :method:`db.auth()`
+method to authenticate against the special ``$external`` database:
+
+.. code-block:: javascript
+
+   use $external
+   db.auth( { mechanism: "GSSAPI", user: "[email protected]" } )
+
+.. note::
+
+   In the above example, if you are not joined to the EXAMPLE.NET
+   domain, use ksetup to map EXAMPLE.NET Kerberos Key Distribution
+   Center (KDC) before running the command. In this case, Kerberos
+   authentication also requires a password.
+
+Enable the Traditional MongoDB Authentication Mechanism
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For testing and development purposes you can enable both the Kerberos
+(i.e. ``GSSAPI``) authentication mechanism in combination with the
+traditional MongoDB challenge/response authentication mechanism
+(i.e. ``MONGODB-CR``), using the following :setting:`setParameter`
+run-time option:
+
+.. code-block:: sh
+
+   mongod.exe --setParameter authenticationMechanisms=GSSAPI,MONGODB-CR
+
+.. warning::
+
+   All :setting:`keyFile` *internal* authentication between members of
+   a :term:`replica set` or :term:`sharded cluster` still uses the
+   ``MONGODB-CR`` authentication mechanism, even if ``MONGODB-CR`` is
+   not enabled. All client authentication will still use Kerberos.
+