mongoldap

New in version 3.4: MongoDB Enterprise

Synopsis

Starting in version 3.4, MongoDB Enterprise providesmongoldap for testing MongoDB’s LDAP configurationoptions against a running LDAP server or setof servers.

To validate the LDAP options in the configuration file, set themongoldap—config option to the configuration file’spath.

To test the LDAP configuration options, you must specify a —userand —password. mongoldap simulates authentication to aMongoDB server running with the provided configuration options and credentials.

mongoldap returns a report that includes the success or failure ofany step in the LDAP authentication or authorization procedure. Error messagesinclude information on specific errors encountered and potential advice forresolving the error.

When configuring options related to LDAP authorization, mongoldap executes an LDAP queryconstructed using the provided configuration options and username, and returnsa 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, usemongoldap to ensure your configuration allows privileged users togain the necessary roles to perform their expected tasks. Similarly, usemongoldap to ensure your configuration disallows non-privilegedusers from gaining roles for accessing the MongoDB server, or performingunauthorized actions.

When configuring options related to LDAP authentication, use mongoldap to ensure that the authenticationoperation 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 formongoldap.

Availability

The mongoldap tool is part of the MongoDB tools package. Consult theinstallation guide for your platform forinstructions on how to install the tools package as part of yourMongoDB installation.

The tools package is also available from theMongoDB Download Center,either as a separate tools download, or contained within theTGZ or ZIP downloads, depending on platform. On Windows, the MSI installer for the Enterprise edition includes mongoldap as part of the default installation.

Tip

If downloading the TGZ or ZIP files from the DownloadCenter, you may want to update your PATH environmentvariable to include the directory where you installed these tools.See the installation guidefor your platform for more information.

Usage

Note

A full description of LDAP or Active Directory is beyond the scope ofthis documentation.

Consider the following sample configuration file, designed to supportLDAP 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, whichreturns a report of the procedure. You must specify a username and passwordfor mongoldap.

mongoldap --config=<path-to-config> --user="bob@dba.example.com" --password="secret123"

If the provided credentials are valid, and the LDAP options in theconfiguration 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-lineconfiguration options. See Configuration File Options formore information.

mongoldap uses any configuration options related to LDAP Proxy Authenticationor LDAP Authorization for testing LDAP authentication orauthorization.

Requires specifying —user. May accept —password fortesting LDAP authentication.

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

• —user=<string>
• Username for mongoldap to use when attempting LDAP authentication orauthorization.

• —password=<string>
• Password of the —user formongoldap to use when attempting LDAP authentication. Notrequired 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 ordetermines what actions a user is authorized to perform on a givendatabase. If the LDAP server specified has any replicated instances,you may specify the host and port of each replicated server in acomma-delimited list.

If your LDAP infrastructure partitions the LDAP directory over multiple LDAPservers, specify one LDAP server or any of its replicated instances to—ldapServers. MongoDB supports following LDAP referrals as defined in RFC 45114.1.10. Do not use —ldapServersfor listing every LDAP server in your infrastructure.

This setting can be configured on a running mongoldap usingsetParameter.

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 orperforming queries on an LDAP server.

Only required if any of the following are true:

• Using LDAP authorization.
• Using an LDAP query for username transformation.
• The LDAP server disallows anonymous bindsYou 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 usingsetParameter.

Note

Windows MongoDB deployments can use —ldapBindWithOSDefaultsinstead of —ldapQueryUser and —ldapQueryPassword. You cannot specifyboth —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 usingsetParameter.

Note

Windows MongoDB deployments can use —ldapBindWithOSDefaultsinstead of —ldapQueryPassword and —ldapQueryPassword. You cannot specifyboth —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 logincredentials when connecting to the LDAP server.

Only required if:

• Using LDAP authorization.
• Using an LDAP query for username transformation.
• The LDAP server disallows anonymous bindsUse —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 LDAPserver. Use with —ldapQueryUser and —ldapQueryPassword to connect to the LDAP server.

—ldapBindMethod supportsthe following values:

ValueDescriptionsimplemongoldap uses simple authentication.saslmongoldap uses SASL protocol for authentication.

If you specify sasl, you can configure the available SASL mechanismsusing —ldapBindSASLMechanisms. mongoldap defaults tousing 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 canuse when authenticating to the LDAP server. The mongoldap and theLDAP server must agree on at least one mechanism. The mongoldapdynamically loads any SASL mechanism libraries installed on the hostmachine at runtime.

