mongodb · ravindk89 · Nov 22, 2016
diff --git a/source/includes/options-mongoldap.yaml b/source/includes/options-mongoldap.yaml
@@ -0,0 +1,113 @@
+program: mongoldap
+name: ldapServers
+inherit:
+  name: ldapServers
+  program: mongod
+  file: options-mongod.yaml
+---
+program: mongoldap
+name: ldapQueryUser
+inherit:
+  name: ldapQueryUser
+  program: mongod
+  file: options-mongod.yaml
+---
+program: mongoldap
+name: ldapQueryPassword
+inherit:
+  name: ldapQueryPassword
+  program: mongod
+  file: options-mongod.yaml
+---
+program: mongoldap
+name: ldapBindWithOSDefaults
+inherit:
+  name: ldapBindWithOSDefaults
+  program: mongod
+  file: options-mongod.yaml
+---
+program: mongoldap
+name: ldapBindMethod
+inherit:
+  name: ldapBindMethod
+  program: mongod
+  file: options-mongod.yaml
+---
+program: mongoldap
+name: ldapBindSASLMechanisms
+inherit:
+  name: ldapBindSASLMechanisms
+  program: mongod
+  file: options-mongod.yaml
+---
+program: mongoldap
+name: ldapTransportSecurity
+inherit:
+  name: ldapTransportSecurity
+  program: mongod
+  file: options-mongod.yaml
+---
+program: mongoldap
+name: ldapTimeoutMS
+inherit:
+  name: ldapTimeoutMS
+  program: mongod
+  file: options-mongod.yaml
+---
+program: mongoldap
+name: ldapUserToDNMapping
+inherit:
+  name: ldapUserToDNMapping
+  program: mongod
+  file: options-mongod.yaml
+---
+program: mongoldap
+name: ldapAuthzQueryTemplate
+inherit:
+  name: ldapAuthzQueryTemplate
+  program: mongod
+  file: options-mongod.yaml
+---
+program: mongoldap
+name: config
+aliases: -f
+args: <filename>
+directive: option
+description: |
+  Specifies a configuration file for runtime configuration options. 
+  The options are equivalent to the command-line
+  configuration options. See :doc:`/reference/configuration-options` for
+  more information.
+
+  {{program}} uses any configuration options related to :ref:`security-ldap`
+  or :ref:`security-ldap-external` for testing LDAP authentication or
+  authorization.
+
+  Requires specifying :option:`--user`. May accept :option:`--password` for
+  testing LDAP authentication.
+
+  Ensure the configuration file uses ASCII encoding. The {{program}}
+  instance does not support configuration files with non-ASCII encoding,
+  including UTF-8.
+optional: false
+---
+program: mongoldap
+name: user
+args: <string>
+directive: option
+description: |
+
+  Username for {{program}} to use when attempting LDAP authentication or
+  authorization. 
+
+optional: false
+---
+program: mongoldap
+name: password
+args: <string>
+directive: option
+description: |
+
+  Password of the ``--user`` for {{program}} to use when attempting LDAP
+  authentication. Not required for LDAP authorization.
+...
diff --git a/source/reference/configuration-options.txt b/source/reference/configuration-options.txt
@@ -450,6 +450,8 @@ Key Management Configuration Options
 
 .. include:: /includes/option/setting-conf-security.sasl.saslauthdSocketPath.rst
 
