Help Search

Configure Ldap plugin

ldap illustration

Important: The Ldap plugin is part of Passbolt Pro only and is not available in the Community Edition.

Introduction

What is it?

The goal of the directory synchronization tool, 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.

Requirements

The directory synchronization tools requires the php-ldap extension to be present on the server. If you built your own server the way you install php-ldap will depend on your system flavor.

On Debian using nginx for example you can do:

sudo apt-get install php-ldap 
sudo service nginx restart

Make sure the ldap extension is present in the php-cli.ini file. You should add extension=ldap.so if it is not already present:

$ php -i |grep php\.ini
Configuration File (php.ini) Path => /etc/php/7.0/cli
Loaded Configuration File => /etc/php/7.0/cli/php.ini
$ nano /etc/php/7.0/cli/php.ini

For testing purpose, it might be handy to have some ldap utilities installed on your system. On Debian you can use ldapsearch for example to search for and display entries:

sudo apt-get install ldap-utils
ldapsearch -b'dc=example,dc=com' -x

The plugin relies on a 3rd party library called ldaptools which you will need to install as part of your passbolt update or install. You can get it the same way than other php dependencies using composer:

cd /var/www/passbolt
git pull origin master
composer install
./bin/cake passbolt migrate

To run, the ldap plugin needs to have at least one active admin user existing inside passbolt.

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.

How to use?

Please note: This guide explains how to configure the Ldap connector through the UI. For complex configurations (for example custom field mapping in openldap) you will need to configure ldap directly through the configuration file.

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”

Ldap directory settings screen (disabled) fig. Ldap directory settings screen (disabled)

Click on the switch next to “Users Directory” to enable the plugin.

Ldap directory settings screen (enabled) fig. Ldap directory settings screen (enabled)

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
(required)
Choose here the type of your directory. Currently only Active Directory and OpenLdap are supported. Active Directory
Domain
(required)
The domain your directory is configured with. mydomain.local
Server URL
(required)
The full url to reach your server. ldap://198.163.0.1:389
Username and password
(required)
Username and password to authentify on your directory
Base DN
(required)
The base DN (default naming context) for the domain. OU=OrgUsers,DC=mydomain,DC=local
Group path
(optional)
If your groups are located in a different path than your base DN, you can specify here the complementary path.

Default value: none
OU=MyGroups
User path
(optional)
If your users are located in a different path than your base DN, you can specify here the complementary path.

Default value: none
OU=MyUsers
Group object class
(optional)
For OpenLdap only, you can specify here the name of the group object class that you are using in your openldap.

Default value: groupOfUniqueNames
groupOfUniqueNames
User object class
(optional)
For OpenLdap only, you can specify here the name of the user object class that you are using in your openldap.

Default value: inetOrgPerson
inetOrgPerson
Default admin
(required)
Choose here the username of the passbolt admin user that will be used to perform the operations on behalf of the synchronization tools.

You can also create a dedicated admin user in passbolt if you want to be able to track more accurately the actions related to ldap.
passboltadmin@domain.com
Default group admin
(required)
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. passboltadmin@domain.com
Groups parent group
(optional)
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
(optional)
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
(optional)
Only for AD. Synchronize only the users that are enabled (=not disabled).
Sync operations
(optional)
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.

Default value: everything is enabled.

Save configuration

Once the configuration is entered, do not forgetto 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.

Ldap directory settings have been saved fig. Ldap directory settings have been saved

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.

Ldap directory sync simulation fig. Ldap directory sync simulation

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.

How to synchronize my directory automatically?

To synchronize the changes automatically you will need to add a cron job on your server. We recommend to execute the job once a day, but you can choose as per your preference.

0 0 * * * su -c "/var/www/passbolt/bin/cake directory_sync all" -s /bin/bash www-data >> /var/log/cron.log 2>&1

Last updated

This article was last updated on December 4th, 2018.

Are you experiencing issues with Passbolt Pro Edition?

Contact Pro support

or ask the community