Normally, a client needs to authenticate themselves
against the MongoDB server user database before doing any work
or reading any data from a mongod or mongos instance.
External authentication allows the MongoDB server
to verify the client’s user name and password against a separate service,
such as OpenLDAP or Active Directory.
The following components are necessary for external authentication to work:
The following image illustrates this architecture:
An authentication session uses the following sequence:
mongo client connects to a running mongod instance.PLAIN authentication request
using the SASL library.mongod server receives this SASL Message,
with its authentication request payload.saslauthd daemon.saslauthd daemon passes the payload on to the LDAP service
to get a YES or NO authentication response
(in other words, does this user exist and is the password correct).saslauthd,
through the SASL library, to mongod.mongod server uses this YES/NO response
to authenticate the client or reject the request.Use the following command to add an external user to the mongod server:
> db.getSiblingDB("$external").createUser( {user : christian, roles: [ {role: "read", db: "test"} ]} );
The previous example assumes that you have set up the server-wide admin user/role and have successfully authenticated as that user locally.
Note
External users cannot have roles assigned in the admin database.
When running the mongo client, a user can authenticate
against a given database using the following command:
> db.getSiblingDB("$external").auth({ mechanism:"PLAIN", user:"christian", pwd:"secret", digestPassword:false})
This section describes an example configuration suitable only to test out the external authentication functionality in a non-production environment. Use common sense to adapt these guidelines to your production.
The following components are required:
slapd: OpenLDAP server.libsasl2 version 2.1.25 or later.saslauthd: SASL Authentication Daemon (distinct from libsasl2).The following steps will help you configure your environment:
Start the LDAP server. Note the given URL and configuration file. Also note the username: openldapper. It is important that the user starting the service, and adding entries to the LDAP database, has permissions to do so.
$ slapd -h ldap://127.0.0.1:9009/ -u openldapper -f /etc/openldap/slapd.conf
The URL argument will be used for entering data into the LDAP database,
verifying entries, and as an endpoint for saslauthd to authenticate
against during MongoDB external authentication.
A simple LDAP configuration file can have the following contents:
database mdb
suffix "dc=example,dc=com"
rootdn "cn=openldapper,dc=example,dc=com"
rootpw secret
directory /home/openldapper/ldap/tests/openldap/install/var/openldap-data
There are other entries in the slapd.conf file
that are important for successfully starting the LDAP service.
OpenLDAP installations have a sample slapd.conf file
that has the above and other required entries,
such as include, pidfile, and argsfile.
OpenLDAP comes with a few programs to communicate with the LDAP daemon/service.
For example, to add new users to the LDAP database,
you can use ldapadd or ldapmodify, with an associated .ldif file.
These are the typical settings required for saslauthd
to connect to a local OpenLDAP service
(the server address MUST match the OpenLDAP installation):
ldap_servers: ldap://127.0.0.1:9009
ldap_search_base: dc=example,dc=com
ldap_filter: (cn=%u)
ldap_bind_dn: cn=openldapper,dc=example,dc=com
ldap_password: secret
Note the LDAP password and bind domain name.
This allows the saslauthd service to connect to the LDAP service as root.
In production, this would not be the case;
users should not store administrative passwords in unecrypted files.
In order for LDAP operations to be performed against a Windows Active Directory server, a user record must be created to perform the lookups.
The following example shows configuration parameters for saslauthd
to communicate with an Active Directory server:
ldap_servers: ldap://198.51.100.10
ldap_mech: PLAIN
ldap_search_base: CN=Users,DC=example,DC=com
ldap_filter: (sAMAccountName=%u)
ldap_bind_dn: CN=ldapmgr,CN=Users,DC=<AD Domain>,DC=<AD TLD>
ldap_password: ld@pmgr_Pa55word
In order to determine and test the correct search base and filter for your Active Directory installation, the Microsoft LDP GUI Tool can be used to bind and search the LDAP-compatible directory.
Verify that the saslauthd service can authenticate
against the users created in the LDAP service:
$ testsaslauthd -u christian -p secret -f /var/run/saslauthd/mux
This should return 0:OK "Success".
If it doesn’t, then either the user name and password
are not in the LDAP service, or sasaluthd is not configured properly.
The SASL library used by mongod must also be configured properly
via a configuration file:
pwcheck_method: saslauthd
saslauthd_path: /var/run/saslauthd/mux
log_level: 5
mech_list: plain
The first two entries (pwcheck_method and saslauthd_path)
are required for mongod to successfully use the saslauthd service.
The log_level is optional but may help determine configuration errors.
The file must be named mongodb.conf and placed in a directory
where libsasl2 can find and read it.
libsasl2 is hard-coded to look in certain directories at build time.
This location may be different depending on the installation method.
External authentication is enabled the same way as local authentication.
Simply start the server with the --auth option:
$ ./mongod --dbpath=/data/db --auth
This assumes that libsasl2 has been installed in the system
as a dynamic library (libsasl2.so).
You may see an error on the command line or in the logs
if that library is missing from your server’s environment.
When everything is configured properly, you can use the External Authentication Commands.
See Also
For general inquiries about our open source software and database management tools, please send us your question and someone will contact you.
