LDAP Configuration

Instana currently supports OpenLDAP and ActiveDirectory for our On-Premises customers. Configuring LDAP can be quite challenging. This guide should help with explaining how to use ldapsearch to find the correct configuration values.

The following guide is using the free LDAP server, provided by Forumsystems.

Configuration

The following is an example configuration needed to use forumsys as the ldap provider for Instana.

ldap:
  url: ldap://ldap.forumsys.com:389
  base: DC=example,DC=com
  group_query: (ou=mathematicians)
  group_member_field: uniqueMember
  user_dn_mapping:
  user_field:
  user_query_template: (uid=%s)
  email_field: mail
  ro_user: cn=read-only-admin,dc=example,dc=com
  ro_password: password

Description of configuration keys:

  • url: The url / port of the server to connect to
  • base: For each query, this base will be taken to make queries more readable
  • group_query: A user should be member of a group (eg. group dev). This lets Instana know in which group we should look for the specific user.
  • group_member_field: Within the group, the users are referenced by this attribute with a so-called “distinguished name”
  • user_dn_mapping: Within the user this “distinguished name” attribute is used to reference the user in the group
  • user_field: Within the group, the users are referenced by the value of this attribute (if not DN is used)
  • user_query_template: The query to retrieve the actual user with the provided login credentials
  • email_field: A unique reference to the mail attribute within the user object
  • ro_user: (read only) User to connect to the ldap server
  • ro_password: (read only) Password to connect to ldap server

Finding the correct configuration values

Starting with nearly no knowledge of the structure of the LDAP server, it is best to get an overview:

$ ldapsearch -H ldap://ldap.forumsys.com:389 -x -b "DC=example,DC=com" -D "cn=read-only-admin,dc=example,dc=com" -w "password"

Description of the parameters:

  • -H: ldap server url
  • -x: use simple authentication (most ldap server use this)
  • -b: base query
  • -D: ro_user
  • -w: ro_password (-W will ask for a pwd)

It is important to note that ldap paths will be read from right to left. The ldap search query from above will return a list of entries starting from the root.

Now that we have the output, we want the correct settings.

group_query

First let’s search for the matching group where the desired user(s) are members. In our case, we take the mathematicians.

    mathematicians, example.com
    dn: ou=mathematicians,dc=example,dc=com
    uniqueMember: uid=euclid,dc=example,dc=com
    uniqueMember: uid=riemann,dc=example,dc=com
    uniqueMember: uid=euler,dc=example,dc=com
    uniqueMember: uid=gauss,dc=example,dc=com
    uniqueMember: uid=test,dc=example,dc=com
    ou: mathematicians
    cn: Mathematicians
    objectClass: groupOfUniqueNames
    objectClass: top

To find this group, we could user either cn=Mathematicians or ou=mathematicians

user_dn_mapping

Within the output from above, we see the attribute “uniqueMember”. This is the distinguished name as this leads us to the user(s) that are member of this group.

user_query_template

Now we need to find the actual user. Let’s have a look at a user from the output from the first query.

    euler, example.com
    dn: uid=euler,dc=example,dc=com
    objectClass: inetOrgPerson
    objectClass: organizationalPerson
    objectClass: person
    objectClass: top
    uid: euler
    sn: Euler
    cn: Leonhard Euler
    mail: euler@ldap.forumsys.com

The (unique)Id of the user is euler, so the user_query_template is (uid=%s). (The %s in the user_query_template is used as a placeholder for the provided user login.)

email_field

In the snippet above, the email field is named “mail” which is also the value of the email_field setting.

Tips & Tricks

  • When configuring LDAP with Instana, make sure to enable the debug mode of the component “butler” as the debugs are chatty and should help
  • LDAP is case insensitive by default

Verify your configuration

In order to verify your configuration insert placeholders with your values and execute the two given searches.

  • group search

    $ ldapsearch -H {url} -x -D "{ro_user}" -w "{ro_password}" -b "{base}" "{group_query}"

    should return the groups with instana access right.

  • user search

    $ ldapsearch -H {url} -x -D "{ro_user}" -w "{ro_password}" -b "{base}" "{user_query_template=login}"

    where login is the provided user name replacing %s within the user_query_template, should return the specific user.

Glossary

  • cn: Common Name
  • ou: Organisation Unit
  • dc: Domain Component
  • dn: Distinguished Name
  • a pathname (dn) is written from the last to the first element from from right to left: cn=Christian Kellner,ou=dev,ou=employee,dc=instana,dc=com

LDAP query syntax

Sometimes it is necessary to specify a bit more complex queries to get the desired result. The query language is pretty straight forward.

Equals

(name=Christian)

This would return everything where the name is equal Christian. Parentheses are included to emphasize the beginning and end of the LDAP statement.

AND

(&(name=Christian)(l=Solingen))

Use this syntax when you have more than one condition and you want all conditions in the series to be true. For example, if you want to find all of the people that have the first name of Christian and live in Solingen, you could use this query.

Notice that each argument is in its own set of parentheses. The entire LDAP statement must be encompassed in a main set of parentheses. The & operator means that each argument must be true for this filter to apply to your object in question.

NOT

(!name=John)

The opposite of the first example.

Wildcard

(title=*)

Use the wildcard to search for anything

Combination

(&(name=Christian)(|(l=Solingen)(l=Duesseldorf)))

This would return every user where the name is christian and who live in either Duesseldorf or Solingen.