Configure LDAP

LDAP Authentication

On-Premises users have the option of provisioning authentication through OpenLDAP and Active Directory. Users authenticate against these third party providers, after which Instana fetches the roles and subsequent permissions for the now authenticated user. Once LDAP authentication is activated users cannot log in with their previous username & password combination, only the corresponding LDAP credentials are verified.

Users created through LDAP will be assigned the "default" role upon creation.

To use LDAP as the authentication method, you need to configure the corresponding config values in the Manangment Portal under Tenant Authentication. The configuration form is under the LDAP tab.

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



Configuring LDAP can be challenging. For more information, see our docs on how to configure LDAP to find the correct settings for LDAP.

Configuration Description
Url LDAP Server URL (ldap://host:389 or ldaps://host:636).
User/anonymouns The LDAP read only user. It needs to have sufficient rights to list groups through group_query or if you allow anonymous access for it.
Password Password for read only user.
Base The base for queries (dc=instana,dc=com).
Group Query The query to list a group or a set of groups with members having access to Instana (ou=Instana).
Group Member Field Name of the field containing DNs of users 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 (e.g. distinguishedName) which 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 only accepts an encryption stronger than what is provided by your Java 8 installation, cryptography extension need to be used. It can be downloaded from Oracle and configured as described on the JCE documentation page.

Currently Supported Authentication Provider

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"

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.


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

    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


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.


Now we need to find the actual user. Let's have a 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
    mail: [email protected]

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


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


  • 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, replace the values from the placeholders with the ones from the LDAP configuration on Instana and execute the two given searches.

It is very important to execute them with the exact values from the input and without extra parameters.

Both of them should work if the LDAP is correctly configured and the values are correct.

If one of the commands do not return the correct values, Instana LDAP will not work.

In case the command 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}"

    Should return the groups with instana access right. Without it, even if the user is present it will not be 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 user name replacing %s within the user_query_template, should return the specific user.

The user also needs to have the emailField attribute.


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



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



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.



The opposite of the first example.



Use the wildcard to search for anything



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