DOCS: Document Kerberos

source/core/kerberos.txt

@@ -0,0 +1,167 @@
+=======================
+Kerberos Authentication
+=======================
+
+.. default-domain:: mongodb
+
+.. versionadded:: 2.4
+
+.. contents::
+   :backlinks: none
+   :local:
+
+Overview
+--------
+
+MongoDB Enterprise supports Kerberos authentication for the
+:program:`mongo` shell and other clients. 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`.
+
+See also :doc:`/tutorial/troubleshoot-kerberos`.
+
+Kerberos Components
+-------------------
+
+Users
+~~~~~
+
+To authenticate clients using Kerberos, you must first :ref:`create
+users <kerberos-create-users>` and grant appropriate privileges
+in the :data:`system.users <admin.system.users>` collection. See
+:ref:`localhost authentication exception <localhost-exception>` and
+:doc:`/tutorial/add-user-to-database` and :doc:`/core/access-control`
+for information on how to create users.
+
+.. _keytab-files:
+
+Linux Keytab Files
+~~~~~~~~~~~~~~~~~~
+
+Linux systems store Kerberos authentication keys in keytab files. Each
+Kerberized :program:`mongod` and :program:`mongos` instance
+running on Linux must have its own keytab file that contains valid
+authentication keys. To keep keytab files secure, use file permissions
+that restrict access to only the user that runs the :program:`mongod`
+or :program:`mongos` process.
+
+Windows Active Directory
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Kerberos is an intrinsic part of the Windows operating system and
+requires no setup. Kerberos authentication happens transparently at
+login time.
+
+.. tip::
+
+   Active Directory can export a keytab file for use in Linux. See
+   `Ktpass <http://technet.microsoft.com/en-us/library/cc753771.aspx>`_
+   for more information.
+
+Service Principal
+~~~~~~~~~~~~~~~~~
+
+Use ``mongodb/<hostname>`` as the Kerberos service principal for
+each :program:`mongod` and :program:`mongos` instance in a MongoDB
+deployment. If this differs from the name in the keytab file, use
+the :parameter:`saslHostName` parameter to give :program:`mongod`
+and :program:`mongos` the correct service principal name.
+
+By default, Kerberos attempts to identify hosts using the
+``/etc/kerb5.conf`` file before using DNS to resolve hosts.
+
+Linux Initialization
+~~~~~~~~~~~~~~~~~~~~
+
+All MongoDB clients, as well as :program:`mongod` and
+:program:`mongos`, must use Kerberos's ``kinit`` program to initialize
+and authenticate a Kerberos session.
+
+Windows Initialization
+~~~~~~~~~~~~~~~~~~~~~~
+
+mongod and mongos
+`````````````````
+
+Use ``setspn.exe`` to assign the service principal name (SPN) to the
+user. For example, assign the ``mongodb`` SPN to the ``mongotest``
+user on the ``test.mongo.com`` host:
+
+.. code-block:: sh
+
+   setspn.exe -A mongodb/test.mongo.com mongotest
+
+The Shell and Tools When Not Authenticated
+``````````````````````````````````````````
+
+Use `Ksetup <http://technet.microsoft.com/en-us/library/hh240190.aspx>`_
+to configure Windows to authenticate a host.
+
+The Shell and Tools When Authenticated
+``````````````````````````````````````
+
+After user login, MongoDB automatically authenticates using that user's
+credentials.
+
+.. tip::
+
+   Even when already authenticated, you can use `Ksetup
+   <http://technet.microsoft.com/en-us/library/hh240190.aspx>`_
+   to authenticate to a different Kerberos domain.
+
+Operational Considerations
+--------------------------
+
+The HTTP Console
+~~~~~~~~~~~~~~~~
+
+The MongoDB :ecosystem:`HTTP Console
+</tools/http-interface/#http-console>` interface does not support
+Kerberos authentication.
+
+DNS
+~~~
+
+Each host that runs a :program:`mongod` or :program:`mongos` instance
+must have both ``A`` and ``PTR`` DNS records to provide forward and
+reverse lookup.
+
+Without ``A`` and ``PTR`` DNS records, the host cannot resolve the components of
+the Kerberos domain or the Key Distribution Center (KDC).
+
+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 other hosts in 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Kerberos authentication (``GSSAPI``) can work alongside
+MongoDB's traditional challenge/response authentication
+mechanism (``MONGODB-CR``) for testing and development. See
+:doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` and
+:doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication`
+for more information.
+

