From 7a177a0a3c11d6f15d4ba443838d8ede2a9e3db2 Mon Sep 17 00:00:00 2001 From: ravind Date: Tue, 22 Nov 2016 17:25:52 -0500 Subject: [PATCH] DOCS-9080: mongoldap documentation --- source/includes/options-mongoldap.yaml | 113 +++++++++++++++ source/reference/configuration-options.txt | 2 + source/reference/program.txt | 4 + source/reference/program/mongoldap.txt | 157 +++++++++++++++++++++ 4 files changed, 276 insertions(+) create mode 100644 source/includes/options-mongoldap.yaml create mode 100644 source/reference/program/mongoldap.txt diff --git a/source/includes/options-mongoldap.yaml b/source/includes/options-mongoldap.yaml new file mode 100644 index 00000000000..ae054a14cae --- /dev/null +++ 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: +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: +directive: option +description: | + + Username for {{program}} to use when attempting LDAP authentication or + authorization. + +optional: false +--- +program: mongoldap +name: password +args: +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 index 101eaf33872..44cfe1bf9f2 100644 --- 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 index 3a667057279..4acde047cf3 100644 --- a/source/reference/program.txt +++ b/source/reference/program.txt @@ -94,6 +94,9 @@ 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 @@ -101,6 +104,7 @@ later time. /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 new file mode 100644 index 00000000000..1f545653ae5 --- /dev/null +++ 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 ` 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 +`, :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 +` 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 +`, 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: "mongodbadmin@dba.example.com" + 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 --username "bob@dba.example.com" --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