In COYO, various user directories can be connected via LDAP. You can choose between Active Directory and LDAP, both use the LDAP protocol. The difference only lies in the values that are suggested for the attributes and the field "AD domain". There are only marginal deviations from the LDAP protocol for the connection of your user directories via the Google Workspace API or the MS Graph API. You can find these deviations in the linked articles.
We’ll run through the process of creating and connecting user directories with you using an example. For these instructions, we’re using Microsoft Active Directory, as it’s the best-known directory service.
Create a user directory
Log into COYO as an administrator and open the Administration. Click on the point "User directories". There, as shown in the picture, you’ll see the user directory "Application database". The directory contains all the local users that are created in COYO.
Click on "Create user directory" to add a new user directory.
Then choose a name, the type "Active Directory", and activate the directory by adding a tick in the checkbox.
Next, you need to fill the details in the individual tabs. We’ll begin with the connection: Host name, port, base DN, username and password are mandatory fields that need to be filled.
As a hostname, enter the server that your user directory manages.
The default LDAP port is 389. The default port for the encrypted SSL communication is port 636. If you activate SSL, your AD server needs an officially signed certificate.
It is not possible to use a self-signed certificate
in our COYO Cloud
. However, a self-signed certificate can be entered in the JVM of the backend container for COYO On-Premises
An entry for AD domains is not necessary if you want to restrict access to COYO for a domain.
If you have different suffixes for your users’ login names, e.g. @coyo.com and @coyo.local, and you define in this field "coyo.local", users can no longer log in with @coyo.com.
For each connection, the Base Distinguished Name ("Base DN") must be entered. This states which areas of a forest or trees you want to cover with the configuration.
Additional DNs can optionally be stated in the following settings under "Users" and "Groups" to precisely define which user accounts or group accounts should be taken into account.
Under usernames, LDAP requires a user that has sufficient read permissions for the objects that are synchronized (Bind DN). COYO won’t change anything in your user directory and so does not need write permissions. This user’s password is not necessary.
With a click on "Test connection", you test whether your directory can be reached with these settings.
This tab defines which users are synchronized. Without settings, everything is searched. As a result, define "Class of the user object" so that not only the class "person" is searched.
For the more precise selection of users, you define "Additional user DN". This is added in the base DN that has just been configured. In our example, this would now be "cn=Users,dc=coyoapp,dc=com".
In addition to this selection, "Filter the user object" can be used to work with an LDAP filter syntax. This allows only users to be taken into account for COYO, which e.g. are members of the group "COYO-GROUPS-ALL". You can find an example of this in this article.
Due to the restrictions of the LDAP protocol, wildcards for DN attributes cannot be used.
Users who no longer belong to this group are also treated as orphaned users. You can find out more about this further down in the article. More complex filters are also possible.
We recommend that you exclusively set the user ID as "objectGUID", as this attribute is unique and is not changed.
The rest of the attributes and profile fields can be chosen optionally. We recommend that you use the specified attributes to avoid problems.
In order to synchronize groups from the user directory, you first need to activate the checkbox "Synchronize groups".
In this example, we use the suggested values and an additional groups DN, which defines the place of the groups.
In the field "Filter for groups objects", we specify an LDAP filter syntax in order to only synchronize certain groups.
COYO checks "User attribute for group memberships" and "Groups ID". If both values are the same, the user is assigned to this group. In the case of our example, all groups starting with "COYO-GROUPS" are filtered.
Nested groups are not taken into account.
The rest of the attributes can be chosen optionally. We recommend that you use the specified values. If you use OpenLDAP, "User attribute for group memberships" must be stated.
On this tab, you can change the synchronization settings.
A value of 100 in "Page Size" defined that COYO synchronizes 100 elements per query. The limit of the LDAP protocol is 1000. As a result, you shouldn’t choose a higher value.
Users can be saved in the directory as a referral to another domain or to a directory; the referrals are taken into account with the setting "Follow referrals".
If your synch ends with a timeout ("timeout error"), this may be because attempts are made to follow a referral that isn’t accessible or insufficient permissions are present.
The checkbox "Activation"
makes it possible to activate new and restored users during synchronization
. Otherwise, you would need to manually set the status of the users in the user administration to "Active"
in Administration, the new and restored users remain "Hidden"
until they have accepted these terms.
In the case of "Just-in-time synchronization", the users are only created and the user data synchronized when they log in. This setting makes sense if only users who log in should be imported. In this case, automatic synchronization should be deactivated so that not all of the users exist in COYO.
"Orphaned users" are users who currently exist as active users in COYO but no longer exist in the LDAP directory. It’s possible to ignore, deactivate, or delete users.
The point "Restore users" makes it possible to reactivate deactivated or deleted users if they are present in the user directory again.
It’s not possible to restore anonymized users
. The previously anonymized users can then only be created as new users. Anonymization
is deactivated by default and can be activated in the "General settings"
Here you can configure the regularity of synchronization. You have the options once a day (at night), several times a day (every four hours) and once an hour.