Help Search

Configure Ldap plugin

ldap illustration

Important: the Ldap connector is currently distributed as an experimental plugin. Although it was tested with the greatest care, it is possible that some bugs are still present that could harm your passbolt installation. It is highly recommended not to use it in a production instance of passbolt.

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 the 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:

  • LDAP settings screen: it will be possible to configure and test ldap directly from an admin interface inside passbolt.
  • Report screens: the synchronization reports will be available in the admin user interface.

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:

Parameter Details Example
defaultUser
(required)
Enter 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
defaultGroupAdminUser
(required)
Enter 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
fieldsMapping
(optional)
In case of OpenLdap, the default mapping between the passbolt and directory record fields might not be the one that will work for you. In this section you can redefine the default mapping for your directory.
'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',
  ],
],
groupObjectClass
(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
userObjectClass
(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
groupPath
(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
userPath
(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
jobs
(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: see example
'jobs' => [
    'users' => [
        'create' => true,
        'delete' => true,
    ],
    'groups' => [
        'create' => true,
        'update' => true,
        'delete' => true,
    ],
],
ldap
(required)
This contains the ldap connection details such as the domain name, username, password, base DN, servers, port, etc.. The options in the config file are self explanatory.
'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:

Screenshot of directory synchronization test 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.

Screenshot of directory synchronization sync in dry run 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
Screenshot of directory synchronization running fig. Screenshot of directory synchronization running

Please note that a user can be added into a group only once his account is activated.

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" -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.

Screenshot of directory synchronization with items to ignore 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.

Screenshot of directory synchronization view ignored command 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

How to report bugs

You can contact us directly at contact@passbolt.com. Please mention [LDAP] in the subject so that we can prioritize your message correctly.

Last updated

This article was last updated on September 7th, 2018.

Are you experiencing issues with Passbolt Pro?

Contact Pro support

or ask the community