11. LDAP setup - guide

11.1. Preface

It is possible to integrate Intella Connect with an external Lightweight Directory Access Protocol (LDAP) providers. The entire configuration can be done in the User Interface, however this task is not trivial and it requires a good level of knowledge of LDAP schemes.

Important

Configuring LDAP providers is considered an advanced task and should be undertaken only by a well qualified administrators. That is mainly because it impacts how passwords are sent between browsers and the server.

In order to allow Intella Connect to communicate with an LDAP database one must add a so called “provider”. Providers define the connection parameters to your LDAP database, as well as set of user defined queries which will control which LDAP entries can access Intella Connect. You can define as many Providers as you would like, however in most situations having just one would suffice. Any change in the providers list requires a full restart of Intella Connect server for the changes to take effect. It’s also up to the administrator to make sure that having multiple Providers will not result in having any name conflicts (where two accounts share the same username), as in such case results are unspecified.

Important

In order for changes in LDAP providers to take effect you must restart Intella Connect server.

11.2. LDAP connection parameters

First four provider settings that you will be asked for are listed below:

  • Name - is just a human friendly name that allows to manage providers better. It must be unique and it won’t be editable after you specify it.
  • Provider URL - it’s an URL pointing to your LDAP database, ex. ldap://192.168.1.1:10389
  • Authentication user DN - it’s a Distinguishable Name (DN) of the LDAP entry that will be used to make searches in your LDAP database. It must have enough privileged to perform LDAP lookups.
  • Authentication user password - simply a password for the user listed above

Those settings are essential for the Provider to communicate with an LDAP database.

11.3. Username Attribute (UA)

First thing to do next is to choose a so called username attribute (UA). All LDAP providers support “CN” attribute, but it’s not very user friendly to use this one as a username because it’s rather long and hard to remember. Users usually prefer signing in with either their email, or some simple username instead. Feel free to choose any attribute supported by your LDAP provider that uniquely identifies a user.

11.4. Customized LDAP queries

The rest of the wizard revolves around creating LDAP queries that specify how to determine which LDAP users should have access to Intella Connect. Those queries are explained below:

  • “Username to DN” query - Some LDAP providers will not return both DN and Username Attribute in the same record. That’s why Intella Connect allows to provide an auxiliary query which does the translation from UA to DN. This query is required even if UA is a part of your standard scheme that defines user record. In this case simply supply a query that returns user record for given username. It’s easy to understand on a working example: we would like users to log in to Connect using unique “email” attribute. We then fetch users from an Organizational Unit (OU) called “groupmembership” which only knows which user entries belong to it based on their DN. So we now must target additional OU called “users” to find what “email” does the given user have.
  • “DN to Username” query - This query is optional and usually won’t be needed with standard OpenLDAP and A.D. implementations. It does exactly the opposite for the previous query. Intella Connect will use it only in case when “All users accounts” query returns user accounts as a multi-value attribute.
  • “All users accounts” query - This is a query that should return all LDAP entries that you think should be entitled with an access to Intella Connect. Most probably those LDAP users are a part of some group defined in your schema. Therefore it’s usually enough to supply a query that would return all of users in this group. Depending on how your LDAP is organized, query might return multiple records (each representing single user) or just one record (where users are listed as a multi-value attribute). In the latter case you must provide an attribute name that will be used to pick up users’ DNs.
  • “Authentication query - First two queries allowed us to find which DNs can access Intella Connect and what human friendly username attribute should we use as their identifier. The third query is the most important one, because it will be used to authenticate user against an LDAP directory using credentials filled in on the login screen. You must make sure that this query returns exactly one entry for passed in username.

All of the queries listed above can use special, extended syntax.

11.5. Extended syntax

