Help Search

Configure Ldap plugin

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

Important: If you have installed passbolt-pro using our debian and ubuntu packages you can skip this section

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?

Please note: This guide explains how to configure the Ldap connector through the configuration file. For simpler configurations, you can configure Ldap through the UI.

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.
[email protected]
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. [email protected]
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 --persist
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 --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.

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

Last updated

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

Are you experiencing issues with Passbolt Pro Edition?

Contact Pro support

or ask the community

🍪   Do you accept cookies for statistical purposes? (Read more) Accept No thanks!