Configuring LDAP

LDAP configuration

After SAML is activated for a tenant, you have no other way to log in to Instana. The SAML configuration can be deleted through API by using a token with enough permissions.

To configure an LDAP (Lightweight Directory Access Protocol) connection, follow these steps:

1. Log in to the Instana user interface (UI).
2. Click Settings from the sidebar on the UI.
3. Click Authentication > LDAP and add the corresponding LDAP configuration values. See Supported authentication providers.
4. To persist the LDAP configuration, you must add a username and password in the **LDAP user account" section on the form. This user is added as owner, and you can change that after the initial setup.

After you configure LDAP, other users who match the group query are added to Instana with the default role. You can set the roles for each user as described in Role-based access control.

Instana fetches the roles and subsequent permissions for the currently authenticated user from your LDAP server. Users can't log in with their previous username and password combination: they must use their LDAP credentials.

Tips:

• For Self-Hosted Classic Edition (Docker), 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.

Supported authentication providers

Currently, Microsoft® Active Directory and OpenLDAP are supported.

• To integrate with Microsoft Active Directory, see the examples in Integrating with Microsoft Active Directory.

• To integrate with OpenLDAP, see the examples in Integrating with OpenLDAP.

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"

See the following description of the parameters:

• -H: LDAP server URL.
• -x: Use simple authentication (most LDAP servers 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 group search and user search.

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 does not return the correct values, Instana LDAP does not work.

If the following commands return the values, it means that the LDAP server is configured and has the corresponding data. Otherwise, the LDAP configuration and data must 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.

Accessing Instana UI

LDAP authentication is configured at the tenant level.

To log on to Instana with LDAP authentication, go to the login page or any other page on a tenant unit.

Note: If you access any page other than the login page on a tenant unit, you are redirected to the tenant login page.

The URL to log in is the following format: https://<unit name>-<tenant name>.<Instana domain>/

For example, if the unit is unit0, the tenant is tenant0, and the Instana domain is example.com, then the URL to log in would be https://unit0-tenant0.example.com/.

Glossary

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

A path name (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 wanted 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 given name of Christian and live in Solingen, you might use this query.

  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.