Configuring LDAP

LDAP authentication

On-Premises users have the option of provision authentication through OpenLDAP and Active Directory. You can authenticate against these third-party providers after which Instana fetches the roles and subsequent permissions for the currently authenticated user. After LDAP authentication is activated, users can't log in with their previous username and password combination, only the corresponding LDAP credentials are verified.

Users who are created through LDAP are assigned the default role upon creation.

To use LDAP as the authentication method, follow the steps:

1. Click Settings from the sidebar on the Instana user interface.
2. Click Tenant Authentication, and configure the corresponding config values in the LDAP tab.

To persist the LDAP configuration, you need to enter a username and password at the end of the form. This user is added as owner, and you can change that after the initial setup. After this is configured and activated, other users who match the group query are added to Instana with the default role. You can set the roles by user as described in Access Control.

Tips:

• When you configure LDAP with Instana, make sure to enable the debugging mode of the component "butler" because the debugging information is chatty and can help you.

• LDAP is case-insensitive by default.

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"

Seee the following description of the parameters:

• -H: LDAP server URL.
• -x: Use simple authentication (most LDAP server use this authentication).
• -b: The base query.
• -D: The LDAP read-only user.
• -w: The password of the LDAP read-only user.

Important: LDAP paths are read from right to left. The LDAP search query returns a list of entries that start from the root.

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

    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

    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

Verifying your configuration

To verify your configuration, replace the values from the placeholders by using the ones from the LDAP configuration in the Instana UI, and run the following two given searches.

Note: It is important to run them with the exact values from the input and without extra parameters. Both of them can work if the LDAP is correctly configured and the values are correct.

If one of the commands doesn't return the correct values, Instana LDAP doesn't work.

If the following commands return the values, it means that the LDAP server is configured and have the corresponding data. Otherwise, the LDAP configuration and data needs to be checked.

• Group search

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

  It returns the groups with instana access right. Without it, even if the user is present, it is not possible for Instana to check the user membership.

• User search

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

  Where login is the provided username that replaces %s within the user_query_template. It returns the specific user.

  The user also needs to have the email field attribute.

Glossary

• cn: Common Name
• ou: Organization Unit
• dc: Domain Component
• dn: Distinguished Name

Note: A pathname (dn) is written from the last to the first element 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 straight forward.

• Equals

  (name=John)
  

  It returns everything where the name is equal John. 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 might use this query.

  Note: 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)
  

  This is the opposite of the first example.

• Wildcard

  (title=*)
  

Use the wildcard to search for anything:

• Combination

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

  It returns every user where the name is christian and who live in either Duesseldorf or Solingen.