Percona Server for MongoDB LDAP Enhancements: User-to-DN Mapping

Automatic Role-Based Authorization by LDAP Comes to Percona Server for MongoDB (PSMDB)

In PSMDB 4.2.5-5, admins now have a way to leverage LDAP infrastructure to automatically assign database roles to LDAP-authenticated database users. The keyword is that LDAP Authorization has now been added alongside LDAP Authentication. The feature is in experimental status as of the current release.

When properly configured, it will also remove the current obligation to pre-create users in the dummy $external database. PSMDB directly authenticates the provided user name on the LDAP server. Nevertheless, the --authenticationDatabase connection argument will still need to be specified as $external . Here is a simple example using mongo shell:

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

More on LDAP Authorization configuration options will come in a future post.

With any LDAP authentication, there is a tricky point that user names must be expanded into LDAP Distinguished Names (DN). For those who are not familiar with DN, they are long, contain many parts, and are more or less impossible to memorize. The long, extra parts of a DN are mostly constant for users in the same group in your organization. From one company to the next it will vary though, and there may even be two or more different groups of users in your company with alternate DN patterns.

To make MongoDB simple to use with LDAP we must convert (or map) usernames to distinguished names suitable for LDAP. This name transformation is done with --ldapUserToDNMapping command line argument (or its configuration file equivalent security.ldap.userToDNMapping ). It provides a way to make the authorization configuration better as we will show below.

userToDNMapping

The userToDNMapping 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 user name. If that pattern matches, there are two ways to continue. If there is substitution value then it becomes the username of the user for further processing. If there is ldapQuery value it is sent to the LDAP server and the result of that LDAP query becomes the Distinguished Name (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, PSMDB tries to match each document against the provided name and if it matches it is replaced either with substitution string or with the result of the LDAP query.

Okay. Let’s see some examples!

The first example will be trivial, but for effective demonstration and explanation, we shouldn’t skip it. It is actually an edge case: how all this works if we authenticate users with DN and thus we don’t need any transformations.

In this case, we can just omit the --ldapUserToDNMapping parameter. When --ldapUserToDNMapping is not specified, then the server does not transform the provided user name. This is effectively the same as specifying --ldapUserToDNMapping with an all-matching regular expression and trivial substitution:

[
    {
        match: "(.+)",
        substitution: "{0}"
        # {0} placeholder corresponds to the first regex submatch
        # which is the whole input string in this case
    }
]

In fact, the above JSON document is the default value for the --ldapUserToDNMapping parameter.

For more examples, let’s look at Microsoft’s active directory servers. This popular implementation of LDAP allows us to authenticate users using the value of userPrincipalName attribute of the user’s object in AD server. For example in my test AD server, I have a user object with DN = cn=alice,cn=users,dc=engineering,dc=example,dc=com and that object has userPrincipalName attribute with alice@engineering.example.com value. AD server allows authentication with either alice@engineering.example.com or cn=alice,cn=users,dc=engineering,dc=example,dc=com as user name. Thus following two commands produce the same output on my testing machine (here I use OpenLDAP’s command line utility called ldapsearch to demonstrate binding to AD server):

ldapsearch -h 192.168.79.154 -p 389 -v -w alice -D alice@engineering.example.com -L -b DC=example,DC=com -s sub
ldapsearch -h 192.168.79.154 -p 389 -v -w alice -D CN=alice,CN=Users,DC=engineering,DC=example,DC=com -L -b DC=example,DC=com -s sub

The ldapsearch utility’s -D parameter in the above examples is used to provide binddn value to bind to the LDAP server. Despite its name in this configuration, we can use alice@engineering.example.com as the value, which is obviously not formatted as Distinguished Name. But to authorize user using LDAP directory we need a DN in most cases, and to resolve this incompatibility we can use --ldapUserToDNMapping parameter with following value (here and below examples are formatted as they would appear in YAML config files ):

security:
  ldap:
    userToDNMapping: >-
      [
        {
          match: "([^@]+)@engineering\\.example\\.com",
          substitution: "CN={0},CN=Users,DC=engineering,DC=example,DC=com"
        }
      ]

You can easily extend this pattern for the situation when you need to serve users from other departments:

security:
  ldap:
    userToDNMapping: >-
      [
        {
          match: "([^@]+)@engineering\\.example\\.com",
          substitution: "CN={0},CN=Users,DC=engineering,DC=example,DC=com"
        },
        {
          match: "([^@]+)@analytics\\.example\\.com",
          substitution: "CN={0},CN=Users,DC=analytics,DC=example,DC=com"
        },
        ...
      ]

Or you can craft a more generic substitution with the addition of second regex submatch:

security:
  ldap:
    userToDNMapping: >-
      [
        {
          match: "([^@]+)@([^\\.]+)\\.example\\.com",
          substitution: "CN={0},CN=Users,DC={1},DC=example,DC=com"
        }
      ]

User to DN mapping is pretty flexible, so as an alternative to the previous code we can use ldapQuery syntax to directly ask LDAP server to return DN of the object which has userPrincipalName equal to specified value:

security:
  ldap:
    userToDNMapping: >-
      [
        {
          match: "(.+)",
          ldapQuery: "dc=example,dc=com??sub?(&(objectClass=organizationalPerson)(userPrincipalName={0}))"
        }
      ]

Of course, doing a request to the LDAP server is much slower than transforming value using just substitution. So you should carefully consider all the pros and cons.

One more use case where you will probably need to use user to DN mapping is x.509 authentication . It is possible to configure PSMDB to use x.509 authentication and LDAP authorization together.

When PSMDB is configured to authenticate users with x.509 certificates, usernames are extracted from those certificates. Here are some examples of such usernames:

C=US,ST=New York,L=New York City,O=MongoDB,OU=Kernel,CN=server
CN=client,OU=KernelUser,O=MongoDB,L=New York City,ST=New York,C=US
CN=client,OU=devs,O=Percona,L=Osokorky,ST=Kyiv,C=UA

They look very similar to LDAP’s distinguished names, but generally, they are not necessarily exactly match corresponding DN. To enable LDAP authorization we can also use some kind of mappings. For example, substitution mapping like this:

security:
  ldap:
    userToDNMapping: >-
      [
        {
          match: "CN=(.+?),OU=(.+?),O=Example,L=New York City,ST=New York,C=US",
          substitution: "CN={0},CN=Users,DC={1},DC=example,DC=com"
        }
      ]

Or LDAP query mapping like this:

security:
  ldap:
    userToDNMapping: >-
      [
        {
          match: "CN=(.+?),OU=(.+?),O=Example,L=New York City,ST=New York,C=US",
          ldapQuery: "dc=example,dc=com??sub?(&(objectClass=organizationalPerson)(userPrincipalName={0}@{1}.example.com))"
        }
      ]

In Summary

User to DN mapping is a mysterious option at first glance, but it is just a string-transformation function. The transformation adds the longer, extra parts of an LDAP Distinguished Name so the users can log in without worrying about that.

Stay tuned for more info on new PSMDB features such as LDAP authorization ( security.ldap.authz.queryTemplate config option) and others.