How to Synchronize Users and Groups from a Directory
The LDAP connector will send an invitation email to all the users matching your configuration during a synchronization. If you are simply testing it, make sure not to perform an actual synchronization (use simulate sync instead), or disable the cron job to send emails first.
Introduction
What is the User Directory synchronization feature?
The goal of the directory synchronization feature, also called LDAP connector, is to provide a way for a passbolt administrator to synchronize a list of groups and users, as well as the associated group memberships.
Currently the connector supports two types of directory: OpenLDAP and Microsoft Active Directory. In the future we will also support other non ldap based user directories such as Google API User Directory.
How does it work?
In a nutshell this part of the application will try to keep passbolt and a directory in sync with a minimal involvement of the administrators and group managers. However if an action is not possible, such as, deleting a user that is the sole password owner, the process triggers will trigger relevant email notifications so that a human can solve it manually. An admin can also alternatively tell passbolt to ignore a record in the next synchronization round, if the issue does not need to be resolved.
Limitations
The LDAP plugin doesn't support nested groups in the current version. This improvement will be added later, once groups inside groups is supported by passbolt.
A delegated authentication (such as using a LDAP user password as replacement of the passphrase) is currently not supported (and is not a trivial problem) but could still be considered in the future. If you are interested in this feature you can join the discussion on the community forum.
The following improvements will also be shipped gradually and will be available soon:
- Test mode: the capability to test the configuration and mapping directly from the configuration screen.
- Report screens: the synchronization reports will be available in the admin workspace.
Setup guide
This guide explains how to configure the Ldap connector through the UI. More complex configurations (for example custom field mapping in openldap) can be achieved via file-based configuration. File based configuration and support is part of Enterprise services, please contact us for more information.
Activate the plugin
The plugin is deactivated by default. You need to activate it to be able to use it. While logged in as an admin, click on the administration menu item in the top menu, and then click on "Users Directory".
Click on the switch next to "Users Directory" to enable the plugin.
You will need to fill the configuration parameters with your connection details before you can save the settings and actually activate it.
Configure the plugin
The available options are:
| Parameter | Details | Example |
|---|---|---|
Directory Type | Choose here the type of your directory. Currently only Active Directory and OpenLdap are supported. | Active Directory |
Domain | The domain your directory is configured with. | mydomain.local |
Server URL | The full url to reach your server. | ldap://198.163.0.1:389 |
Username and password | Username and password to authentify on your directory | |
Base DN | The base DN (default naming context) for the domain. | OU=OrgUsers,DC=mydomain,DC=local |
Group path | If your groups are located in a different path than your base DN, you can specify here the complementary path.
| OU=MyGroups |
User path | If your users are located in a different path than your base DN, you can specify here the complementary path.
| OU=MyUsers |
Group object class | For OpenLdap only, you can specify here the name of the group object class that you are using in your openldap.
| groupOfUniqueNames |
User object class | For OpenLdap only, you can specify here the name of the user object class that you are using in your openldap.
| inetOrgPerson |
Default admin | Choose here the username of the passbolt admin user that will be used to perform the operations on behalf of the synchronization tools.
| [email protected] |
Default group admin | Choose here the username of the default group manager. It is the user that will be assigned as a group manager to all new groups created by ldap. | [email protected] |
Groups parent group | Using this filter will list only groups that are part of the given parent group (recursively). Enter the parent group name. | MyGroupName |
Users parent group | Using this filter will list only users that are part of the given parent group (recursively). Enter the parent group name. | MyGroupName |
Enabled users only | Only for AD. Synchronize only the users that are enabled (=not disabled). | |
Sync operations | By default, the synchronization will be done for all created / deleted users and groups in your directory and all edited group members. You can enable / disable some tasks here.
|
Save configuration
Once the configuration is entered, do not forget to save it by clicking on the "Save settings" at the top. The configuration will be saved only if passbolt managed to connect to your directory. If not, it will display an error message.
Test configuration and simulate sync
Once the settings have been saved, the buttons "Simulate synchronize" and "Synchronize" at the top have become clickable.
Before we actually do a real synchronization, we will first simulate one. Click on "Simulate synchronize" and wait a few seconds. Once the simulation is complete, a report such as the one below will be displayed.
In this report, you will be able to see what will actually happen when you will synchronize your directory for real. You will also be able to take corrective measures before an error actually happens.
First synchronization
To do the first synchronization, repeat the same process as above. Only, click on "Synchronize" this time. A similar report to the one that was displayed during a simulate will appear and let you know what happened exactly.
User synchronization example workflow
When an user is created in LDAP, they are imported in Passbolt using synchronization.
If you delete this user in Passbolt, he will remain present in LDAP but won't be added back to Passbolt on next synchronization.
If you want to re-sync this user with LDAP, manually re-create him in Passbolt then run synchronization. Passbolt synchronization tool will automatically recreate the link in Passbolt database.
If you delete this user in LDAP, he will be deleted from Passbolt on next synchronization.
Going further
How to synchronize my directory automatically?
If you want to automate the synchronization, you (or the person in charge of hosting) will need to setup a cron job.
Configure LDAP with SSL (LDAPS)
If your configuration doesn't run out of the box with LDAPS, you can refer to the LDAP with SSL documentation in order to adjust your config or throubleshoot your issue.