When defining some of the queries you can use standard LDAP syntax with one small extension. When you use special keywords described below, those will be replaced (string replacement) each time with runtime values passed in by the user. In case the value is unknown at the time of query evaluation it will return “NULL” string instead.

  • &&USERNAME_ATTRIBUTE&&: this string will be replaced with the name of a username attribute that you defined in Step 3 of the wizard.
  • &&USERNAME_VALUE&&: this string will be replaced with the value entered by the user on the Intella Connect login screen.
  • &&USER_DN&&: this string will be replaced with the value of user’s DN.

11.6. Using LDAPS

To use secure LDAP connection, is it required to provide proper protocol name (ldaps://) in the Provider URL while configuring LDAP provider through the wizard. If different port than default port is used for LDAPS, then port must be also provided in Provider URL.

The certificate issued to your LDAP server must be recognized as trusted. If you are using self-signed certificate, then you should add the certificate of your CA to the trusted keystore used by Intella Connect runtime (Java). This keystore is located in Intella Connect installation directory. Steps to do that would be the following:

  • Download and install auxiliary KeyStore Explorer application (http://keystore-explorer.org/downloads.html)
  • Make a backup of ‘cacerts’ file from the ‘jre/lib/security’ subfolder of your current Intella Connect installation.
  • Using KeyStore Explorer, open the ‘cacerts’ keystore file.
  • Install certificate of your CA only (CTRL + T).
  • Restart Intella Connect and use your LDAPS provider.

Note

Vound is not associated with developers of Keystore Explorer and we wish not to promote them. This guide serves explanatory purposes and should be treated as a learning material only. Vound cannot be held accountable for any misuse or damage that might be a result of using Keystore Explorer. If you feel uncertain if you should use it, please consult your IT specialists or keep on relying on keytool.

11.7. Sample config for OpenLDAP with memberof overlay

Below you will find a sample configuration for a custom database running on OpenLDAP with memberof overlay. It assumes that the user entries are stored in “users” OU and that Intella Connect users belong to a group named “cn=Intella Connect Users Group,ou=groupmembership,dc=vound-software,dc=com”.

Basic settings

  • Provider name: OpenLDAP test
  • Provider url: ldap://192.168.1.107:10389
  • Auth user DN: cn=admin,dc=vound-software,dc=com
  • Auth user password: SOME_PASSWORD

Query for getting single user details

  • Username attribute name: mail
  • Username to DN query Base: ou=users,dc=vound-software,dc=com
  • Username to DN query Filter: (&&USERNAME_ATTRIBUTE&&=&&USERNAME_VALUE&&)

Query for getting all user accounts

  • Query base DN: ou=users,dc=vound-software,dc=com
  • Query filter: (memberOf=cn=Intella Connect Users Group,ou=groupmembership,dc=vound-software,dc=com)

Query for authenticating single user

  • Query base DN: ou=users,dc=vound-software,dc=com
  • Query filter: (&(&&USERNAME_ATTRIBUTE&&=&&USERNAME_VALUE&&)(memberOf=cn=Intella Connect Users Group,ou=groupmembership,dc=vound-software,dc=com))

11.8. Sample config for Active Directory

Basic settings

  • Provider name: AD test
  • Provider url: ldap://192.168.56.2
  • Auth user DN: CN=admin,OU=ConnectUsers,OU=Users,OU=MyBusiness,DC=site,DC=local
  • Auth user password: SOME_PASSWORD

Query for getting single user details

  • Username attribute name: cn
  • Username to DN query Base: OU=ConnectUsers,OU=Users,OU=MyBusiness,DC=site,DC=local
  • Username to DN query Filter: (&&USERNAME_ATTRIBUTE&&=&&USERNAME_VALUE&&)

Query for getting all user accounts

  • Query base DN: OU=ConnectUsers,OU=Users,OU=MyBusiness,DC=site,DC=local
  • Query filter: (objectClass=person)

Query for authenticating single user

  • Query base DN: OU=ConnectUsers,OU=Users,OU=MyBusiness,DC=site,DC=local
  • Query filter: (&(&&USERNAME_ATTRIBUTE&&=&&USERNAME_VALUE&&)(memberOf=CN=Administrators,CN=Builtin,DC=site,DC=local))