Install and configure the appropriate libraries for the selectedSASL mechanism(s) on both the mongoldap host and the remoteLDAP server host. Your operating system may include certain SASLlibraries by default. Defer to the documentation associated with eachSASL mechanism for guidance on installation and configuration.

If using the GSSAPI SASL mechanism for use withKerberos Authentication, verify the following for themongoldap host machine:

• Linux
• • The KRB5_CLIENT_KTNAME environmentvariable resolves to the name of the client Linux Keytab Filesfor the host machine. For more on Kerberos environmentvariables, please defer to theKerberos documentation.
  • The client keytab includes aUser Principal for the mongoldap to use whenconnecting to the LDAP server and execute LDAP queries.
• Windows
• If connecting to an Active Directory server, the WindowsKerberos configuration automatically generates aTicket-Granting-Ticket.aspx)when the user logs onto the system. Set —ldapBindWithOSDefaults totrue to allow mongoldap to use the generated credentials whenconnecting 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 theIANA listing.Defer to the documentation for your LDAP or Active Directoryservice for identifying the SASL mechanisms compatible with theservice.

MongoDB is not a source of SASL mechanism libraries, noris the MongoDB documentation a definitive source forinstalling or configuring any given SASL mechanism. Fordocumentation and support, defer to the SASL mechanismlibrary vendor or owner.

For more information on SASL, defer to the following resources:

• For Linux, please see the Cyrus SASL documentation.
• For Windows, please see the Windows SASL documentation.

• —ldapTransportSecurity=<string>
• Default: tls

New in version 3.4: Available in MongoDB Enterprise only.

By default, mongoldap creates a TLS/SSL secured connection to the LDAPserver.

For Linux deployments, you must configure the appropriate TLS Options in/etc/openldap/ldap.conf file. Your operating system’s package managercreates this file as part of the MongoDB Enterprise installation, via thelibldap dependency. See the documentation for TLS Options in theldap.conf OpenLDAP documentationfor more complete instructions.

For Windows deployment, you must add the LDAP server CA certificates to theWindows certificate management tool. The exact name and functionality of thetool may vary depending on operating system version. Please see thedocumentation for your version of Windows for more information oncertificate management.

Set —ldapTransportSecurity to none to disable TLS/SSL between mongoldap and the LDAPserver.

Warning

Setting —ldapTransportSecurity to none transmits plaintext information and possiblycredentials between mongoldap and the LDAP server.

• —ldapTimeoutMS=<long>
• Default: 10000

New in version 3.4: Available in MongoDB Enterprise only.

The amount of time in milliseconds mongoldap should wait for an LDAP serverto respond to a request.

Increasing the value of —ldapTimeoutMS may prevent connection failure between theMongoDB server and the LDAP server, if the source of the failure is aconnection timeout. Decreasing the value of —ldapTimeoutMS reduces the timeMongoDB waits for a response from the LDAP server.

This setting can be configured on a running mongoldap usingsetParameter.

• —ldapUserToDNMapping=<string>

New in version 3.4: Available in MongoDB Enterprise only.

Maps the username provided to mongoldap for authentication to a LDAPDistinguished Name (DN). You may need to use —ldapUserToDNMapping to transform ausername into an LDAP DN in the following scenarios:

• Performing LDAP authentication with simple LDAP binding, where usersauthenticate to MongoDB with usernames that are not full LDAP DNs.
• Using an LDAP authorization query template that requires a DN.
• Transforming the usernames of clients authenticating to Mongo DB usingdifferent authentication mechanisms (e.g. x.509, kerberos) to a full LDAPDN for authorization.—ldapUserToDNMapping expects a quote-enclosed JSON-string representing an ordered arrayof documents. Each document contains a regular expression match andeither a substitution or ldapQuery template used for transforming theincoming username.

Each document in the array has the following form:

{
  match: "<regex>"
  substitution: "<LDAP DN>" | ldapQuery: "<LDAP Query>"
}

FieldDescriptionExamplematchAn ECMAScript-formatted regular expression (regex) to match against aprovided username. Each parenthesis-enclosed section represents aregex capture group used by substitution or ldapQuery."(.+)ENGINEERING""(.+)DBA"substitutionAn LDAP distinguished name (DN) formatting template that converts theauthentication name matched by the match regex into a LDAP DN.Each curly bracket-enclosed numeric value is replaced by thecorresponding regex capture group extractedfrom the authentication username via the match regex.

