Docs4dev
Docs
mongodb / v3.6 / reference / reference-program-mongoldap.html

mongoldap

On this page

New in version 3.4: MongoDB Enterprise

Synopsis

MongoDB provides mongoldap for testing MongoDB’s LDAP configuration options against a running LDAP server or set of servers.

To validate the LDAP options in the configuration file, set the mongoldap --config option to the configuration file’s path.

To test the LDAP configuration options, you must specify a --user and --password. mongoldap simulates authentication to a MongoDB server running with the provided configuration options and credentials.

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 LDAP authorization, 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 LDAP authorization roles for user access control. For example, use mongoldap to ensure your configuration allows privileged users to gain the necessary roles to perform their expected tasks. Similarly, use 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 LDAP authentication, use mongoldap to ensure that the authentication operation works as expected.

Run mongoldap from the system command line, not the mongo shell.

This document provides a complete overview of all command line options for 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:

security:
   authorization: "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:
   authenticationMechanisms: "PLAIN"

You can use mongoldap to validate the configuration file, which returns a report of the procedure. You must specify a username and password for mongoldap.

mongoldap --config <path-to-config> --user "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:

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

mongoldap
--config <filename> , -f <filename>

Specifies a configuration file for runtime configuration options. The options are equivalent to the command-line configuration options. See Configuration File Options for more information.

mongoldap uses any configuration options related to LDAP Proxy Authentication or LDAP Authorization for testing LDAP authentication or authorization.

Requires specifying --user. May accept --password for testing LDAP authentication.

Ensure the configuration file uses ASCII encoding. The mongoldap instance does not support configuration files with non-ASCII encoding, including UTF-8.

--user <string>

Username for mongoldap to use when attempting LDAP authentication or authorization.

--password <string>

Password of the --user for mongoldap to use when attempting LDAP authentication. Not required for LDAP authorization.

--ldapServers <host1>:<port>,<host2>:<port>,...,<hostN>:<port>

New in version 3.4: Available in MongoDB Enterprise only.

The LDAP server against which the mongoldap authenticates users or determines what actions a user is authorized to perform on a given database. If the LDAP server specified has any replicated instances, you may specify the host and port of each replicated server in a comma-delimited list.

If your LDAP infrastructure partitions the LDAP directory over multiple LDAP servers, specify one LDAP server or any of its replicated instances to --ldapServers. MongoDB supports following LDAP referrals as defined in RFC 4511 4.1.10 . Do not use --ldapServers for listing every LDAP server in your infrastructure.

This setting can be configured on a running mongoldap using setParameter.

If unset, mongoldap cannot use LDAP authentication or authorization.

--ldapQueryUser <string>

New in version 3.4: Available in MongoDB Enterprise only.

The identity with which mongoldap binds as, when connecting to or performing queries on an LDAP server.

Only required if any of the following are true:

You must use --ldapQueryUser with --ldapQueryPassword.

If unset, mongoldap will not attempt to bind to the LDAP server.

This setting can be configured on a running mongoldap using setParameter.

Note

Windows MongoDB deployments can use --ldapBindWithOSDefaults instead of --ldapQueryUser and --ldapQueryPassword. You cannot specify both --ldapQueryUser and --ldapBindWithOSDefaults at the same time.

--ldapQueryPassword <string>

New in version 3.4: Available in MongoDB Enterprise only.

The password used to bind to an LDAP server when using --ldapQueryUser. You must use --ldapQueryPassword with --ldapQueryUser.

If unset, mongoldap will not attempt to bind to the LDAP server.

This setting can be configured on a running mongoldap using setParameter.

Note

Windows MongoDB deployments can use --ldapBindWithOSDefaults instead of --ldapQueryPassword and --ldapQueryPassword. You cannot specify both --ldapQueryPassword and --ldapBindWithOSDefaults at the same time.

--ldapBindWithOSDefaults <bool>

Default: false

New in version 3.4: Available in MongoDB Enterprise for the Windows platform only.

Allows mongoldap to authenticate, or bind, using your Windows login credentials when connecting to the LDAP server.

Only required if:

Use --ldapBindWithOSDefaults to replace --ldapQueryUser and --ldapQueryPassword.

--ldapBindMethod <string>

Default: simple

New in version 3.4: Available in MongoDB Enterprise only.

The method mongoldap uses to authenticate to an LDAP server. Use with --ldapQueryUser and --ldapQueryPassword to connect to the LDAP server.

--ldapBindMethod supports the following values:

  • simple - mongoldap uses simple authentication.
  • sasl - mongoldap uses SASL protocol for authentication

If you specify sasl, you can configure the available SASL mechanisms using --ldapBindSaslMechanisms. mongoldap defaults to using DIGEST-MD5 mechanism.

--ldapBindSaslMechanisms =<string>

Default: DIGEST-MD5

New in version 3.4: Available in MongoDB Enterprise only.

A comma-separated list of SASL mechanisms mongoldap can use when authenticating to the LDAP server. The mongoldap and the LDAP server must agree on at least one mechanism. The mongoldap dynamically loads any SASL mechanism libraries installed on the host machine at runtime.

Install and configure the appropriate libraries for the selected SASL mechanism(s) on both the mongoldap host and the remote LDAP server host. Your operating system may include certain SASL libraries by default. Defer to the documentation associated with each SASL mechanism for guidance on installation and configuration.

If using the GSSAPI SASL mechanism for use with Kerberos Authentication, verify the following for the mongoldap host machine:

Linux
  • The KRB5_CLIENT_KTNAME environment variable resolves to the name of the client Linux Keytab Files for the host machine. For more on Kerberos environment variables, please defer to the Kerberos documentation .
  • The client keytab includes a User Principal for the mongoldap to use when connecting to the LDAP server and execute LDAP queries.
Windows
If connecting to an Active Directory server, the Windows Kerberos configuration automatically generates a Ticket-Granting-Ticket when the user logs onto the system. Set --ldapBindWithOSDefaults to true to allow mongoldap to use the generated credentials when connecting to the Active Directory server and execute queries.

Set --ldapBindMethod to sasl to use this option.

Note

For a complete list of SASL mechanisms see the IANA listing . Defer to the documentation for your LDAP or Active Directory service for identifying the SASL mechanisms compatible with the service.

MongoDB is not a source of SASL mechanism libraries, nor is the MongoDB documentation a definitive source for installing or configuring any given SASL mechanism. For documentation and support, defer to the SASL mechanism library vendor or owner.

For more information on SASL, defe