In Haiilo, different user directories can be connected. For example, you can choose between Active Directory and LDAP, both use the LDAP protocol. For connecting your user directories via Google Workspace or Microsoft Graph, there are only marginal differences to the LDAP protocol. You can find these differences in the linked articles.
In this article, we will guide you through the process of connecting an Active Directory. The directory service we will be using for this tutorial is Microsoft Active Directory. Kindly follow the instructions and tutorial video provided below.
General
Log in to Haiilo as administrator and open the administration. Click on the item "User directories". There you will see the user directory "Application database" as shown in the picture. This directory contains all local users that are created in Haiilo.
Click on "Create directory" to add a new user directory.
Then choose a name, the type "Active Directory" and activate the directory by checking the checkbox.
Connection
Next, it's about filling in the details in each tab. We start with the connection: Hostname, Port, Base DN, Username and Password are mandatory fields that must be filled in.
As hostname you enter the server that manages your user directory.
The default LDAP port is 389. The default port for encryptedSSL communication is port 636.
If you enable SSL, your AD server requires an officially signed certificate.
Note:
It is not possible to use a self-signed certificate in our Haiilo cloud.
An entry for AD domain is only necessary if you want to restrict access to Haiilo Home for a domain.
Example:
If you have different suffixes for your users' login names, for example. @coyo.com and @coyo.local, and you define "coyo.local" in this field, users with @coyo.com can log in more.
For each connection, the base distinguished name ("Base DN") must be entered. This indicates which area of your forest or tree you want to cover with the configuration.
Note:
Optionally, additional DNs can be specified in the following settings under "Users" and "Groups" to define more precisely which user accounts or group accounts are to be observed.
Under username the user directory requires a user who has sufficient read permission for the objects that will be synchronized (Bind DN). Haiilo Home will not change anything in your user directory and therefore does not need write permission.
The password of this username is necessary.
Clicking on "Test Connection" will check if your directory is accessible with these settings.
User
This tab defines which users are synchronized. Without settings, everything will be searched.
For more precise selection of users, define a additional user DN. This will be added to the previously configured base DN.
Defines user object class preferably in such a way that only the class "person" is searched for.
In addition to this selection, it is possible to work with an LDAP filter syntax via user object filter. This allows to consider only users for Haiilo Home who are members of a certain group. Also, users who are no longer members of this group are treated as orphaned users. More complex filters are also possible.
Note:
Due to the limitations of the LDAP protocol, wildcards cannot be used for DN attributes.
We recommend you to use only "objectGUID" as user unique ID, because this attribute is unique and does not change.
The rest of the attributes and profile fields are optional. We recommend you to use the default attributes to avoid problems.
Groups
In order to synchronize groups from a user directory, you must first activate synchronize groups.
Under Additional group DN enter the location that defines the groups and under group object class enter the class of groups to search for.
In the group object filter field you can specify an LDAP filter syntax to synchronize only certain groups.
Haiilo Home checks group unique ID and group displayname for group memberships. If both values are equal, the user will be assigned to this group. If you use OpenLDAP the field user attribute for group memberships must be specified.
Note:
Nested groups are not considered.
The remaining attributes are optional. We recommend that you use the default values.
Synchronization
In this tab you can make settings for synchronization.
The value in page size defines how many items should be synchronized per query. The LDAP protocol limit is 1000, so you should not choose a higher value.
Users can be stored in the directory as a reference to another domain or directory and with the follow referrals setting the references are taken into account. These references allow, for example, to partition a directory tree and distribute it among multiple LDAP servers. This means that LDAP servers may not store the entire directory information tree, but may still contain references to other LDAP servers that provide requested information instead.
Example:
So when Haiilo Home synchronizes with a directory, an LDAP server can refer you to another server by returning referrals. A referral is an entry with the referral objectClass that contains at least one attribute named ref that has an LDAP URL of the referred entry on another LDAP server as its value.
Note:
If your sync is timed out ("timeout error"), it may be because you are trying to follow a reference which is not accessible or you do not have enough permissions.
The activation option allows new and restored users to be activated during synchronization. Otherwise, you would have to manually set the status of the users to "Active" in the user management.
Note:
If you have enabled terms of use in administration, the new and restored users will remain on "Hidden" until they accept them.
With just-in-time sync, users are only created and user data synchronized when they log in. This setting makes sense if only users who log in are to be imported. For this, automatic synchronization should be disabled so that not all users already exist in Haiilo.
Orphaned users are users that currently exist as an active user, but no longer exist in the user directory. It is possible to ignore, disable or delete the users in Haiilo Home during sync.
The restore users option allows to reactivate deactivated or deleted users of Haiilo Home, if they are present again in the user directory during the sync.
Note:
It is not possible to restore anonymized users. The previously anonymized user can then only be created as a new user. Anonymization is disabled by default and can be enabled in the "General settings" of the administration.
Scheduling
Here you can configure the regularity of synchronization. You have the options once per day (at night), several times a day (every four hours) and once per hour.
FAQ
How can we securely connect a LDAP server to the Haiilo cloud?
In some environments, there will be security concerns about "sharing LDAP servers with a cloud". This is perfectly understandable, after all, the shared information concerns important data of your employees.
Infrastructurally, we cannot offer a VPN connection to our cloud, so here is a suggestion on how this can still be implemented with appropriate security:
LDAPS
In the cloud there is the possibility to use LDAPS (LDAP over SSL).
The requirement for this is:
- LDAPS: Your LDAP server can communicate encrypted.
- The SSL certificate must be from an official certificate authority
DMZ
You can also secure your network if you use a read-only domain controller in a DMZ for Haiilo Home, for example. Additionally, you can share the network of this DMZ only for the IP addresses of our cloud.
What can we do when we have problems establishing the connection?
java.net.ConnectException: Connection refused
Haiilo is unable to connect to the LDAP server because it is unable to resolve the path it can use to the LDAP/Active Directory server.
You should check and adjust this:
- There might be a reverse proxy blocking the connection.
- There might be a firewall between the servers blocking the port.
- Haiilo Home cannot resolve the LDAP server hostname correctly.
No subject alternative DNS name matching <hostname> found
Haiilo Home can check the hostname in the SSL certificate when communicating with an LDAP server via SSL. This means that the hostname used to connect to the LDAP server must match the one in the SSL certificate, otherwise Haiilo will not be able to connect to the directory.
Another possible cause of this problem is when the Synchronization > Follow References option is enabled in the user directory configurations when connecting to an LDAP directory.