The result of the substitution must be an RFC4514 escaped string."cn={0},ou=engineering,dc=example,dc=com"ldapQueryA LDAP query formatting template that inserts the authenticationname matched by the match regex into an LDAP query URI encodedrespecting RFC4515 and RFC4516. Each curly bracket-enclosed numericvalue is replaced by the corresponding regex capture group extractedfrom the authentication username via the match expression.mongoldap executes the query against the LDAP server to retrievethe LDAP DN for the authenticated user. mongoldap requiresexactly one returned result for the transformation to besuccessful, or mongoldap skips this transformation."ou=engineering,dc=example,dc=com??one?(user={0})"

Note

An explanation of RFC4514,RFC4515,RFC4516, or LDAP queries is outof scope for the MongoDB Documentation. Please review the RFC directly oruse your preferred LDAP resource.

For each document in the array, you must use either substitution orldapQuery. You cannot specify both in the same document.

When performing authentication or authorization, mongoldap steps througheach document in the array in the given order, checking the authenticationusername against the match filter. If a match is found,mongoldap applies the transformation and uses the output forauthenticating the user. mongoldap does not check the remaining documentsin the array.

If the given document does not match the provided authentication name, orthe transformation described by the document fails, mongoldap continuesthrough the list of documents to find additional matches. If no matches arefound in any document, mongoldap returns an error.

Example

The following shows two transformation documents. The firstdocument matches against any string ending in @ENGINEERING, placinganything preceeding the suffix into a regex capture group. Thesecond document matches against any string ending in @DBA, placinganything preceeding the suffix into a regex capture group.

Important

You must pass the array to —ldapUserToDNMapping as a string.

"[
   {
      match: "(.+)@ENGINEERING.EXAMPLE.COM",
      substitution: "cn={0},ou=engineering,dc=example,dc=com"
   },
   {
      match: "(.+)@DBA.EXAMPLE.COM",
      ldapQuery: "ou=dba,dc=example,dc=com??one?(user={0})"
 
   }
 
]"

A user with username alice@ENGINEERING.EXAMPLE.COM matches the firstdocument. The regex capture group {0} corresponds to the stringalice. The resulting output is the DN"cn=alice,ou=engineering,dc=example,dc=com".

A user with username bob@DBA.EXAMPLE.COM matches the second document.The regex capture group {0} corresponds to the string bob. Theresulting output is the LDAP query"ou=dba,dc=example,dc=com??one?(user=bob)". mongoldap executes thisquery against the LDAP server, returning the result"cn=bob,ou=dba,dc=example,dc=com".

If —ldapUserToDNMapping is unset, mongoldap applies no transformations to the usernamewhen attempting to authenticate or authorize a user against the LDAP server.

This setting can be configured on a running mongoldap using thesetParameter database command.

• —ldapAuthzQueryTemplate=<string>

New in version 3.4: Available in MongoDB Enterprise only.

A relative LDAP query URL formatted conforming to RFC4515 and RFC4516 that mongoldap executes to obtainthe LDAP groups to which the authenticated user belongs to. The query isrelative to the host or hosts specified in —ldapServers.

In the URL, you can use the following substituion tokens:

Substitution TokenDescription{USER}Substitutes the authenticated username, or thetransformedusername if a username mapping is specified.{PROVIDED_USER}Substitutes the supplied username, i.e. before eitherauthentication or LDAP transformation.

New in version 4.2.

When constructing the query URL, ensure that the order of LDAP parametersrespects RFC4516:

[ dn  [ ? [attributes] [ ? [scope] [ ? [filter] [ ? [Extensions] ] ] ] ] ]

If your query includes an attribute, mongoldap assumes that the queryretrieves a the DNs which this entity is member of.

If your query does not include an attribute, mongoldap assumesthe query retrieves all entities which the user is member of.

For each LDAP DN returned by the query, mongoldap assigns the authorizeduser a corresponding role on the admin database. If a role on the on theadmin database exactly matches the DN, mongoldap grants the user theroles and privileges assigned to that role. See thedb.createRole() method for more information on creating roles.

Example

This LDAP query returns any groups listed in the LDAP user object’smemberOf attribute.

"{USER}?memberOf?base"

Your LDAP configuration may not include the memberOf attribute as partof the user schema, may possess a different attribute for reporting groupmembership, or may not track group membership through attributes.Configure your query with respect to your own unique LDAP configuration.

If unset, mongoldap cannot authorize users using LDAP.

This setting can be configured on a running mongoldap using thesetParameter database command.

Note

An explanation of RFC4515,RFC4516 or LDAP queries is outof scope for the MongoDB Documentation. Please review the RFC directly oruse your preferred LDAP resource.