Configuring LDAP

To configure LDAP, follow the steps:

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.



  • 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.

Currently supported authentication provider

Currently, Microsoft® Active Directory and OpenLDAP are supported.


Configuring LDAP can be challenging. To find the correct settings for LDAP in the Instana UI, see the following configuration explanations:

Configuration Description
Url LDAP Server URL (ldap://host:389 or ldaps://host:636).
Trust any certificate authorities whilst using ldaps When it's enabled, any Certificate Authority is trusted whilst using LDAP. It's required for untrusted Authorities or self-signed certificates.
Read only user has anonymous access to LDAP Decides whether read-only access requires authentication. If it's disabled, a user and their password need to be specified.
User The LDAP read-only user. It needs to have sufficient rights to list groups by using group_query. It's only required if anonymous access is insufficient.
Password Password for read-only user. It's only required if anonymous access is insufficient.
Base The base for queries (dc=instana,dc=com).
Group Query The query to list a group or a set of groups with members who have access to Instana (ou=Instana).
Group Member Field Name of the field that contains DNs of users who are listed through group_query (uniqueMember).
User Query Template Template to query the user, for instance (uid=%s).
Email Field The name of the field where to find the email address (mail).
User Dn Mapping (optional) The field (such as distinguishedName) that contains the users dn.
user_field (optional) The field where the users within the group are referenced by the value of this attribute (if no DN is used).
Owner Username The user to be related in instana as owner user. A login is tried as a test before the settings are saved.
Login Password The password of the Instana owner user.


Connecting through LDAPs can be as easy as providing ldaps://url:636. In case the server accepts only an encryption stronger than what is provided by your Java® 8 installation, the cryptography extension needs to be used. It can be downloaded from Oracle, and configured as described on the JCE documentation page.

By default, a self-signed certificate for the LDAP is expected, and therefore the Certificate Authority is not validated. The Certificate Authority validation can be turned on by unselecting the checkbox Trust any certificate authorities whilst using ldaps in the LDAP Configuration wizard.

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:// -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.

Group Query

First, search for the matching group where the desired users are members. In the following case, take the mathematicians as an example:

    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, use either cn=Mathematicians or ou=mathematicians.

User DN Mapping

Within the output, you can see the attribute uniqueMember. It is the distinguished name as it leads you to the users that are member of this group.

User Query Template

Now, you need to find the actual user. Look at a user from the output from the first query.

    dn: uid=euler,dc=example,dc=com
    objectClass: inetOrgPerson
    objectClass: organizationalPerson
    objectClass: person
    objectClass: top
    uid: euler
    sn: Euler
    cn: Leonhard Euler

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 that you see before, the email field is named mail, which is also the value of the Email Field setting.

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.


  • 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


    It returns everything where the name is equal John. Parentheses are included to emphasize the beginning and end of the LDAP statement.

  • AND


    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


    This is the opposite of the first example.

  • Wildcard


Use the wildcard to search for anything:

  • Combination


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