From bfc3d2c6b9b623066858cc9f3e261a8f92e9a419 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 13 Mar 2014 09:35:23 -0400 Subject: [PATCH] DOCS-2751 reformat steps: Authenticate Using SASL and LDAP --- source/core/authentication.txt | 3 +- ...nticate-through-ldap-active-directory.yaml | 5 + .../steps-authenticate-through-ldap.yaml | 28 ++ ...-authentication-with-active-directory.yaml | 73 +++++ ...toc-security-tutorials-access-control.yaml | 8 +- source/release-notes/2.6.txt | 3 +- source/tutorial/add-user-to-database.txt | 8 +- ...l-authentication-with-active-directory.txt | 109 ++++++++ ...dap-sasl-authentication-with-open-ldap.txt | 140 ++++++++++ .../configure-ldap-sasl-authentication.txt | 262 ------------------ 10 files changed, 369 insertions(+), 270 deletions(-) create mode 100644 source/includes/steps-authenticate-through-ldap-active-directory.yaml create mode 100644 source/includes/steps-authenticate-through-ldap.yaml create mode 100644 source/includes/steps-configure-ldap-sasl-authentication-with-active-directory.yaml create mode 100644 source/tutorial/configure-ldap-sasl-authentication-with-active-directory.txt create mode 100644 source/tutorial/configure-ldap-sasl-authentication-with-open-ldap.txt delete mode 100644 source/tutorial/configure-ldap-sasl-authentication.txt diff --git a/source/core/authentication.txt b/source/core/authentication.txt index 6b4978fc8bb..a95dec3aae4 100644 --- a/source/core/authentication.txt +++ b/source/core/authentication.txt @@ -113,7 +113,8 @@ LDAP Proxy Authority Authentication `MongoDB Enterprise `_ supports proxy authentication through a Lightweight Directory Access Protocol (LDAP) service. See -:doc:`/tutorial/configure-ldap-sasl-authentication`. +:doc:`/tutorial/configure-ldap-sasl-authentication-with-active-directory` +and :doc:`/tutorial/configure-ldap-sasl-authentication-with-open-ldap`. .. include:: /includes/admonition-mongodb-enterprise-windows-ldap.rst diff --git a/source/includes/steps-authenticate-through-ldap-active-directory.yaml b/source/includes/steps-authenticate-through-ldap-active-directory.yaml new file mode 100644 index 00000000000..046412b4c8e --- /dev/null +++ b/source/includes/steps-authenticate-through-ldap-active-directory.yaml @@ -0,0 +1,5 @@ +stepnum: 1 +source: + file: steps-authenticate-through-ldap.yaml + ref: authenticate +... diff --git a/source/includes/steps-authenticate-through-ldap.yaml b/source/includes/steps-authenticate-through-ldap.yaml new file mode 100644 index 00000000000..7abc03471bc --- /dev/null +++ b/source/includes/steps-authenticate-through-ldap.yaml @@ -0,0 +1,28 @@ +title: Authenticate the user in the ``mongo`` shell. +stepnum: 1 +ref: authenticate +pre: | + To perform the authentication in the :program:`mongo` shell, use the + :method:`db.auth()` method in the ``$external`` database. +action: + pre: | + Specify the value ``"PLAIN"`` in the ``mechanism`` field, the user and + password in the ``user`` and ``pwd`` fields respectively, and the + value ``false`` in the ``digestPassword`` field. You **must** specify + ``false`` for ``digestPassword`` since the server must receive an + undigested password to forward on to ``saslauthd``, as in the + following example: + language: javascript + code: | + db.getSiblingDB("$external").auth( + { + mechanism: "PLAIN", + user: , + pwd: , + digestPassword: false + } + ) +post: + The server forwards the password in plain text. In general, use only on + a trusted channel (VPN, SSL, trusted wired network). +... diff --git a/source/includes/steps-configure-ldap-sasl-authentication-with-active-directory.yaml b/source/includes/steps-configure-ldap-sasl-authentication-with-active-directory.yaml new file mode 100644 index 00000000000..eaa8015910b --- /dev/null +++ b/source/includes/steps-configure-ldap-sasl-authentication-with-active-directory.yaml @@ -0,0 +1,73 @@ +title: Specify the mechanism. +stepnum: 1 +ref: specify-mechanism +action: + - pre: | + On systems that configure ``saslauthd`` with the + ``/etc/sysconfig/saslauthd`` file, such as Red Hat Enterprise Linux, + Fedora, CentOS, and Amazon Linux AMI, set the mechanism ``MECH`` to + ``ldap``: + language: javascript + code: | + MECH=ldap + - pre: | + On systems that configure ``saslauthd`` with the + ``/etc/default/saslauthd`` file, set the ``MECHANISMS`` option to + ``ldap``: + language: javascript + code: | + MECHANISMS="ldap" +--- +title: Set the caching behavior. +stepnum: 2 +ref: caching-behavior +pre: | + On certain Linux distributions, ``saslauthd`` starts with the caching + of authentication credentials *enabled*. Until restarted or until the + cache expires, ``saslauthd`` will not contact the LDAP server to + re-authenticate users in its authentication cache. This allows + ``saslauthd`` to successfully authenticate users in its cache, even in + the LDAP server is down or if the cached users' credentials are revoked. +action: + pre: | + To set the expiration time (in seconds) for the authentication cache, see + the `-t option `_ of + ``saslauthd``. +--- +title: Configure ``saslauthd`` LDAP options. +stepnum: 3 +ref: ldap-options +pre: | + If the ``saslauthd.conf`` file does not exist, create it. + The ``saslauthd.conf`` file usually resides in the ``/etc`` + folder. If specifying a different file path, see the + `-O option `_ of + ``saslauthd``. +action: + - heading: Configure for Use with ActiveDirectory + pre: | + To use with ActiveDirectory, start ``saslauthd`` with the following + configuration options set in the ``saslauthd.conf`` file: + language: javascript + code: | + ldap_servers: + ldap_use_sasl: yes + ldap_mech: DIGEST-MD5 + ldap_auth_method: fastbind + post: | + For the ````, specify the uri of the ldap server. For + example, ``ldap_servers: ldaps://ad.example.net``. + - heading: Configure for Use with OpenLDAP + pre: | + .. include:: /includes/steps-configure-openldap.rst +--- +title: Test the ``saslauthd`` configuration. +stepnum: 4 +ref: +action: + pre: | + Use ``testsaslauthd`` utility. For example: + language: javascript + code: | + testsaslauthd -u testuser -p testpassword -f /var/run/saslauthd/mux +... diff --git a/source/includes/toc-security-tutorials-access-control.yaml b/source/includes/toc-security-tutorials-access-control.yaml index f6ef1c500df..5bdb5e7a5b7 100644 --- a/source/includes/toc-security-tutorials-access-control.yaml +++ b/source/includes/toc-security-tutorials-access-control.yaml @@ -17,9 +17,13 @@ file: /tutorial/configure-x509 description: | Use x.509 for client authentication and internal member authentication. --- -file: /tutorial/configure-ldap-sasl-authentication +file: /tutorial/configure-ldap-sasl-authentication-with-active-directory description: | - Describes for MongoDB Enterprise the process to authenticate with SASL/LDAP. + Describes authentication with SASL/LDAP and ActiveDirectory. +--- +file: /tutorial/configure-ldap-sasl-authentication-with-open-ldap +description: | + Describes authentication with SASL/LDAP and OpenLDAP. --- file: /tutorial/control-access-to-mongodb-with-kerberos-authentication description: | diff --git a/source/release-notes/2.6.txt b/source/release-notes/2.6.txt index 343dcc32849..19c43cfedce 100644 --- a/source/release-notes/2.6.txt +++ b/source/release-notes/2.6.txt @@ -337,7 +337,8 @@ MongoDB Enterprise provides support for proxy authentication of users. This allows administrators to configure a MongoDB cluster to authenticate users via Linux PAM or by proxying authentication requests to a specified Lightweight Directory Access Protocol (LDAP) service. -See :doc:`/tutorial/configure-ldap-sasl-authentication`. +See :doc:`/tutorial/configure-ldap-sasl-authentication-with-active-directory` +and :doc:`/tutorial/configure-ldap-sasl-authentication-with-open-ldap`. .. include:: /includes/admonition-mongodb-enterprise-windows-ldap.rst diff --git a/source/tutorial/add-user-to-database.txt b/source/tutorial/add-user-to-database.txt index 9e2db0e7714..5e4fa595fa1 100644 --- a/source/tutorial/add-user-to-database.txt +++ b/source/tutorial/add-user-to-database.txt @@ -43,10 +43,10 @@ You can create a user without assigning roles, choosing instead to assign the roles later. To do so, create the user with an empty :data:`~admin.system.users.roles` array. -.. [#external-auth-mechanisms] :doc:`Kerberos - `, - :doc:`LDAP `, and - x.509 certificates provide external authentication mechanisms. +.. [#external-auth-mechanisms] :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication`, + :doc:`/tutorial/configure-ldap-sasl-authentication-with-active-directory`, + :doc:`/tutorial/configure-ldap-sasl-authentication-with-open-ldap`, + and x.509 certificates provide external authentication mechanisms. .. _add-user-prereq: diff --git a/source/tutorial/configure-ldap-sasl-authentication-with-active-directory.txt b/source/tutorial/configure-ldap-sasl-authentication-with-active-directory.txt new file mode 100644 index 00000000000..b03db13430a --- /dev/null +++ b/source/tutorial/configure-ldap-sasl-authentication-with-active-directory.txt @@ -0,0 +1,109 @@ +===================================================== +Authenticate Using SASL and LDAP with ActiveDirectory +===================================================== + +.. default-domain:: mongodb + +Overview +-------- + +MongoDB Enterprise provides support for proxy authentication of users. +This allows administrators to configure a MongoDB cluster to authenticate +users via Linux PAM or by proxying authentication requests to a specified +Lightweight Directory Access Protocol (LDAP) service. + +MongoDB does **not** support LDAP authentication in mixed sharded cluster +deployments that contain both version 2.4 and version 2.6 shards. See +:doc:`/release-notes/2.6-upgrade` for upgrade instructions. + +.. include:: /includes/admonition-mongodb-enterprise-windows-ldap.rst + +Considerations +-------------- + +Because the transmission of the username and password from the client to +the MongoDB server, from the MongoDB server to ``saslauthd``, and from +``saslauthd`` to the LDAP server uses ``SASL PLAIN`` mechanism, i.e. in +**plain text**, you should, in general, use only on a trusted channel +(VPN, SSL, trusted wired network). + +Procedures +---------- + +To use LDAP with ActiveDirectory, configure the ``saslauthd`` daemon +process and the MongoDB server, as described here. + +Configure ``saslauthd`` to use ActiveDirectory as the Authentication Mechanism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/steps/ldap-sasl-authentication-with-active-directory.rst + +Configure MongoDB Server to use ``saslauthd`` for Authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To configure the MongoDB server to use ``saslauthd`` set the following +options. Use either the :doc:`configuration file +` or the command line: + +- :setting:`auth`. This option enables authentication and authorization. + Either set :setting:`auth` to ``true`` in the configuration file or + enable :option:`--auth` on the command-line. + +- :parameter:`authenticationMechanisms`. Set this parameter to ``PLAIN``. + + - If using the configuration file, set the following: + + .. code-block:: sh + + setParameter=authenticationMechanisms=PLAIN + + - If using the command line, use :doc:`--setParameter + ` to set the following: + + .. code-block:: sh + + --setParameter authenticationMechanisms=PLAIN + +- :parameter:`saslauthdPath`. Set this parameter to the path of the + Unix-domain Socket of the ``saslauthd`` instance. + + For example, to set this option in the configuration file for a system + that uses ``/etc/sysconfig/saslauthd``, set the following: + + .. code-block:: sh + + setParameter=saslauthdPath=/etc/sysconfig/saslauthd/mux + + To use the default Unix-domain socket path, set + :parameter:`saslauthdPath` to the empty string ``""``. + +The following example sets the parameters using a :doc:`configuration file +`: + +.. code-block:: sh + + auth=true + setParameter=authenticationMechanisms=PLAIN + setParameter=saslauthdPath=//saslauthd/mux + +Add a User for Authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add the user to the ``$external`` database in MongoDB. To specify the +user's privileges, assign :doc:`roles ` to the user. +For example, the following adds a user with read-only access to the +records database: + +.. code-block:: sh + + db.getSiblingDB("$external").createUser( + { + user : , + roles: [ { role: "read", db: "records" } ] + } + ) + +Authenticate a Client +~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/steps/authenticate-through-ldap-active-directory.rst diff --git a/source/tutorial/configure-ldap-sasl-authentication-with-open-ldap.txt b/source/tutorial/configure-ldap-sasl-authentication-with-open-ldap.txt new file mode 100644 index 00000000000..48218a71f23 --- /dev/null +++ b/source/tutorial/configure-ldap-sasl-authentication-with-open-ldap.txt @@ -0,0 +1,140 @@ +============================================== +Authenticate Using SASL and LDAP with OpenLDAP +============================================== + +.. default-domain:: mongodb + +Overview +-------- + +MongoDB Enterprise provides support for proxy authentication of users. +This allows administrators to configure a MongoDB cluster to authenticate +users via Linux PAM or by proxying authentication requests to a specified +Lightweight Directory Access Protocol (LDAP) service. + +MongoDB does **not** support LDAP authentication in mixed sharded cluster +deployments that contain both version 2.4 and version 2.6 shards. See +:doc:`/release-notes/2.6-upgrade` for upgrade instructions. + +.. include:: /includes/admonition-mongodb-enterprise-windows-ldap.rst + +Considerations +-------------- + +Because the transmission of the username and password from the client +to the MongoDB server, from the MongoDB server to ``saslauthd``, and +from ``saslauthd`` to the LDAP server uses ``SASL PLAIN`` mechanism, +i.e. in **plain text**, you should, in general, use only on a trusted +channel (VPN, SSL, trusted wired network). + +Procedures +---------- + +To use LDAP for user authentication, configure the ``saslauthd`` daemon +process and the MongoDB server, as described here. + +Configure ``saslauthd`` to use OpenLDAP as the Authentication Mechanism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Update the ``saslauthd.conf`` file with the following configuration +options: + +.. code-block:: none + + ldap_servers: + ldap_search_base: + ldap_filter: + +For the ````, specify the uri of the ldap server. For example, +``ldap_servers: ldaps://ad.example.net``. + +For example, a sample ``saslauthd.conf`` file may have the following +content: + +.. code-block:: none + + ldap_servers: ldaps://ad.example.net + ldap_search_base: ou=Users,dc=example,dc=com + ldap_filter: (uid=%u) + +The values for these configuration options should correspond to the +values specific for your test. For example, to filter on email, specify +``ldap_filter: (mail=%n)`` instead. + +To use this sample OpenLDAP configuration, create users with a ``uid`` +attribute (login name) and place under the ``Users`` organizational +unit (``ou``) under the domain components (``dc``) ``example`` and +``com``. + +For more information on ``saslauthd`` configuration, see +``_. + +Configure MongoDB Server to use ``saslauthd`` for Authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To configure the MongoDB server to use ``saslauthd`` set the following +options. Use either the :doc:`configuration file +` or the command line: + +- :setting:`auth`. This option enables authentication and authorization. + Either set :setting:`auth` to ``true`` in the configuration file or + enable :option:`--auth` on the command-line. + +- :parameter:`authenticationMechanisms`. Set this parameter to ``PLAIN``. + + - If using the configuration file, set the following: + + .. code-block:: sh + + setParameter=authenticationMechanisms=PLAIN + + - If using the command line, use :doc:`--setParameter + ` to set the following: + + .. code-block:: sh + + --setParameter authenticationMechanisms=PLAIN + +- :parameter:`saslauthdPath`. Set this parameter to the path of the + Unix-domain Socket of the ``saslauthd`` instance. + + For example, to set this option in the configuration file for a system + that uses ``/etc/sysconfig/saslauthd``, set the following: + + .. code-block:: sh + + setParameter=saslauthdPath=/etc/sysconfig/saslauthd/mux + + To use the default Unix-domain socket path, set + :parameter:`saslauthdPath` to the empty string ``""``. + +The following example sets the parameters using a :doc:`configuration file +`: + +.. code-block:: sh + + auth=true + setParameter=authenticationMechanisms=PLAIN + setParameter=saslauthdPath=//saslauthd/mux + +Add a User for Authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add the user to the ``$external`` database in MongoDB. To specify the +user's privileges, assign :doc:`roles ` to the user. +For example, the following adds a user with read-only access to the +records database: + +.. code-block:: sh + + db.getSiblingDB("$external").createUser( + { + user : , + roles: [ { role: "read", db: "records" } ] + } + ) + +Authenticate a Client +~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/steps/authenticate-through-ldap.rst diff --git a/source/tutorial/configure-ldap-sasl-authentication.txt b/source/tutorial/configure-ldap-sasl-authentication.txt deleted file mode 100644 index dded285d053..00000000000 --- a/source/tutorial/configure-ldap-sasl-authentication.txt +++ /dev/null @@ -1,262 +0,0 @@ -================================ -Authenticate Using SASL and LDAP -================================ - -.. default-domain:: mongodb - -MongoDB Enterprise provides support for proxy authentication of users. -This allows administrators to configure a MongoDB cluster to -authenticate users via Linux PAM or by proxying authentication requests -to a specified Lightweight Directory Access Protocol (LDAP) service. - -.. include:: /includes/admonition-mongodb-enterprise-windows-ldap.rst - -MongoDB does **not** support LDAP authentication in mixed sharded -cluster deployments that contain both version 2.4 and version 2.6 -shards. See :doc:`/release-notes/2.6-upgrade` for upgrade instructions. - -.. _ldap-password-in-plaintext: - -Password in Plaintext ---------------------- - -Because the transmission of the username and password from the client -to the MongoDB server, from the MongoDB server to ``saslauthd``, and -from ``saslauthd`` to the LDAP server uses ``SASL PLAIN`` mechanism, -i.e. in **plain text**, you should, in general, use only on a trusted -channel (VPN, SSL, trusted wired network). - -Configure ``saslauthd`` ------------------------ - -LDAP support for user authentication requires proper configuration of -the ``saslauthd`` daemon process as well as the MongoDB server. - -Specify Mechanism -~~~~~~~~~~~~~~~~~ - -On systems that configure ``saslauthd`` with a -``/etc/sysconfig/saslauthd`` file, such as Red Hat Enterprise Linux, -Fedora, CentOS, Amazon Linux AMI, set the mechanism ``MECH`` to -``ldap``: - -.. code-block:: none - - MECH=ldap - -On systems that configure ``saslauthd`` with a -``/etc/default/saslauthd`` file, set the ``MECHANISMS`` option to -``ldap``: - -.. code-block:: none - - MECHANISMS="ldap" - -Caching Behavior -~~~~~~~~~~~~~~~~ - -On certain Linux distributions, ``saslauthd`` starts with the caching -of authentication credentials *enabled*. Until restarted or until the -cache expires, ``saslauthd`` will not contact the LDAP server to -re-authenticate users in its authentication cache. This allows -``saslauthd`` to successfully authenticate users in its cache, even in -the LDAP server is down or if the cached users' credentials are revoked. - -To set the expiration time (in seconds) for the authentication cache, -see the `-t option -`_ of -``saslauthd``. - -Update ``saslauthd`` Configuration with LDAP Options -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If ``saslauthd.conf`` file does not exist, create a ``saslauthd.conf`` -file. Generally, the ``saslauthd.conf`` file resides in the ``/etc`` -folder; however, when specifying a different file path, see the see the -`-O option `_ of -``saslauthd``. - -Configure for Use with ActiveDirectory -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To use with *ActiveDirectory*, start ``saslauthd`` with the following -configuration options set in the ``saslauthd.conf`` file: - -.. code-block:: none - - ldap_servers: - ldap_use_sasl: yes - ldap_mech: DIGEST-MD5 - ldap_auth_method: fastbind - -Configure for Use with OpenLDAP -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To connect to an OpenLDAP server, update the ``saslauthd.conf`` file -with the following configuration options: - -.. code-block:: none - - ldap_servers: - ldap_search_base: - ldap_filter: - -- The ``ldap_servers`` specifies the uri of the LDAP server used for - authentication. - - In general, for OpenLDAP installed on the local machine, you can - specify the value ``ldap://localhost:389`` or if using LDAP over SSL, - you can specify the value ``ldaps://localhost:636``. - -- The ``ldap_search_base`` specifies distinguished name to which the - search is relative. The search includes the base or objects below. - -- The ``ldap_filter`` specifies the search filter. - -For example, a sample ``saslauthd.conf`` file may have the following -content: - -.. code-block:: none - - ldap_servers: ldaps://ad.example.net - ldap_search_base: ou=Users,dc=example,dc=com - ldap_filter: (uid=%u) - -The values for these configuration options should correspond to the -values specific for your test. For example, to filter on email, specify -``ldap_filter: (mail=%n)`` instead. - -To use this sample OpenLDAP configuration, create users with a ``uid`` -attribute (login name) and place under the ``Users`` organizational -unit (``ou``) under the domain components (``dc``) ``example`` and -``com``. - -For more information on ``saslauthd`` configuration, see -``_. - -Test ``saslauthd`` Configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To test the ``saslauthd`` configuration, use ``testsaslauthd`` utility, -as in the following example: - -.. code-block:: sh - - testsaslauthd -u testuser -p testpassword -f /var/run/saslauthd/mux - -Configure MongoDB Server ------------------------- - -To configure the MongoDB server to use the ``saslauthd`` instance for -proxy authentication, start the :program:`mongod` with the following -options: - -- :option:`--auth` to enable authentication/authorization, - -- :parameter:`authenticationMechanisms` parameter set to ``PLAIN``, and - -- :parameter:`saslauthdPath` parameter set to the path to the - Unix-domain Socket of the ``saslauthd`` instance. - - - If ``saslauthd`` has a socket path of ``///saslauthd``, - set :parameter:`saslauthdPath` to ``///saslauthd/mux``. - - - To use the default Unix-domain socket path, set - :parameter:`saslauthdPath` to the empty string ``""``. - -Configure the MongoDB server using either the command line option -:doc:`--setParameter ` or the :doc:`configuration -file `. - -Specify A Socket Path -~~~~~~~~~~~~~~~~~~~~~ - -For socket path of ``///saslauthd``, set the -:parameter:`saslauthdPath` to ``///saslauthd/mux``, as in -the following command line example: - -.. code-block:: sh - - mongod --auth --setParameter saslauthdPath=///saslauthd/mux --setParameter authenticationMechanisms=PLAIN - -Or if using a :doc:`configuration file -`, specify the following parameters -in the file: - -.. code-block:: sh - - auth=true - setParameter=saslauthdPath=///saslauthd/mux - setParameter=authenticationMechanisms=PLAIN - -Use the Default Unix-domain Socket Path -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To use the default Unix-domain socket path, set the -:parameter:`saslauthdPath` to the empty string ``""``, as in the -following command line example: - -.. code-block:: sh - - mongod --auth --setParameter saslauthdPath="" --setParameter authenticationMechanisms=PLAIN - -Or if using a :doc:`configuration file -`, specify the following parameters -in the file: - -.. code-block:: sh - - setParameter=saslauthdPath="" - setParameter=authenticationMechanisms=PLAIN - auth=true - -Authenticate ------------- - -.. _add-ldap-sasl-auth-user: - -Add User for Authentication -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To perform authentication for a user, you must first add the user to -the ``$external`` database in MongoDB. To specify the user's -privileges, assign :doc:`roles ` to the user. For -example, the following adds a user with read-only access to the records -database: - -.. code-block:: javascript - - db.getSiblingDB("$external").createUser( - { - user : , - roles: [ { role: "read", db: "records" } ] - } - ) - -Authenticate in the ``mongo`` Shell -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To perform the authentication in the :program:`mongo` shell, use the -:method:`db.auth()` method in the ``$external`` database. - -Specify the value ``"PLAIN"`` in the ``mechanism`` field, the user and -password in the ``user`` and ``pwd`` fields respectively, and the value -``false`` in the ``digestPassword`` field. You **must** specify -``false`` for ``digestPassword`` since the server must receive an -undigested password to forward on to ``saslauthd``, as in the following -example: - -.. code-block:: javascript - :emphasize-lines: 7 - - db.getSiblingDB("$external").auth( - { - mechanism: "PLAIN", - user: , - pwd: , - digestPassword: false - } - ) - -The server forwards the password in plain text. In general, use only on -a trusted channel (VPN, SSL, trusted wired network). See -:ref:`ldap-password-in-plaintext`.