mirror of
https://github.com/mongodb/mongo.git
synced 2024-12-01 09:32:32 +01:00
858 lines
24 KiB
Groff
858 lines
24 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "MONGOLDAP" "1" "Jun 23, 2020" "4.4" "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\%Installation\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 INSTALLATION
|
|
.sp
|
|
The \fI\%mongoldap\fP tool is part of the \fIMongoDB Database Tools Extra\fP
|
|
package, and can be \fI\%installed with the MongoDB Server\fP or as a
|
|
\fI\%standalone installation\fP\&.
|
|
.SS Install with Server
|
|
.sp
|
|
To install \fI\%mongoldap\fP as part of a MongoDB Enterprise Server
|
|
installation:
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
Follow the instructions for your platform:
|
|
Install MongoDB Enterprise Server
|
|
.IP \(bu 2
|
|
After completing the installation, \fI\%mongoldap\fP and the other
|
|
included tools are available in the same location as the Server.
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 2.0
|
|
.INDENT 3.5
|
|
For the Windows \fB\&.msi\fP installer wizard, the
|
|
Complete installation option includes \fI\%mongoldap\fP\&.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Install as Standalone
|
|
.sp
|
|
To install \fI\%mongoldap\fP as a standalone installation:
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
Follow the download link for MongoDB Enterprise Edition:
|
|
\fI\%MongoDB Enterprise Download Center\fP
|
|
.IP \(bu 2
|
|
Select your Platform (operating system) from the dropdown
|
|
menu, then select the appropriate Package for your
|
|
platform according to the following chart:
|
|
.TS
|
|
center;
|
|
|l|l|.
|
|
_
|
|
T{
|
|
OS
|
|
T} T{
|
|
Package
|
|
T}
|
|
_
|
|
T{
|
|
\fILinux\fP
|
|
T} T{
|
|
\fBtgz\fP package
|
|
T}
|
|
_
|
|
T{
|
|
\fIWindows\fP
|
|
T} T{
|
|
\fBzip\fP package
|
|
T}
|
|
_
|
|
T{
|
|
\fImacOS\fP
|
|
T} T{
|
|
\fBtgz\fP package
|
|
T}
|
|
_
|
|
.TE
|
|
.IP \(bu 2
|
|
Once downloaded, unpack the archive and copy \fI\%mongoldap\fP to a
|
|
location on your hard drive.
|
|
.INDENT 2.0
|
|
.INDENT 3.5
|
|
.SS Tip
|
|
.sp
|
|
Linux and macOS users may wish to copy \fI\%mongoldap\fP to a filesystem
|
|
location that is defined in the \fB$PATH\fP environment variable, such
|
|
as \fB/usr/bin\fP\&. Doing so allows referencing \fI\%mongoldap\fP directly
|
|
on the command line by name, without needing to specify its full
|
|
path, or first navigating to its parent directory. See the
|
|
installation guide for your platform
|
|
for more information.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.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=<path\-to\-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=<filename>, \-f=<filename>
|
|
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=<string>
|
|
Username for \fBmongoldap\fP to use when attempting LDAP authentication or
|
|
authorization.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-password=<string>
|
|
Password of the \fI\%\-\-user\fP for
|
|
\fBmongoldap\fP to use when attempting LDAP authentication. Not
|
|
required for LDAP authorization.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-ldapServers=<host1>:<port>,<host2>:<port>,...,<hostN>:<port>
|
|
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=<string>
|
|
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=<string>
|
|
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=<bool>
|
|
\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=<string>
|
|
\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:
|
|
.TS
|
|
center;
|
|
|l|l|.
|
|
_
|
|
T{
|
|
Value
|
|
T} T{
|
|
Description
|
|
T}
|
|
_
|
|
T{
|
|
\fBsimple\fP
|
|
T} T{
|
|
\fBmongoldap\fP uses simple authentication.
|
|
T}
|
|
_
|
|
T{
|
|
\fBsasl\fP
|
|
T} T{
|
|
\fBmongoldap\fP uses SASL protocol for authentication.
|
|
T}
|
|
_
|
|
.TE
|
|
.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=<string>
|
|
\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=<string>
|
|
\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=<long>
|
|
\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=<string>
|
|
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: "<regex>"
|
|
substitution: "<LDAP DN>" | ldapQuery: "<LDAP Query>"
|
|
}
|
|
.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, \fBmongoldap\fP continues through the list of documents
|
|
to find additional matches. If no matches are found in any document,
|
|
or the transformation the document describes fails,
|
|
\fBmongoldap\fP returns an error.
|
|
.sp
|
|
Starting in MongoDB 4.4, \fBmongoldap\fP also returns an error
|
|
if one of the transformations cannot be evaluated due to networking
|
|
or authentication failures to the LDAP server. \fBmongoldap\fP
|
|
rejects the connection request and does not check the remaining
|
|
documents in the array.
|
|
.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=<string>
|
|
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
|
|
In the URL, you can use the following substituion tokens:
|
|
.TS
|
|
center;
|
|
|l|l|.
|
|
_
|
|
T{
|
|
Substitution Token
|
|
T} T{
|
|
Description
|
|
T}
|
|
_
|
|
T{
|
|
\fB{USER}\fP
|
|
T} T{
|
|
Substitutes the authenticated username, or the
|
|
\fBtransformed\fP
|
|
username if a \fI\%username mapping\fP is specified.
|
|
T}
|
|
_
|
|
T{
|
|
\fB{PROVIDED_USER}\fP
|
|
T} T{
|
|
Substitutes the supplied username, i.e. before either
|
|
authentication or \fBLDAP transformation\fP\&.
|
|
.sp
|
|
New in version 4.2.
|
|
T}
|
|
_
|
|
.TE
|
|
.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-2020
|
|
.\" Generated by docutils manpage writer.
|
|
.
|