source/includes/steps-control-access-to-mongodb-windows-with-kerberos-authentication.yaml

@@ -0,0 +1,113 @@
+stepnum: 1
+ref: start-mongod-exe-without-kerberos-support
+title: Create a Kerberos User Principal
+action:
+   - pre: 'Start :program:`mongod.exe` without Kerberos support:'
+     language: sh
+     code: mongod.exe
+   - pre: |
+        To give a new Kerberos user ``[email protected]`` read-only access
+        to the ``records`` database, use the :method:`db.addUser()` method
+        in the :program:`mongo.exe` shell, as follows:
+     language: javascript
+     code: |
+        use $external
+        db.runCommand({ createUser: "[email protected]",
+           pwd: "<cleartext password>",
+           roles: [
+              { role: "read", db: "records" }
+           ],
+           writeConcern: { <write concern> }
+        })
+post: |
+   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:: :dbcommand:`db.updateuser`,
+      :doc:`/reference/system-users-collection/`, and
+      :doc:`/reference/system-defined-roles`.
+---
+stepnum: 2
+ref: remove-user-privileges
+title: Remove User Privileges
+pre: |
+  To remove Kerberos privileges from a user, or to remove
+  the user entirely, use the MongoDB :doc:`user management
+  </reference/method/js-user-management>` methods.
+
+  .. seealso:: :doc:`/reference/privilege-documents` and
+     :doc:`/reference/user-privileges`.
+---
+stepnum: 3
+ref: start-mongod-exe-with-kerberos-support
+title: Start ``mongod.exe`` with Kerberos Support
+pre: |
+   After creating a service principal, the service principal user may start
+   :program:`mongod.exe` with the ``authenticationMechanisms=GSSAPI``
+   setting to initialize Kerberos support:
+action:
+  language: sh
+  code: |
+     mongod.exe --auth --setParameter authenticationMechanisms=GSSAPI --keyFile C:\<path>\mongod.keyfile
+post: |
+   Or :ref:`use x.509 member authentication
+   <x509-internal-authentication>` instead of authenticating with a keyfile.
+
+   If you encounter problems when trying to start
+   :program:`mongod.exe`, see the :ref:`troubleshooting section
+   <kerberos-troubleshooting>`.
+---
+stepnum: 4
+ref: start-mongos-exe-with-kerberos-support
+title: Start ``mongos.exe`` with Kerberos Support
+pre: |
+   Once the user obtains appropriate privileges, the user may start
+   :program:`mongos.exe` with the ``authenticationMechanisms=GSSAPI``
+   setting to initialize Kerberos support:
+action:
+  language: sh
+  code: |
+     mongos.exe --auth --setParameter authenticationMechanisms=GSSAPI --keyFile C:\<path>\mongod.keyfile
+post: |
+   Or :ref:`use x.509 member authentication
+   <x509-internal-authentication>` instead of authenticating with a keyfile.
+
+   If you encounter problems when trying to start :program:`mongos.exe`,
+   see the :ref:`troubleshooting section <kerberos-troubleshooting>`.
+---
+stepnum: 5
+ref: authenticate-mongos-exe-from-command-line
+title: Authenticate a ``mongo.exe`` Shell from the Command Line
+pre: |
+   To authenticate the :program:`mongo.exe` program to the Kerberos principal
+   name ``[email protected]``, use the following command:
+action:
+  language: sh
+  code: |
+     mongo.exe --authenticationMechanism=GSSAPI --authenticationDatabase='$external' --username [email protected]
+post: |
+   .. note::
+
+    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.
+---
+stepnum: 6
+ref: authenticate-a-user-within-mongo-shell
+title: Authenticate a User within a Running ``mongo.exe`` Shell
+pre: |
+   From a running :program:`mongo.exe` shell, use the :method:`db.auth()`
+   method to authenticate against the special ``$external`` database:
+action:
+  language: javascript
+  code: |
+     use $external
+     db.auth( { mechanism: "GSSAPI", user: "[email protected]" } )
+post: |
+  In the above example, if you are not joined to the ``EXAMPLE.NET``
+  domain, use ``ksetup`` with your Kerberos credentials to map
+  ``EXAMPLE.NET`` Kerberos Key Distribution Center (KDC) before
+  running the :dbcommand:`db.auth`.
+...