LDAP / Active Directory – iceScrum

Documentation This documentation applies only to iceScrum v7.
For old iceScrum R6, read the documentation or migrate.

Authenticate your users through LDAP/AD.


Unlike most Apps, this App is server-wide. That means that it cannot be used on iceScrum Cloud. Otherwise, if your license includes it, then it will available automatically.

There are two types of users in iceScrum, depending on their authentication mode:

  • Internal: regular iceScrum users. They are authenticated only according to their user / password registered in iceScrum. Users created through the register form or from the user administration panel are internal by default.
  • External: users that can authenticate only through an external service such as LDAP. If the external authentication fails, they can’t log in. When a new user successfully logs in into iceScrum for the first time through the external service, the corresponding iceScrum external user is created from their attributes: username, first name, last name and email address. Consequently, there is no need for the administrator to create them manually. Their email address and their password cannot be modified from iceScrum.

Permissions for external users are managed through the usual iceScrum team wizard, they cannot be managed from the external service (e.g. LDAP groups).

Each time an external user logs in successfully, its iceScrum attributes are updated from their external attributes.

Note that iceScrum never writes in your external service and that external passwords are never stored in iceScrum.

User type (internal / external) can be changed by the administrator at any time. This can be used to migrate an existing internal user base to an external authentication service. Refer to the user administration documentation for more information.

For LDAP / AD, authentication is achieved by a bind operation. However, a search is required prior to the bind in order to retrieve the user Distinguished Name (DN).


You need to log in as administrator in order to configure the LDAP connection. You will find the LDAP settings in the “Settings” menu.

  • Enable: Enable or disable the LDAP feature for the iceScrum server.
  • Server URL: Full URI of the LDAP server (example : ‘ldap://localhost:389’).
  • Search base: Context name to search in, e.g. dc=example,dc=com or ou=users,dc=example,dc=com.
  • Search filter: The filter expression used in the user search. For AD, use sAMAccountName={0}.
  • Search subtree: If checked, search the entire subtree as identified by context, otherwise only search the level identified by the search base.
  • First name attribute: LDAP attribute used to populate the external user first name.
  • Last name attribute: LDAP attribute used to populate the external user last name.
  • Email attribute: LDAP attribute used to populate the external user email.
  • Anonymous connection: Use anonymous connection instead of Manager credentials (possible because the LDAP operations are read-only).
  • Manager Dn: DN of a user having sufficient rights to search the LDAP directory. Required if you don’t allow anonymous connection.
  • Manager password: Required if you don’t allow anonymous connection.

A restart is needed in order for these settings to be taken into account. Use the Test button to check if the connection to your LDAP server is successful before restarting.

If you want to use LDAP over SSL:

  • Use the ldaps scheme in the server URL
  • Use the appropriate port in the server URL (usually 636)

If your SSL certificate is not recognized then:

  • Import the certificate chain in the trustStore of the iceScrum server
  • Add the path to the trustStore in the JVM system properties (usually defined in CATALINA_OPTS):

Please note that TLS is not supported.


Detailed logs about LDAP authentication can be obtained by enabling verbose logging for security. Refer to the server administration documentation.

If user authentication through LDAP doesn’t work, ensure that:

  • Your configuration has been taken into account (a restart is required). You can check in the verbose logs that the search base used when a user tries to authenticate is the one you defined.
  • The iceScrum server has access to the LDAP server (proxy, firewall, ports).
  • An LDAP search with the given search base and filter works outside iceScrum (anonymous or based on the user credentials given in the configuration).

Try it for free now
All you need for your Agile project management