Configure Ldap plugin

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.4/cli
Loaded Configuration File => /etc/php/7.4/cli/php.ini
$ nano /etc/php/7.4/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.

How to use?

Activate the plugin

The plugin is deactivated by default. You need to activate it to be able to use it.

To do so, simply copy the file /config/ldap.default.php into ldap.php.

cd /var/www/passbolt
mv ./config/ldap.default.php ./config/ldap.php

Configure the plugin

Edit the file ldap.php and modify the configuration to match your needs. The available options are:

'openldap' => [
  'user' => [
     'id' => 'entryUUID',
     'firstname' => 'firstName',
     'lastname' => 'lastName',
     'username' => 'mail',
     'created' => 'created',
     'modified' => 'modified',
  ],
  'group' => [
     'id' => 'entryUUID',
     'name' => 'cn',
     'created' => 'created',
     'modified' => 'modified',
     'users' => 'members',
  ],
],

'jobs' => [
    'users' => [
        'create' => true,
        'delete' => true,
    ],
    'groups' => [
        'create' => true,
        'update' => true,
        'delete' => true,
    ],
],

'ldap' => [
  'domains' => [
      // Active directory.
     'mydomain.local' => [
          'domain_name' => 'mydomain.local',
          'username' => 'johndoe',
          'password' => 'Compl!c4t3dP4ssw0rD',
          'base_dn' => 'OU=OrgUsers,DC=mydomain,DC=local',
          'servers' => ['35.225.111.241'],
          'port' => 389,
          'use_ssl' => false,
         'ldap_type' => 'ad',
      ],
   ],
]

Test the connection

Once the configuration options have been entered in ldap.php, you can test that the connection is working and that the objects are retrieved correctly from your directory:

./bin/cake directory_sync test

An output similar to the one below should be observed:

fig. Screenshot of directory synchronization test

What you should pay attention to:

• Make sure that you can see the same groups and users as the ones available in your directory.
• Make sure that each user has an email address. If not, they will not validate in passbolt.
• Make sure that each group is shown with the right number of users.

First synchronization

Before we actually do a real synchronization, we will first simulate one:

./bin/cake directory_sync all --dry-run

This command will simulate what will happen when the synchronization will be done for real.

fig. Screenshot of directory synchronization sync in dry run

If the result displayed is similar to what you expect to happen, you can proceed with the actual synchronization:

./bin/cake directory_sync all --persist

fig. Screenshot of directory synchronization running

Run it automatically

To synchronize the changes automatically you will need to add a cron job. 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 --persist" -s /bin/bash www-data >> /var/log/cron.log 2>&1

For debian and ubuntu systems where passbolt is installed through our supported packages:

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

Ignoring records

It is possible for you to individually ignore synchronization of some of your directory records and/or some users/groups in passbolt, especially when there are some problematics records you do not want to keep in sync. Such records and the command to ignore them will be displayed in the reports.

fig. Screenshot of directory synchronization with items to ignore

 ./bin/cake directory_sync ignore-create --id=55872084-ed6f-4e96-b401-479dd86ca357 --model=DirectoryEntries

You can also view all the records that are being ignored.

fig. Screenshot of directory synchronization view ignored command

./bin/cake directory_sync ignore-list

You can also stop ignoring them:

./bin/cake directory_sync ignore-delete --id=16789f75-2cf7-4755-9bd9-634d1ff42240 --model=DirectoryEntries