+.. _security.ldap.options:
+
 ``security.ldap`` Options
 `````````````````````````
 

diff --git a/source/reference/program.txt b/source/reference/program.txt
@@ -94,13 +94,17 @@ that you can use to inspect and record commands sent to a MongoDB
 instance, and then replay those commands back onto another host at a
 later time.
 
+MongoDB 3.4 provides :program:`mongoldap` for testing native operating system
+LDAP configuration options against a running LDAP server or set of servers.
+
 .. toctree::
    :maxdepth: 1
 
    /reference/program/mongostat
    /reference/program/mongotop
    /reference/program/mongoperf
    /reference/program/mongoreplay
+   /reference/program/mongoldap
 
 GridFS
 ------

diff --git a/source/reference/program/mongoldap.txt b/source/reference/program/mongoldap.txt
@@ -0,0 +1,157 @@
+.. _mongoldap:
+
+=============
+``mongoldap``
+=============
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. versionadded:: 3.4 MongoDB Enterprise
+
+Synopsis
+--------
+
+MongoDB 3.4 provides :program:`mongoldap` for testing MongoDB's LDAP
+:ref:`configuration options <security.ldap.options>` against a running LDAP
+server or set of servers.
+
+To validate the LDAP options in the configuration file, set the
+:program:`mongoldap` :option:`--config` option to the configuration file's
+path.
+
+To test the LDAP configuration options, you must specify a :option:`--user`
+and ``--password``. :program:`mongoldap` simulates authentication to a
+MongoDB server running with the provided configuration options and credentials.
+
+:program:`mongoldap` returns a report that includes the success or failure of
+any step in the LDAP authentication or authorization procedure. Error messages
+include information on specific errors encountered and potential advice for
+resolving the error.
+
+When configuring options related to :ref:`LDAP authorization
+<security-ldap-external>`, :program:`mongoldap` executes an LDAP query
+constructed using the provided configuration options and username, and returns
+a list of roles on the ``admin`` database which the user is authorized for.
+
+You can use this information when configuring :ref:`LDAP authorization roles
+<security-ldap-external-roles>` for user access control. For example, use
+:program:`mongoldap` to ensure your configuration allows privileged users to
+gain the necessary roles to perform their expected tasks. Similarly, use
+:program:`mongoldap` to ensure your configuration disallows non-privileged
+users from gaining roles for accessing the MongoDB server, or performing
+unauthorized actions. 
+
+When configuring options related to :ref:`LDAP authentication
+<security-ldap>`, use :program:`mongoldap` to ensure that the authentication
+operation works as expected.
+
+This document provides a complete overview of all command line options for
+:program:`mongoldap`.
+
+Usage
+-----
+
+.. note::
+
+   A full description of LDAP or Active Directory is beyond the scope of
+   this documentation.
+
+Consider the following sample configuration file, designed to support
+LDAP authentication and authorization via Active Directory:
+
+.. code-block:: yaml
+
+   security:
+      authentication: "enabled"
+      ldap:
+         servers: "activedirectory.example.net"
+         bind:
+            queryUser: "[email protected]"
+            queryPassword: "secret123"
+         userToDNMapping:
+            '[
+               {
+                  match : "(.+)",
+                  ldapQuery: "DC=example,DC=com??sub?(userPrincipalName={0})"
+               }
+            ]'
+         authz:
+            queryTemplate: "DC=example,DC=com??sub?(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={USER}))"
+   setParameter:
+      authenticationMechanism: "PLAIN"
+
+You can use :program:`mongoldap` to validate the configuration file, which
+returns a report of the procedure. You must specify a username and password
+for :program:`mongoldap`.
+
+.. code-block:: shell
+
+   mongoldap --config <path-to-config> --username "[email protected]" --password "secret123" 
+
+If the provided credentials are valid, and the LDAP options in the
+configuration files are valid, the output might be as follows:
+
+.. code-block:: shell
+
+   Checking that an LDAP server has been specified...
+   [OK] LDAP server found
+
+   Connecting to LDAP server...
+   [OK] Connected to LDAP server
+
+   Parsing MongoDB to LDAP DN mappings..
+   [OK] MongoDB to LDAP DN mappings appear to be valid
+
+   Attempting to authenticate against the LDAP server...
+   [OK] Successful authentication performed
+
+   Checking if LDAP authorization has been enabled by configuration...
+   [OK] LDAP authorization enabled
+
+   Parsing LDAP query template..
+   [OK] LDAP query configuration template appears valid
+
+   Executing query against LDAP server...
+   [OK] Successfully acquired the following roles:
+   ...
+
+Options
+-------
+
+.. only:: (not man)
+
+   .. class:: hidden
+
+      .. binary:: mongod
+
+.. include:: /includes/option/option-mongoldap-config.rst
+
+.. include:: /includes/option/option-mongoldap-user.rst
+
+.. include:: /includes/option/option-mongoldap-password.rst
+
+.. include:: /includes/option/option-mongoldap-ldapServers.rst
+
+.. include:: /includes/option/option-mongoldap-ldapQueryUser.rst
+
+.. include:: /includes/option/option-mongoldap-ldapQueryPassword.rst
+
+.. include:: /includes/option/option-mongoldap-ldapBindWithOSDefaults.rst
+
+.. include:: /includes/option/option-mongoldap-ldapBindMethod.rst
+
+.. include:: /includes/option/option-mongoldap-ldapBindSASLMechanisms.rst
+
+.. include:: /includes/option/option-mongoldap-ldapTransportSecurity.rst
+
+.. include:: /includes/option/option-mongoldap-ldapTimeoutMS.rst
+
+.. include:: /includes/option/option-mongoldap-ldapUserToDNMapping.rst
+
+.. include:: /includes/option/option-mongoldap-ldapAuthzQueryTemplate.rst