This documentation is for the end of life version of Percona Server for MongoDB and is no longer supported. You may want to see the current documentation.

LDAP authorization

LDAP authorization allows you to control user access and operations in your database environment using the centralized user management storage – an LDAP server. You create and manage user credentials and permission information in the LDAP server. In addition, you create roles in the admin database with the names that exactly match the LDAP group Distinguished Name. These roles define what privileges the users who belong to the corresponding LDAP group.

Supported authentication mechanisms

LDAP authorization is compatible with the following authentication mechanisms:

• x.509 certificate authentication

• Kerberos Authentication

• Authentication and authorization with direct binding to LDAP

Authentication and authorization with direct binding to LDAP

Starting with release 4.2.5-5, you can configure Percona Server for MongoDB to communicate with the LDAP server directly to authenticate and also authorize users.

The advantage of using this mechanism is that it is easy to setup and does not require pre-creating users in the dummy $external db. Nevertheless, the --authenticationDatabase connection argument will still need to be specified as $external.

The following example illustrates the connection to Percona Server for MongoDB from the mongo shell:

mongo -u "CN=alice,CN=Users,DC=engineering,DC=example,DC=com" -p --authenticationDatabase '$external' --authenticationMechanism PLAIN

The following diagram illustrates the authentication and authorization flow:

1. A user connects to the db providing their credentials

2. If required, Percona Server for MongoDB transforms the username to match the DN in the LDAP server according to the mapping rules specified for the --ldapUserToDNMapping parameter.

3. Percona Server for MongoDB queries the LDAP server for the user identity and /or the LDAP groups this user belongs to.

4. The LDAP server evaluates the query and if a user exists, returns their LDAP groups.

5. Percona Server for MongoDB authorizes the user by mapping the DN of the returned groups against the roles assigned to the user in the admin database. If a user belongs to several groups they receive permissions associated with every group.

Username transformation

If clients connect to Percona Server for MongoDB with usernames that are not LDAP DN, these usernames must be converted to the format acceptable by LDAP.

To achieve this, the --ldapUserToDNMapping parameter is available in Percona Server for MongoDB configuration.

The --ldapUserToDNMapping parameter is a JSON string representing an ordered array of rules expressed as JSON documents. Each document provides a regex pattern (match field) to match against a provided username. If that pattern matches, there are two ways to continue:

• If there is the substitution value, then the matched pattern becomes the username of the user for further processing.

• If there is the ldapQuery value, the matched pattern is sent to the LDAP server and the result of that LDAP query becomes the DN of the user for further processing.

Both substitution and ldapQuery should contain placeholders to insert parts of the original username – those placeholders are replaced with regular expression submatches found on the match stage.

So having an array of documents, Percona Server for MongoDB tries to match each document against the provided name and if it matches, the name is replaced either with the substitution string or with the result of the LDAP query.

LDAP referrals

As of version 4.2.10-11, Percona Server for MongoDB supports LDAP referrals as defined in RFC 4511 4.1.10. For security reasons, referrals are disabled by default. Double-check that using referrals is safe before enabling them.

To enable LDAP referrals, set the ldapFollowReferrals server parameter to true using the setParameter command or by editing the configuration file.

setParameter:
   ldapFollowReferrals: true

Connection pool

As of version 4.2.10-11, Percona Server for MongoDB always uses a connection pool to LDAP server to process bind requests. The connection pool is enabled by default. The default connection pool size is 2 connections.

You can change the connection pool size either at the server startup or dynamically by specifying the value for the ldapConnectionPoolSizePerHost server parameter.

For example, to set the number of connections in the pool to 5, use the setParameter command:

Command lineConfiguration file:

$ db.adminCommand( { setParameter: 1, ldapConnectionPoolSizePerHost: 5  } )

Support for multiple LDAP servers

As of version 4.2.12-13, you can specify multiple LDAP servers for failover. Percona Server for MongoDB sends bind requests to the first server defined in the list. When this server is down or unavailable, it sends requests to the next server and so on. Note that Percona Server for MongoDB keeps sending requests to this server even after the unavailable server recovers.

Specify the LDAP servers as a comma-separated list in the format <host>:<port> for the –ldapServers option.

You can define the option value at the server startup by editing the configuration file.

security:
  authorization: "enabled"
  ldap:
    servers: "ldap1.example.net,ldap2.example.net"

You can change ldapServers dynamically at runtime using the setParameter.

$ db.adminCommand( { setParameter: 1, ldapServers:"localhost,ldap1.example.net,ldap2.example.net"} )
{ "was" : "ldap1.example.net,ldap2.example.net", "ok" : 1 }

See also

MongoDB Documentation:

• Authenticate and Authorize Users Using Active Directory via Native LDAP

• LDAP referrals

Configuration

For how to configure LDAP authorization with the native LDAP authentication, see Setting up LDAP authentication and authorization using NativeLDAP.