From e5577b81aba9c268f90961fdb0ef2aee7294c669 Mon Sep 17 00:00:00 2001 From: Andrew Aldridge Date: Wed, 5 Oct 2016 12:29:55 -0400 Subject: [PATCH] DOCS-9077: LDAP landing page changes --- .../authentication-mechanisms-enterprise.txt | 44 +- source/core/security-ldap-external.txt | 469 ++++++++++++++++++ source/core/security-ldap.txt | 313 +++++++++++- source/reference/parameters.txt | 7 +- 4 files changed, 798 insertions(+), 35 deletions(-) create mode 100644 source/core/security-ldap-external.txt diff --git a/source/core/authentication-mechanisms-enterprise.txt b/source/core/authentication-mechanisms-enterprise.txt index 07f663e9fc5..c69a64fd18b 100644 --- a/source/core/authentication-mechanisms-enterprise.txt +++ b/source/core/authentication-mechanisms-enterprise.txt @@ -37,31 +37,55 @@ For more information on Kerberos and MongoDB, see: .. _security-auth-ldap: -LDAP Proxy Authority Authentication ------------------------------------ +LDAP Proxy Authentication +------------------------- -`MongoDB Enterprise (excluding Windows version) +`MongoDB Enterprise `_ supports proxy authentication through a Lightweight Directory Access Protocol (LDAP) service. -LDAP support for user authentication requires proper configuration of the -``saslauthd`` daemon process as well as the MongoDB server. +.. versionchanged:: 3.4 -For more information on LDAP and MongoDB, see + MongoDB 3.4 supports using operating system libraries instead of the + `saslauthd `_ + daemon, allowing MongoDB 3.4 servers running on Linux and Microsoft Windows + to connect to LDAP servers. Linux MongoDB deployments continue to support + ``saslauthd``. -- :doc:`/core/security-ldap`, +Previous versions of MongoDB support authentication against an LDAP server +using simple and SASL binding via ``saslauthd``. This restricted LDAP +authentication support to only Linux MongoDB deployments. -- :doc:`/tutorial/configure-ldap-sasl-openldap` and +See :doc:`/core/security-ldap` for more information. -- :doc:`/tutorial/configure-ldap-sasl-activedirectory`. +LDAP Authorization +~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 3.4 + +MongoDB Enterprise supports querying an LDAP server for the LDAP groups the +authenticated user is a member of. MongoDB maps the Distinguished Names (DN) +of each returned group to :ref:`roles ` on the ``admin`` database. +MongoDB authorizes the user based on the mapped roles and their associated +privileges. See :ref:`LDAP Authorization ` for more +information. + +.. seealso:: + + - :doc:`/core/security-ldap`, + + - :doc:`/tutorial/configure-ldap-sasl-openldap` and + + - :doc:`/tutorial/configure-ldap-sasl-activedirectory`. .. class:: hidden .. toctree:: - :titlesonly: + :titlesonly: /core/kerberos /core/security-ldap + /core/security-ldap-external diff --git a/source/core/security-ldap-external.txt b/source/core/security-ldap-external.txt new file mode 100644 index 00000000000..72e05bed66e --- /dev/null +++ b/source/core/security-ldap-external.txt @@ -0,0 +1,469 @@ +.. _security-ldap-external: +.. _ldap-authorization: + +================== +LDAP Authorization +================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 3.4 + + `MongoDB Enterprise + `_ supports + querying an LDAP server for the LDAP groups to which the authenticated user + belongs. MongoDB maps the distinguished names (DN) of each returned group + to :ref:`roles ` on the ``admin`` database. MongoDB authorizes the + user based on the mapped roles and their associated privileges. See + :ref:`LDAP Authorization ` for more information. + +The LDAP Authorization process is summarized below: + +#. A client connects to MongoDB and performs authentication with any + :ref:`authentication ` mechanism that + :ref:`supports external authentication + `. + +#. MongoDB binds to to the LDAP server specified with :setting:`security.ldap.servers` + using the credentials specified with :setting:`security.ldap.queryUser` and + :setting:`security.ldap.queryPassword`. + + MongoDB uses simple binding by default, but can use ``sasl`` binding + instead if configured in :setting:`security.ldap.bind.method` and + :setting:`security.ldap.bind.saslMechanisms`. + +#. MongoDB constructs an LDAP query using the + :setting:`security.ldap.authz.queryTemplate` and queries the LDAP server for + the authenticated user's group membership. + + MongoDB can use the :setting:`security.ldap.userToDNMapping` option to + transform the username for supporting the query template. + +#. The LDAP server evaluates the query and returns the list of + groups to which the authenticated user belongs. + +#. MongoDB authorizes the user to perform actions on the server by mapping + each returned group's Distinguished Name (DN) into a :ref:`role + ` on the ``admin`` database. If a returned group DN exactly + matches the name of an existing role on the ``admin`` database, MongoDB + grants the user the roles and privileges assigned to that role. See + :ref:`security-ldap-external-roles` for more information. + +#. The client can perform actions on the MongoDB server which require the roles + or privileges granted to the authenticated user. + +#. At an interval defined by :option:`--ldapUserCacheInvalidationInterval`, + MongoDB flushes the ``$external`` cache. Prior to executing + subsequent operations performed by externally authorized users, MongoDB + re-acquires their group membership from the LDAP server. + +Considerations +-------------- + +A full description of LDAP is beyond the scope of this documentation. This +page assumes prior knowledge of LDAP. + +This documentation only describes MongoDB LDAP authorization, and does not +replace other resources on LDAP. We encourage you to thoroughly familiarize +yourself with LDAP and its related subject matter before configuring LDAP +authentication. + +MongoDB can provide `professional services +`_ for optimal +configuration of LDAP authorization for your MongoDB deployment. + +.. _security-ldap-external-compatibility: + +Compatible Authentication Mechanism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following authentication mechanisms are compatible with MongoDB LDAP +authorization: + +- :ref:`security-ldap` +- :ref:`security-kerberos` +- :ref:`security-auth-x509` + +User Management +~~~~~~~~~~~~~~~ + +With LDAP authorization, user creation and management occurs on the LDAP +server. MongoDB requires creation of :ref:`roles ` on the ``admin`` +database, with the name of each role exactly matching a LDAP group +Distinguished Name (DN). This is in contrast to MongoDB managed authorization, +which requires creating users on the ``$external`` database. + +To manage roles on the MongoDB server, authenticate as a user whose group +membership corresponds to a ``admin`` database role with role administration +privileges, such as those provided by :authrole:`userAdmin`. Create or update +roles corresponding to LDAP group DNs such that users with membership in that +group receive the appropriate roles and privileges. + +For example, an LDAP group for database administrators might have a role with +administrative roles and privileges. An LDAP group for marketing or analytics +users may have a role with only have read privileges on certain databases. + +.. important:: + + When configuring a role for a corresponding LDAP Group, remember that *all* + users with membership in that group can receive the configured roles and + privileges. Consider applying the principle of least privilege when + configuring MongoDB roles, LDAP groups, or group membership. + +If no role with role administration privileges exists *AND* no +non-``$external`` user with these privileges exists, you effectively cannot +perform user management, as no new or existing roles can be altered to reflect +additions or changes to groups or group membership on the LDAP server. + +To remedy a scenario where you cannot manage roles on the MongoDB server, +perform the following procedure: + +#. Restart the MongoDB server without authentication and LDAP authorization + +#. Create a role on the ``admin`` database whose name corresponds to the + appropriate LDAP group Distinguished Name. When choosing a group DN, + consider which group is most appropriate for database administration. + +#. Restart the MongoDB server with authentication and LDAP authorization + +#. Authenticate as a user with membership in the group corresponding to the + created administrative role. + +Existing Users +~~~~~~~~~~~~~~ + +A MongoDB server using LDAP for authorization makes any existing users on the +``$external`` database inaccessible. If there are existing users in +``$external`` database, you must meet the following requirements for each user +on the ``$external`` database to ensure continued access: + +- User has a corresponding user object on the LDAP server + +- User object has membership in the appropriate LDAP groups + +- MongoDB has roles on the ``admin`` database named for the user's LDAP + groups, such that the granted roles and privileges are identical to those + granted to the non-``$external`` user. + +If you want to continue allowing access by users *not* on the ``$external`` +database, ensure the :parameter:`authenticationMechanisms` parameter +includes ``SCRAM-SHA-1``. Alternatively, apply the requirements listed +above for transitioning those users to LDAP authorization. + +Replica Sets +~~~~~~~~~~~~ + +For :term:`replica sets `, configure LDAP authorization on the +:term:`secondary` and :term:`arbiter` members first before configuring the +:term:`primary`. This also applies to :doc:`shard replica sets +`, or :ref:`config server replica sets `. +Configure one replica set member at a time to maintain a majority of members +for write availability. + +Sharded Clusters +~~~~~~~~~~~~~~~~ + +In :term:`sharded clusters `, you must configure LDAP +authorization on the :term:`config servers ` for cluster-level +users. You can optionally configure LDAP authorization on each +:term:`shard` for shard-local users. + +Configuration +------------- + +You must configure the following settings to use LDAP Authorization: + +To use LDAP for authorization via operating system libraries, specify the +following settings as a part of your :program:`mongod` or :program:`mongos` +configuration file: + +.. list-table:: + :header-rows: 1 + :widths: 30 60 10 + + * - option + - description + - required + + * - :setting:`security.ldap.servers` + - Quote-enclosed comma-separated list of LDAP servers in ``host[:port]`` + format. + + - **YES** + + * - :setting:`security.ldap.authz.queryTemplate` + + - An `RFC4515 `_ and `RFC4516 + `_ LDAP formatted query URL + template executed by MongoDB to obtain the LDAP groups to + which the user belongs to. The query is relative to the host or hosts + specified in :setting:`~security.ldap.servers`. + + Use the ``{USER}`` special placeholder to substitute the authenticated + username, or the :setting:`transformed ` + username, into the LDAP query. + + Only :program:`mongod` supports this parameter. :program:`mongos` + defers to this setting as configured on its :term:`config servers + ` + + - **YES** + + * - :setting:`security.ldap.bind.queryUser` + + - The identity the MongoDB server binds as when connecting to and + executing operations and queries on an LDAP server. + + Use with :setting:`~security.ldap.bind.queryPassword`. + + The user specified must have the appropriate privileges to support the + LDAP queries generated from the configured + :setting:`~security.ldap.authz.queryTemplate`. + + - **YES** + + * - :setting:`security.ldap.bind.queryPassword` + + - The password used to bind to an LDAP server when using + :setting:`~security.ldap.bind.queryUser`. + + - **YES** + + * - :setting:`security.ldap.bind.method` + + - Used to specify the method the :program:`mongod` or :program:`mongos` + uses to authenticate, or bind, to the LDAP server. Specify ``sasl`` to + use one of the SASL protocols defined in + :setting:`security.ldap.bind.saslMechanisms`. + + Defaults to ``simple``. + + - **NO**, unless using ``sasl`` for binding to the LDAP server. + + * - :setting:`security.ldap.bind.saslMechanisms` + + - Used to specify the SASL mechanisms :program:`mongod` or + :program:`mongos` can use when authenticating or binding to the LDAP + server. MongoDB and the LDAP server must agree on at least one SASL + mechanism. + + Defaults to ``DIGEST-MD5``. + + - **NO**, unless setting :setting:`~security.ldap.bindMethod` to + ``sasl``, and you need different or additional SASL mechanisms. + + * - :setting:`security.ldap.bind.useOSDefaults` + + - Windows MongoDB deployments can use the operating system credentials in + place of :setting:`~security.ldap.queryUser` and + :setting:`~security.ldap.queryPassword` for authenticating or binding + as when connecting to the LDAP server. + + - **NO**, unless replacing :setting:`~security.ldap.queryUser` and + :setting:`~security.ldap.queryPassword`. + + * - :setting:`security.ldap.userToDNMapping` + + - Depending on your :setting:`~security.ldap.queryTemplate`, the + authenticated client username may require transformation to support the + the LDAP query URL. :setting:`~security.ldap.userToDNMapping` allows + MongoDB to transform incoming usernames. + + - **NO**, unless client usernames require transformation into LDAP DNs. + +LDAP Query Template +~~~~~~~~~~~~~~~~~~~ + +MongoDB uses the :setting:`security.ldap.authz.queryTemplate` to create an +`RFC4516 `_ formatted LDAP query URL. In +the template, use the ``{USER}`` placeholder to substitute the authenticated +username into the LDAP query URL. Design the query template to retrieve the +authenticated user's groups. If MongoDB transformed the username using +:setting:`~security.ldap.userToDNMapping`, MongoDB replaces the ``{USER}`` +token with the transformed username when constructing the LDAP query URL. + +.. example:: + + The following query template returns any groups listed in the + LDAP user object's ``memberOf`` attribute. This query assumes the ``memberOf`` + attribute exists - your specific LDAP deployment may use a different attribute + or methodology for tracking group membership. This query also assumes + the user authenticates using their full LDAP DN as their username. + + .. code-block:: shell + + "{USER}?memberOf?base" + +The LDAP query URL must conform to the format defined in `RFC4516 +`_: + +.. code-block:: text + + [ dn [ ? [attributes] [ ? [scope] [ ? [filter] [ ? [Extensions] ] ] ] ] ] + +Consider the definition of each component, as quoted from RFC4516: + + The ``dn`` is an LDAP Distinguished Name using the string format described + in `RFC4514 `_. It identifies the base + object of the LDAP search or the target of a non-search operation. + + The ``attributes`` construct is used to indicate which attributes should be + returned from the entry or entries. + + The ``scope`` construct is used to specify the scope of the search to perform + in the given LDAP server. The allowable scopes are "base" for a base object + search, "one" for a one-level search, or "sub" for a subtree search. + + The ``filter`` is used to specify the search filter to apply to entries + within the specified scope during the search. It has the format specified + in [RFC4515]. + + The ``extensions`` construct provides the LDAP URL with an extensibility + mechanism, allowing the capabilities of the URL to be extended in the + future. + +If the query includes an ``attribute``, MongoDB assumes the query retrieves a +the DNs which this entity is member of. + +If the query does not include an attribute, MongoDB assumes the query +retrieves all entities for which the user is member of. + +MongoDB currently ignores any extensions specified in the LDAP query. + +.. important:: + + A full description of RFC4516 or LDAP query URL construction is out of + scope for this documentation. + +Tutorials +--------- + +The following tutorials contain procedures for connecting to an LDAP server +via the Operating System LDAP libraries: + +- :doc:`/tutorial/authenticate-nativeldap-activedirectory` +- :doc:`/tutorial/kerberos-auth-activedirectory-authz` + +Connecting to a MongoDB server using LDAP Authorization +------------------------------------------------------- + +When using LDAP for authorization, users connecting via the :program:`mongo` +shell must: + +- set :option:`--authenticationDatabase` to ``$external``. + +- set :option:`authenticationMechanism` to the appropriate authentication + mechanism. + + If using :ref:`LDAP authentication `, set this to ``PLAIN``. + + If using :ref:`Kerberos authentication `, set this to + ``GSSAPI``. + + If using :ref:`x.509 `, set this to ``MONGODB-X.509``. + +- set :option:`--username` to a username that respects the + :setting:`security.ldap.authz.queryTemplate`, or any configured + :setting:`security.ldap.userToDNMapping` template. + +- set :option:`--password` to the appropriate password. + +Include the :option:`--host` and :option:`--port` of the MongoDB server, +along with any other options relevant to your deployment. + +For example, the following operation authenticates to a MongoDB server running +with LDAP authentication and authorization: + +.. code-block:: shell + + mongo --username alice@dba.example.com --password secret123 --authenticationDatabase "$external" --authenticationMechanism "PLAIN" --host "mongodb.example.com" --port 27017 + +.. _security-ldap-external-roles: + +MongoDB Roles for LDAP Authorization +------------------------------------ + +MongoDB maps each returned group distinguished name (DN) returned by +the LDAP :option:`query ` to a +:ref:`role ` on the ``admin`` database. + +If MongoDB acquires a group whose DN exactly matches the name of an existing +role, MongoDB grants the authenticated user roles and :ref:`privileges +` associated with that role. If MongoDB cannot map any of the +returned groups to a role, MongoDB grants no privileges to the user. + +.. note:: + + :ref:`LDAP ` and :ref:`kerberos ` + authentication normally require creating users in the ``$external`` + database. If you also use LDAP for authorization, you do *not* need to + create users in the ``$external`` database. You only need to create the + appropriate roles in the ``admin`` database. Users still authenticate + against the ``$external`` database. + +.. example:: + + A database has the following roles configured on the ``admin`` database: + + .. code-block:: javascript + + { + role: "CN=dba,CN=Users,DC=example,DC=com", + privileges: [], + roles: [ “dbAdminAnyDatabase”, “clusterAdmin” ] + } + { + role: "CN=analytics,CN=Users,DC=example,DC=com" + privileges: [], + roles: [ + { role : "read", db : "web_statistics" }, + { role : "read", db : "user_statistics" } + ] + } + + After authenticating a user ``alice@dba.example.com`` against the + ``$external`` database, the MongoDB server performs a query derived from + the configured :setting:`query template + ` to retrieve the groups which include + the authenticated user as a member. In this example, the MongoDB server + retrieves the following group DNs for the user: + + .. code-block:: text + + dn:CN=dba,CN=Users,dc=example,dc=com + dn:CN=admin,CN=Users,dc=example,dc=com + + MongoDB maps these group DNs to roles on the ``admin`` database. The first + group DN matches the first role, and MongoDB grants the authenticated user + its roles and privileges. The second group DN does not match to any role on + the server, so MongoDB grants no additional permissions. + + A new user ``bob@analytics.example.com`` authenticates against the + ``$external`` database. The MongoDB server repeats the query process, using + the provided username in the query template. In this example, the MongoDB + server retrieves the following group DNs for the user: + + .. code-block:: text + + dn:cn=analytics,CN=Users,dc=example,dc=com + + MongoDB maps these group DNs to roles on the ``admin`` database and grants + the authenticated user the roles and privileges of the second role. + + A new user ``workstation@guest.example.com`` authenticates against the + ``$external`` database. The MongoDB server repeats the query process, using + the provided username in the query template. In this example, the MongoDB + server retrieves the following group DNs for the user: + + .. code-block:: text + + dn:cn=guest,CN=Users,dc=example,dc=com + + MongoDB maps the group to a role on the ``admin`` database and, because no + matching roles exist, grants the user no additional permissions. diff --git a/source/core/security-ldap.txt b/source/core/security-ldap.txt index 3648252314c..910f8caaacd 100644 --- a/source/core/security-ldap.txt +++ b/source/core/security-ldap.txt @@ -1,6 +1,8 @@ -=================================== -LDAP Proxy Authority Authentication -=================================== +.. _security-ldap: + +========================= +LDAP Proxy Authentication +========================= .. default-domain:: mongodb @@ -12,18 +14,264 @@ LDAP Proxy Authority Authentication `MongoDB Enterprise `_ supports -proxy authentication through a Lightweight Directory Access Protocol +proxying authentication requests to a Lightweight Directory Access Protocol (LDAP) service. + +MongoDB 3.4 supports simple and SASL binding to LDAP servers via: + +- Operating system libraries + + .. versionadded:: 3.4 + + MongoDB 3.4 supports binding to an LDAP server via operating system + libraries. This allows Linux and Windows MongoDB 3.4 servers to use an + LDAP server for authentication. + +- ``saslauthd`` + + Linux MongoDB servers supports binding to an LDAP server via the + ``saslauthd`` daemon. + +Previous versions of MongoDB support LDAP authentication using ``saslauthd``. +This restricted LDAP authentication support to Linux MongoDB deployments only. + +Previous versions of Microsoft Windows MongoDB cannot connect to LDAP servers. +MongoDB 3.4 on Windows remains incompatible with ``saslauthd``. Considerations -------------- +A full description of LDAP is beyond the scope of this documentation. This +page assumes prior knowledge of LDAP. + +This documentation only describes MongoDB LDAP authentication, and does not +replace other resources on LDAP. We encourage you to thoroughly familiarize +yourself with LDAP and its related subject matter before configuring LDAP +authentication. + +MongoDB can provide `professional services +`_ for optimal +configuration of LDAP authentication for your MongoDB deployment. + +Managing LDAP Users on the MongoDB server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +User management requires managing users both on the LDAP server and the +MongoDB server. For each user authenticating via LDAP, MongoDB requires a user +on the ``$external`` database whose name exactly matches the authentication +username. Changes to a user on the LDAP server may require changes to the +corresponding MongoDB ``$external`` user. + +.. example:: + + A user authenticates as ``sam@dba.example.com``. The MongoDB server + binds to the LDAP server and authenticates the user, respecting any + :setting:`username transformations `. + On successful authentication, the MongoDB server then checks the + ``$external`` database for a user ``sam@dba.example.com`` and + grants the authenticated user the roles and privileges associated to + that user. + +To manage users on the MongoDB server, you must authenticate as an LDAP user +whose corresponding MongoDB ``$external`` user has user administrative +privileges on the ``$external`` database, such as those provided by +:authrole:`userAdmin`. + +.. important:: + + If no ``$external`` users have user administrative privileges on + ``$external`` database, you cannot perform user management for LDAP + authentication. This scenario may occur if you configure users prior to + enabling LDAP authentication, but do not create the appropriate user + administrators. + +Managing existing non-LDAP users +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If there are existing users not on the ``$external`` database, you must meet +the following requirements for each user to ensure continued access: + +- User has a corresponding user object on the LDAP server + +- User exists on the ``$external`` database with equivalent roles and + privileges + +If you want to continue allowing access by users *not* on the ``$external`` +database, you must configure :setting:`setParameter` +:parameter:`authenticationMechanisms` to include ``SCRAM-SHA-1``. Users +must then specify :option:`--authenticationMechanism` ``SCRAM-SHA-1`` when +authenticating. + +Deploying LDAP authentication on a replica set +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For :term:`replica sets `, configure LDAP authentication on +:term:`secondary` and :term:`arbiter` members first before configuring the +:term:`primary`. This also applies to :doc:`shard replica sets +`, or :ref:`config server replica sets `. +Configure one replica set member at a time to maintain a majority of members +for write availability. + +Deploying LDAP authentication on a sharded cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In :term:`sharded clusters `, you must configure LDAP +authentication on the :term:`config servers ` and each +:program:`mongos` for cluster-level users. You can optionally configure LDAP +authorization on each :term:`shard` for shard-local users. + +.. _security-ldap-connect-native: + +LDAP Authentication via the Operating System LDAP libraries +----------------------------------------------------------- + +.. versionadded:: 3.4 + +The LDAP authentication via OS libraries process is summarized below: + +#. A client authenticates to MongoDB, providing a user's credentials. + +#. If the username requires mapping to an LDAP DN prior to binding against the + LDAP server, MongoDB can apply transformations based on the configured + :setting:`security.ldap.userToDNMapping` setting. + +#. MongoDB binds to an LDAP server specified in + :setting:`security.ldap.servers` using the provided username or, if a + transformation was applied, the transformed username. + + MongoDB uses simple binding by default, but can also use ``sasl`` binding + if configured in :setting:`security.ldap.bind.method` and + :setting:`security.ldap.bind.saslMechanisms`. + + If a transformation requires querying the LDAP server, or if the LDAP + server disallows anonymous binds, MongoDB uses the username and password + specified to :setting:`security.ldap.bind.queryUser` and + :setting:`security.ldap.bind.queryPassword` to bind to the LDAP server + before attempting to authenticate the provided user credentials. + +#. The LDAP server returns the result of the bind attempt to MongoDB. On + success, MongoDB attempts to authorize the user. + +#. The MongoDB server attempts to map the username to a user on the + ``$external`` database, assigning the user any roles or privileges + associated to a matching user. If MongoDB cannot find a matching user, + authentication fails. + +#. The client can perform those actions for which MongoDB granted the + authenticated user roles or privileges. + +To use LDAP for authentication via operating system libraries, specify the +following settings as a part of your :program:`mongod` or :program:`mongos` +configuration file: + +.. list-table:: + :header-rows: 1 + :widths: 30 60 10 + + * - option + - description + - required + + * - :setting:`security.ldap.servers` + - Quote-enclosed comma-separated list of LDAP servers in ``host[:port]`` + format. + + - **YES** + + * - :setting:`security.ldap.bind.method` + + - Used to specify the method the :program:`mongod` or :program:`mongos` + uses to authenticate, or bind, to the LDAP server. Specify ``sasl`` to + use one of the SASL protocols defined in + :setting:`security.ldap.bind.saslMechanisms`. + + Defaults to ``simple``. + + - **NO**, unless using ``sasl`` for binding to the LDAP server. + + * - :setting:`security.ldap.bind.saslMechanisms` + + - Used to specify the SASL mechanisms :program:`mongod` or + :program:`mongos` can use when authenticating or binding to the LDAP + server. MongoDB and the LDAP server must agree on at least one SASL + mechanism. + + Defaults to ``DIGEST-MD5``. + + - **NO**, unless setting :setting:`~security.ldap.bind.method` to + ``sasl`` *and* you need different or additional SASL mechanisms. + + * - :setting:`security.ldap.bind.queryUser` + - The LDAP entity, identified by its distinguished name (DN) or SASL name, + with which the MongoDB server authenticates, or binds, when connecting + to an LDAP server. + + Use with :setting:`~security.ldap.bind.queryPassword`. + + The user specified must have the appropriate privileges to execute + queries on the LDAP server. + + - **NO**, unless specifying a query as part of a + :setting:`~security.ldap.userToDNMapping` transformation, or if the + LDAP server's security settings disallow anonymous binds. + + * - :setting:`security.ldap.bind.queryPassword` + + - The password used to authenticate to an LDAP server when using + :setting:`~security.ldap.bind.queryUser`. + + - **NO**, unless specifying :setting:`~security.ldap.queryUser` + + * - :setting:`security.ldap.bind.useOSDefaults` + + - Windows MongoDB deployments can use the operating system credentials in + place of :setting:`~security.ldap.queryUser` and + :setting:`~security.ldap.queryPassword` for authenticating or binding + as when connecting to the LDAP server. + + - **NO**, unless replacing :setting:`~security.ldap.bind.queryUser` and + :setting:`~security.ldap.bind.queryPassword`. + + * - :setting:`security.ldap.userToDNMapping` + + - Clients may authenticate using a username whose format is incompatible + with the format expected by the configured :setting:`bind method + <~security.ldap.bind.method>`. For example, ``simple`` binding may + require a full LDAP DN while the username used to authenticate to + MongoDB might be an e-mail address. + + :setting:`~security.ldap.userToDNMapping` allows MongoDB to transform + incoming usernames into a format compatible with your LDAP schema. + MongoDB supports transformations using either a substitution template + or an LDAP query template. + + If you specify a :setting:`~security.ldap.userToDNMapping` + transformation that uses LDAP queries as part of the transformation, + you must also specify a :setting:`~security.ldap.queryUser` with + the appropriate level of permissions for the LDAP server + + - **NO**, unless client authenticate using usernames that require + transformation. + +LDAP Authentication via ``saslauthd`` +------------------------------------- + +.. warning:: + + Windows MongoDB deployments are incompatible with ``saslauthd`` and cannot + use the following procedures. Connect using your :ref:`operating system's + LDAP libraries ` instead. + +Considerations +~~~~~~~~~~~~~~ + .. include:: /includes/admonition-saslauthd-ldap-considerations.rst -MongoDB Configuration ---------------------- +Configuration +~~~~~~~~~~~~~ -To configure the MongoDB server to use LDAP authentication mechanism, use +To configure the MongoDB server to bind to the LDAP server using via +``saslauthd``, use the following command line options: - ``--auth`` to enable access control, @@ -43,22 +291,45 @@ Or, if using the :doc:`YAML configuration file - :setting:`setParameter.saslauthdPath ` set to the path to the Unix-domain Socket of the saslauthd instance. -LDAP User ---------- +You need to create or update the ``saslauthd.conf`` file with the parameters +appropriate for your LDAP server. Documenting ``saslauthd.conf`` is out +of scope for this documentation. The following tutorials provide basic +information on configuring ``saslauthd.conf`` to work with two popular +LDAP services: + +- :doc:`/tutorial/configure-ldap-sasl-openldap` + +- :doc:`/tutorial/configure-ldap-sasl-activedirectory` + +Please see the documentation for ``saslauthd`` as well as your specific +LDAP service for guidance. -In order to authenticate a user with the LDAP authentication mechanism, -add a corresponding :doc:`user ` to the -``$external`` database. You do not need to save the user's password in -MongoDB. +Connect to a MongoDB server via LDAP authentication +--------------------------------------------------- -The ``$external`` database is the :ref:`authentication database -` for the LDAP user. To authenticate the LDAP -user, you must authenticate against the ``$external`` database. When -authenticating, specify ``PLAIN`` for the authentication mechanism . +To authenticate to a MongoDB server via LDAP authentication, use +:method:`db.auth()` on the ``$external`` database with the following +parameters: -LDAP authentication requires that MongoDB forward the user's password in -plain text. As such, you must specify ``digestPassword`` set to false -during authentication. +.. list-table:: + :header-rows:1 + :widths: 20 80 + + * - option + + - description + + * - ``username`` + + - The username to authenticate as. + + * - ``password`` + + - The password to authenticate with. + + * - ``mechanism`` + + - Set to ``PLAIN``. Additional Information ---------------------- @@ -74,6 +345,6 @@ users using LDAP, see: .. toctree:: :titlesonly: - + /tutorial/configure-ldap-sasl-activedirectory /tutorial/configure-ldap-sasl-openldap diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt index 7721b562b04..e5191cbaa3e 100644 --- a/source/reference/parameters.txt +++ b/source/reference/parameters.txt @@ -79,10 +79,9 @@ Authentication Parameters * - :ref:`PLAIN ` (LDAP SASL) - - External authentication using LDAP. ``PLAIN`` transmits - passwords in plain text. This mechanism is available only in - `MongoDB Enterprise - `_. + - ``PLAIN`` transmits passwords in plain text. Required for + :ref:`security-ldap`. Optional for authenticating non-``$external`` + users. .. todo:: Per DOCS-2940, combine this with similar info in /includes/options-conf