.\" Man page generated from reStructuredText. . .TH "MONGOLDAP" "1" "Oct 24, 2019" "4.0" "mongodb-manual" .SH NAME mongoldap \- MongoDB LDAP Configuration Testing Utility . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SS On this page .INDENT 0.0 .IP \(bu 2 \fI\%Synopsis\fP .IP \(bu 2 \fI\%Usage\fP .IP \(bu 2 \fI\%Options\fP .UNINDENT .sp New in version 3.4: MongoDB Enterprise .SH SYNOPSIS .sp Starting in version 3.4, MongoDB Enterprise provides \fI\%mongoldap\fP for testing MongoDB\(aqs LDAP configuration options against a running LDAP server or set of servers. .sp To validate the LDAP options in the configuration file, set the \fI\%mongoldap\fP \fI\%\-\-config\fP option to the configuration file\(aqs path. .sp To test the LDAP configuration options, you must specify a \fI\%\-\-user\fP and \fB\-\-password\fP\&. \fI\%mongoldap\fP simulates authentication to a MongoDB server running with the provided configuration options and credentials. .sp \fI\%mongoldap\fP 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. .sp When configuring options related to LDAP authorization, \fI\%mongoldap\fP executes an LDAP query constructed using the provided configuration options and username, and returns a list of roles on the \fBadmin\fP database which the user is authorized for. .sp You can use this information when configuring LDAP authorization roles for user access control. For example, use \fI\%mongoldap\fP to ensure your configuration allows privileged users to gain the necessary roles to perform their expected tasks. Similarly, use \fI\%mongoldap\fP to ensure your configuration disallows non\-privileged users from gaining roles for accessing the MongoDB server, or performing unauthorized actions. .sp When configuring options related to LDAP authentication, use \fI\%mongoldap\fP to ensure that the authentication operation works as expected. .sp Run \fI\%mongoldap\fP from the system command line, not the \fBmongo\fP shell. .sp This document provides a complete overview of all command line options for \fI\%mongoldap\fP\&. .SH USAGE .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 A full description of LDAP or Active Directory is beyond the scope of this documentation. .UNINDENT .UNINDENT .sp Consider the following sample configuration file, designed to support LDAP authentication and authorization via Active Directory: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C security: authorization: "enabled" ldap: servers: "activedirectory.example.net" bind: queryUser: "mongodbadmin@dba.example.com" queryPassword: "secret123" userToDNMapping: \(aq[ { match : "(.+)", ldapQuery: "DC=example,DC=com??sub?(userPrincipalName={0})" } ]\(aq authz: queryTemplate: "DC=example,DC=com??sub?(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={USER}))" setParameter: authenticationMechanisms: "PLAIN" .ft P .fi .UNINDENT .UNINDENT .sp You can use \fI\%mongoldap\fP to validate the configuration file, which returns a report of the procedure. You must specify a username and password for \fI\%mongoldap\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongoldap \-\-config \-\-user "bob@dba.example.com" \-\-password "secret123" .ft P .fi .UNINDENT .UNINDENT .sp If the provided credentials are valid, and the LDAP options in the configuration files are valid, the output might be as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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: \&... .ft P .fi .UNINDENT .UNINDENT .SH OPTIONS .INDENT 0.0 .TP .B \-\-config , \-f Specifies a configuration file for runtime configuration options. The options are equivalent to the command\-line configuration options. See /reference/configuration\-options for more information. .sp \fBmongoldap\fP uses any configuration options related to security\-ldap or security\-ldap\-external for testing LDAP authentication or authorization. .sp Requires specifying \fI\%\-\-user\fP\&. May accept \fI\%\-\-password\fP for testing LDAP authentication. .sp Ensure the configuration file uses ASCII encoding. The \fBmongoldap\fP instance does not support configuration files with non\-ASCII encoding, including UTF\-8. .UNINDENT .INDENT 0.0 .TP .B \-\-user Username for \fBmongoldap\fP to use when attempting LDAP authentication or authorization. .UNINDENT .INDENT 0.0 .TP .B \-\-password Password of the \fB\-\-user\fP for \fBmongoldap\fP to use when attempting LDAP authentication. Not required for LDAP authorization. .UNINDENT .INDENT 0.0 .TP .B \-\-ldapServers :,:,...,: New in version 3.4: Available in MongoDB Enterprise only. .sp The LDAP server against which the \fBmongoldap\fP 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. .sp If your LDAP infrastructure partitions the LDAP directory over multiple LDAP servers, specify \fIone\fP LDAP server or any of its replicated instances to \fI\%\-\-ldapServers\fP\&. MongoDB supports following LDAP referrals as defined in \fI\%RFC 4511 4.1.10\fP\&. Do not use \fI\%\-\-ldapServers\fP for listing every LDAP server in your infrastructure. .sp This setting can be configured on a running \fBmongoldap\fP using \fBsetParameter\fP\&. .sp If unset, \fBmongoldap\fP cannot use LDAP authentication or authorization\&. .UNINDENT .INDENT 0.0 .TP .B \-\-ldapQueryUser New in version 3.4: Available in MongoDB Enterprise only. .sp The identity with which \fBmongoldap\fP binds as, when connecting to or performing queries on an LDAP server. .sp Only required if any of the following are true: .INDENT 7.0 .IP \(bu 2 Using LDAP authorization\&. .IP \(bu 2 Using an LDAP query for \fI\%username transformation\fP\&. .IP \(bu 2 The LDAP server disallows anonymous binds .UNINDENT .sp You must use \fI\%\-\-ldapQueryUser\fP with \fI\%\-\-ldapQueryPassword\fP\&. .sp If unset, \fBmongoldap\fP will not attempt to bind to the LDAP server. .sp This setting can be configured on a running \fBmongoldap\fP using \fBsetParameter\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Windows MongoDB deployments can use \fI\%\-\-ldapBindWithOSDefaults\fP instead of \fI\%\-\-ldapQueryUser\fP and \fI\%\-\-ldapQueryPassword\fP\&. You cannot specify both \fI\%\-\-ldapQueryUser\fP and \fI\%\-\-ldapBindWithOSDefaults\fP at the same time. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-ldapQueryPassword New in version 3.4: Available in MongoDB Enterprise only. .sp The password used to bind to an LDAP server when using \fI\%\-\-ldapQueryUser\fP\&. You must use \fI\%\-\-ldapQueryPassword\fP with \fI\%\-\-ldapQueryUser\fP\&. .sp If unset, \fBmongoldap\fP will not attempt to bind to the LDAP server. .sp This setting can be configured on a running \fBmongoldap\fP using \fBsetParameter\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Windows MongoDB deployments can use \fI\%\-\-ldapBindWithOSDefaults\fP instead of \fI\%\-\-ldapQueryPassword\fP and \fI\%\-\-ldapQueryPassword\fP\&. You cannot specify both \fI\%\-\-ldapQueryPassword\fP and \fI\%\-\-ldapBindWithOSDefaults\fP at the same time. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-ldapBindWithOSDefaults \fIDefault\fP: False .sp New in version 3.4: Available in MongoDB Enterprise for the Windows platform only. .sp Allows \fBmongoldap\fP to authenticate, or bind, using your Windows login credentials when connecting to the LDAP server. .sp Only required if: .INDENT 7.0 .IP \(bu 2 Using LDAP authorization\&. .IP \(bu 2 Using an LDAP query for \fI\%username transformation\fP\&. .IP \(bu 2 The LDAP server disallows anonymous binds .UNINDENT .sp Use \fI\%\-\-ldapBindWithOSDefaults\fP to replace \fI\%\-\-ldapQueryUser\fP and \fI\%\-\-ldapQueryPassword\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-ldapBindMethod \fIDefault\fP: simple .sp New in version 3.4: Available in MongoDB Enterprise only. .sp The method \fBmongoldap\fP uses to authenticate to an LDAP server. Use with \fI\%\-\-ldapQueryUser\fP and \fI\%\-\-ldapQueryPassword\fP to connect to the LDAP server. .sp \fI\%\-\-ldapBindMethod\fP supports the following values: .INDENT 7.0 .IP \(bu 2 \fBsimple\fP \- \fBmongoldap\fP uses simple authentication. .IP \(bu 2 \fBsasl\fP \- \fBmongoldap\fP uses SASL protocol for authentication .UNINDENT .sp If you specify \fBsasl\fP, you can configure the available SASL mechanisms using \fI\%\-\-ldapBindSASLMechanisms\fP\&. \fBmongoldap\fP defaults to using \fBDIGEST\-MD5\fP mechanism. .UNINDENT .INDENT 0.0 .TP .B \-\-ldapBindSASLMechanisms \fIDefault\fP: DIGEST\-MD5 .sp New in version 3.4: Available in MongoDB Enterprise only. .sp A comma\-separated list of SASL mechanisms \fBmongoldap\fP can use when authenticating to the LDAP server. The \fBmongoldap\fP and the LDAP server must agree on at least one mechanism. The \fBmongoldap\fP dynamically loads any SASL mechanism libraries installed on the host machine at runtime. .sp Install and configure the appropriate libraries for the selected SASL mechanism(s) on both the \fBmongoldap\fP 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. .sp If using the \fBGSSAPI\fP SASL mechanism for use with security\-kerberos, verify the following for the \fBmongoldap\fP host machine: .INDENT 7.0 .TP .B \fBLinux\fP .INDENT 7.0 .IP \(bu 2 The \fBKRB5_CLIENT_KTNAME\fP environment variable resolves to the name of the client keytab\-files for the host machine. For more on Kerberos environment variables, please defer to the \fI\%Kerberos documentation\fP\&. .IP \(bu 2 The client keytab includes a kerberos\-user\-principal for the \fBmongoldap\fP to use when connecting to the LDAP server and execute LDAP queries. .UNINDENT .TP .B \fBWindows\fP If connecting to an Active Directory server, the Windows Kerberos configuration automatically generates a \fI\%Ticket\-Granting\-Ticket\fP when the user logs onto the system. Set \fI\%\-\-ldapBindWithOSDefaults\fP to \fBtrue\fP to allow \fBmongoldap\fP to use the generated credentials when connecting to the Active Directory server and execute queries. .UNINDENT .sp Set \fI\%\-\-ldapBindMethod\fP to \fBsasl\fP to use this option. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For a complete list of SASL mechanisms see the \fI\%IANA listing\fP\&. Defer to the documentation for your LDAP or Active Directory service for identifying the SASL mechanisms compatible with the service. .sp 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. .sp For more information on SASL, defer to the following resources: .INDENT 0.0 .IP \(bu 2 For Linux, please see the \fI\%Cyrus SASL documentation\fP\&. .IP \(bu 2 For Windows, please see the \fI\%Windows SASL documentation\fP\&. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-ldapTransportSecurity \fIDefault\fP: tls .sp New in version 3.4: Available in MongoDB Enterprise only. .sp By default, \fBmongoldap\fP creates a TLS/SSL secured connection to the LDAP server. .sp For Linux deployments, you must configure the appropriate TLS Options in \fB/etc/openldap/ldap.conf\fP file. Your operating system\(aqs package manager creates this file as part of the MongoDB Enterprise installation, via the \fBlibldap\fP dependency. See the documentation for \fBTLS Options\fP in the \fI\%ldap.conf OpenLDAP documentation\fP for more complete instructions. .sp For Windows deployment, you must add the LDAP server CA certificates to the Windows certificate management tool. The exact name and functionality of the tool may vary depending on operating system version. Please see the documentation for your version of Windows for more information on certificate management. .sp Set \fI\%\-\-ldapTransportSecurity\fP to \fBnone\fP to disable TLS/SSL between \fBmongoldap\fP and the LDAP server. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Setting \fI\%\-\-ldapTransportSecurity\fP to \fBnone\fP transmits plaintext information and possibly credentials between \fBmongoldap\fP and the LDAP server. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-ldapTimeoutMS \fIDefault\fP: 10000 .sp New in version 3.4: Available in MongoDB Enterprise only. .sp The amount of time in milliseconds \fBmongoldap\fP should wait for an LDAP server to respond to a request. .sp Increasing the value of \fI\%\-\-ldapTimeoutMS\fP may prevent connection failure between the MongoDB server and the LDAP server, if the source of the failure is a connection timeout. Decreasing the value of \fI\%\-\-ldapTimeoutMS\fP reduces the time MongoDB waits for a response from the LDAP server. .sp This setting can be configured on a running \fBmongoldap\fP using \fBsetParameter\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-ldapUserToDNMapping New in version 3.4: Available in MongoDB Enterprise only. .sp Maps the username provided to \fBmongoldap\fP for authentication to a LDAP Distinguished Name (DN). You may need to use \fI\%\-\-ldapUserToDNMapping\fP to transform a username into an LDAP DN in the following scenarios: .INDENT 7.0 .IP \(bu 2 Performing LDAP authentication with simple LDAP binding, where users authenticate to MongoDB with usernames that are not full LDAP DNs. .IP \(bu 2 Using an \fBLDAP authorization query template\fP that requires a DN. .IP \(bu 2 Transforming the usernames of clients authenticating to Mongo DB using different authentication mechanisms (e.g. x.509, kerberos) to a full LDAP DN for authorization. .UNINDENT .sp \fI\%\-\-ldapUserToDNMapping\fP expects a quote\-enclosed JSON\-string representing an ordered array of documents. Each document contains a regular expression \fBmatch\fP and either a \fBsubstitution\fP or \fBldapQuery\fP template used for transforming the incoming username. .sp Each document in the array has the following form: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { match: "" substitution: "" | ldapQuery: "" } .ft P .fi .UNINDENT .UNINDENT .TS center; |l|l|l|. _ T{ Field T} T{ Description T} T{ Example T} _ T{ \fBmatch\fP T} T{ An ECMAScript\-formatted regular expression (regex) to match against a provided username. Each parenthesis\-enclosed section represents a regex capture group used by \fBsubstitution\fP or \fBldapQuery\fP\&. T} T{ \fB"(.+)ENGINEERING"\fP \fB"(.+)DBA"\fP T} _ T{ \fBsubstitution\fP T} T{ An LDAP distinguished name (DN) formatting template that converts the authentication name matched by the \fBmatch\fP regex into a LDAP DN. Each curly bracket\-enclosed numeric value is replaced by the corresponding \fI\%regex capture group\fP extracted from the authentication username via the \fBmatch\fP regex. .sp The result of the substitution must be an \fI\%RFC4514\fP escaped string. T} T{ \fB"cn={0},ou=engineering, dc=example,dc=com"\fP T} _ T{ \fBldapQuery\fP T} T{ A LDAP query formatting template that inserts the authentication name matched by the \fBmatch\fP regex into an LDAP query URI encoded respecting RFC4515 and RFC4516. Each curly bracket\-enclosed numeric value is replaced by the corresponding \fI\%regex capture group\fP extracted from the authentication username via the \fBmatch\fP expression. \fBmongoldap\fP executes the query against the LDAP server to retrieve the LDAP DN for the authenticated user. \fBmongoldap\fP requires exactly one returned result for the transformation to be successful, or \fBmongoldap\fP skips this transformation. T} T{ \fB"ou=engineering,dc=example, dc=com??one?(user={0})"\fP T} _ .TE .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 An explanation of \fI\%RFC4514\fP, \fI\%RFC4515\fP, \fI\%RFC4516\fP, or LDAP queries is out of scope for the MongoDB Documentation. Please review the RFC directly or use your preferred LDAP resource. .UNINDENT .UNINDENT .sp For each document in the array, you must use either \fBsubstitution\fP or \fBldapQuery\fP\&. You \fIcannot\fP specify both in the same document. .sp When performing authentication or authorization, \fBmongoldap\fP steps through each document in the array in the given order, checking the authentication username against the \fBmatch\fP filter. If a match is found, \fBmongoldap\fP applies the transformation and uses the output for authenticating the user. \fBmongoldap\fP does not check the remaining documents in the array. .sp If the given document does not match the provided authentication name, or the transformation described by the document fails, \fBmongoldap\fP continues through the list of documents to find additional matches. If no matches are found in any document, \fBmongoldap\fP returns an error. .INDENT 7.0 .INDENT 3.5 .SH EXAMPLE .sp The following shows two transformation documents. The first document matches against any string ending in \fB@ENGINEERING\fP, placing anything preceeding the suffix into a regex capture group. The second document matches against any string ending in \fB@DBA\fP, placing anything preceeding the suffix into a regex capture group. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 You must pass the array to \fI\%\-\-ldapUserToDNMapping\fP as a string. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C "[ { 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})" } ]" .ft P .fi .UNINDENT .UNINDENT .sp A user with username \fBalice@ENGINEERING.EXAMPLE.COM\fP matches the first document. The regex capture group \fB{0}\fP corresponds to the string \fBalice\fP\&. The resulting output is the DN \fB"cn=alice,ou=engineering,dc=example,dc=com"\fP\&. .sp A user with username \fBbob@DBA.EXAMPLE.COM\fP matches the second document. The regex capture group \fB{0}\fP corresponds to the string \fBbob\fP\&. The resulting output is the LDAP query \fB"ou=dba,dc=example,dc=com??one?(user=bob)"\fP\&. \fBmongoldap\fP executes this query against the LDAP server, returning the result \fB"cn=bob,ou=dba,dc=example,dc=com"\fP\&. .UNINDENT .UNINDENT .sp If \fI\%\-\-ldapUserToDNMapping\fP is unset, \fBmongoldap\fP applies no transformations to the username when attempting to authenticate or authorize a user against the LDAP server. .sp This setting can be configured on a running \fBmongoldap\fP using the \fBsetParameter\fP database command. .UNINDENT .INDENT 0.0 .TP .B \-\-ldapAuthzQueryTemplate New in version 3.4: Available in MongoDB Enterprise only. .sp A relative LDAP query URL formatted conforming to \fI\%RFC4515\fP and \fI\%RFC4516\fP that \fBmongoldap\fP executes to obtain the LDAP groups to which the authenticated user belongs to. The query is relative to the host or hosts specified in \fI\%\-\-ldapServers\fP\&. .sp Use the \fB{USER}\fP placeholder in the URL to substitute the authenticated username, or the transformed username if a \fI\%username mapping\fP is specified. .sp When constructing the query URL, ensure that the order of LDAP parameters respects RFC4516: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [ dn [ ? [attributes] [ ? [scope] [ ? [filter] [ ? [Extensions] ] ] ] ] ] .ft P .fi .UNINDENT .UNINDENT .sp If your query includes an attribute, \fBmongoldap\fP assumes that the query retrieves a the DNs which this entity is member of. .sp If your query does not include an attribute, \fBmongoldap\fP assumes the query retrieves all entities which the user is member of. .sp For each LDAP DN returned by the query, \fBmongoldap\fP assigns the authorized user a corresponding role on the \fBadmin\fP database. If a role on the on the \fBadmin\fP database exactly matches the DN, \fBmongoldap\fP grants the user the roles and privileges assigned to that role. See the \fBdb.createRole()\fP method for more information on creating roles. .INDENT 7.0 .INDENT 3.5 .SH EXAMPLE .sp This LDAP query returns any groups listed in the LDAP user object\(aqs \fBmemberOf\fP attribute. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C "{USER}?memberOf?base" .ft P .fi .UNINDENT .UNINDENT .sp Your LDAP configuration may not include the \fBmemberOf\fP attribute as part of the user schema, may possess a different attribute for reporting group membership, or may not track group membership through attributes. Configure your query with respect to your own unique LDAP configuration. .UNINDENT .UNINDENT .sp If unset, \fBmongoldap\fP cannot authorize users using LDAP. .sp This setting can be configured on a running \fBmongoldap\fP using the \fBsetParameter\fP database command. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 An explanation of \fI\%RFC4515\fP, \fI\%RFC4516\fP or LDAP queries is out of scope for the MongoDB Documentation. Please review the RFC directly or use your preferred LDAP resource. .UNINDENT .UNINDENT .UNINDENT .SH AUTHOR MongoDB Documentation Project .SH COPYRIGHT 2008-2019 .\" Generated by docutils manpage writer. .