LDAP Sync

LDAP Sync allows you to manage LDAP users and groups (and LDAP groups membership) in your Team Password Manager installation in sync with your LDAP/AD server(s). LDAP Sync is a feature available in Team Password Manager since version 7.82.196.

• Introduction
• LDAP Groups
• LDAP Paged Searches
• Enabling/disabling LDAP Sync
• LDAP Sync objects
  • Add/update users objects
  • Delete users objects
  • Add/update groups and sync members
  • Delete groups objects
• Enabling/disabling LDAP Sync objects
• Deleting LDAP Sync objects
• Testing LDAP Sync objects
• Executing LDAP Sync objects
• Automating LDAP Sync objects execution

Introduction

With LDAP Sync you'll be able to:

• Create and update LDAP users in Team Password Manager from your LDAP server(s).
• Delete LDAP users in Team Password Manager that have been deleted in LDAP server(s).
• Create and update LDAP groups in Team Password Manager from your LDAP server(s).
• Sync LDAP groups membership from your LDAP server(s).
• Delete LDAP groups in Team Password Manager that have been deleted in LDAP server(s).

These actions can be executed manually or automated to be executed regularly.

All modifications in users and groups happen in Team Password Manager. Data from the LDAP server(s) is never modified, only read.

Even though the creation of LDAP users with LDAP Sync is the same as the current "Import LDAP Users" function (in Users | New User Options), we've decided to keep the "Import LDAP Users" function for two reasons: 1) you might only want to quickly import some LDAP users without having to create any LDAP Sync object, and 2) it provides a "debug mode" which is more detailed than the Test mode of the LDAP Sync objects.

You can manage LDAP Sync is via the "Users/Groups" top menu and then the "LDAP Sync" tab:

LDAP Groups

In version 7.82.196 of Team Password Manager we've created LDAP groups.

LDAP groups are groups than can only be managed (created, updated, deleted) using LDAP Sync. The only exception to this is that Admin users can delete them.

Their members can only be added or deleted by LDAP Sync too.

LDAP groups are listed and can be viewed in the groups section of Team Password Manager (User/Groups top menu, then the Groups tab), and you can filter them by their LDAP/AD server. Here's an example of a LDAP group:

Note: groups in Team Password Manager cannot be nested. So, while you can pull nested groups from LDAP (in Active Directory, for example using the LDAP_MATCHING_RULE_IN_CHAIN matching rule), they will be transformed to a flat structure once in Team Password Manager.

LDAP Paged Searches

Since v. 7.93.204 LDAP Sync uses LDAP paged searches by default. This means that when fetching items from the LDAP server (users, groups, etc.), LDAP sync will override any server size limit. This is specially important for Active Directory, which only allows 1000 items to be fetched at a time. With paged searches if you have, for instance, more than 1000 users, you'll get them all.

If you want to use the previous method, which limits the number of entries fetched from the LDAP server, you can by setting the LDAP_SYNC_PAGED_SEARCHES config.php parameter to FALSE. See how to use it here: LDAP_SYNC_PAGED_SEARCHES.

Enabling/disabling LDAP Sync

To be able to use LDAP Sync, you'll first have to enable it as it's disabled by default. To enable click the "Enable LDAP Sync" button:

You can disable LDAP Sync whenever you want by clicking the "Disable LDAP Sync" button. When LDAP Sync is disabled:

• LDAP Sync objects data are not deleted.
• LDAP Sync objects cannot be executed.

LDAP Sync Objects

LDAP Sync actions are performed using LDAP Sync objects, that can be of four types depending on the action performed:

• Add/update users.
• Delete users.
• Add/update groups and sync members.
• Delete groups.

To create an LDAP Sync object click the "New LDAP Sync Object" button. Then select the action in the next screen and click "Add" to proceed:

Each object has the following common data:

• The action being performed.
• LDAP/AD server, which is connecting to, to fetch users or groups.
• Login DN/Username and password (or anonymous) for the connection.
• Maximum number of LDAP entries that it can fetch (size limit). Note that this limit cannot override the server-side preset limit. Since v. 7.93.204, this datum is only available if you're not using LDAP paged searches.
• A field to enter some short notes.

Then, for each type of object, you'll have different configuration data depending on the action.

Once created, LDAP Sync objects can be edited, enabled or disabled, deleted, tested and executed.

Let's view each type of object in more detail.

Add/update users objects

Note: if you're using version 7.84.198 please apply this patch as it affects this type of object: Patch 7.84.198.331

Add/update users objects allow you to add new LDAP users or update existing LDAP users from a LDAP/AD server.

They work like this:

1. Using a base DN and a search filter, users are fetched from the LDAP/AD server.
2. If a fetched user is not in Team Password Manager, it's added.
3. If a fetched user is already in Team Password Manager (as an LDAP user in the same server), its data (name, email address, Login DN) are updated if it's needed.

User matching is done using the username of the user (case insensitive).

Add/update users objects need the following configuration data to work:

• A Base Distinguished Name (Base DN): from which users will be fetched. Example: OU=Group Policy OU, DC=TPMAD, DC=local
• A Search Filter: a filter that specifies which users to fetch from the Base DN. Example (this will fetch all the users): (&(objectCategory=person)(samaccountname=*))
• The following user attributes:
  • Username: the field in the LDAP entries where the username is stored for a user. This is an important field since it's the field used to match users in Team Password Manager. You can leave it empty if you want, but in this case, the email will be taken as the username. Typical examples of usernames fields are: samaccountname or cn.
  • Email: the field in the LDAP entries where the email address is stored for a user. The email address is required in Team Password Manager, so users in the LDAP entries without one will not be imported (synced).
  • Name 1 and Name 2: the fields in the LDAP entries where the first name and surname are stored for a user. Typical fields for these are: givenname and sn.
• Role: the role you want new users to have in Team Password Manager. Note that roles are only used for new users. Existing users will not change their role if the one set in the object is different from the one they have when the object is executed.

Here you have an example of an add/update users object for an Active Directory:

Delete users objects

Delete users objects allow you to delete LDAP users that no longer exist in a LDAP/AD server.

They work like this:

1. Using a base DN and a search filter, users are fetched from the LDAP/AD server.
2. This list of users is compared to the list of LDAP users in Team Password Manager for the configured LDAP server.
3. If a user in the Team Password Manager LDAP list of users is not present in the list of users fetched from the LDAP server, the user is deleted.

(In short, if a LDAP user in Team Password Manager is not in the LDAP server, it's deleted)

User matching is done using the username of the user (case insensitive).

Delete users objects need the following configuration data to work:

• A Base Distinguished Name (Base DN): from which users will be fetched. Example: OU=Group Policy OU, DC=TPMAD, DC=local
• A Search Filter: a filter that specifies which users to fetch from the Base DN. Example (this will fetch all the users): (&(objectCategory=person)(samaccountname=*))
• The following user attributes:
  • Username: the field in the LDAP entries where the username is stored for a user. This is an important field since it's the field used to match users in Team Password Manager. You can leave it empty if you want, but in this case, the email will be taken as the username. Typical examples of usernames fields are: samaccountname or cn.
  • Email: the field in the LDAP entries where the email address is stored for a user. The email address is required in Team Password Manager, so users in the LDAP system without one will not be considered when fetching users.

Important: deleting a user in Team Password Manager is irreversible. It will delete the user, any group membership and any permissions in passwords and projects. So, be careful when using this object. You might end up deleting users if you're not using a base dn/search filter that are broad enough to include all the users you want in the LDAP system (for example, because of users changing their position in the LDAP tree). Also, be sure to use the same attributes (username, email) you used in the add/update object when adding/updating users. In any case, test the object before executing it if you're not sure of the results.

Here you have an example of an delete users object for an Active Directory:

Add/update groups and sync members

Add/update groups and sync members objects allow you to add new LDAP groups or update existing LDAP groups and sync their membership from a LDAP/AD server.

Note: groups in Team Password Manager cannot be nested. So, while you can pull nested groups from LDAP (in Active Directory, for example using the LDAP_MATCHING_RULE_IN_CHAIN matching rule), they will be transformed to a flat structure once in Team Password Manager.

They work like this:

1. Using a base DN and a search filter, groups are fetched from the LDAP/AD server.
2. For each group, their members are fetched.
3. If a fetched group is not in Team Password Manager, it's added. Its members, if they're users in Team Password Manager, are added to the group too.
4. If a fetched group is already in Team Password Manager, its Group DN is updated if it's needed.
5. If a fetched group is already in Team Password Manager, its members are synced: they're added to the group or removed from the group in Team Password Manager.

Group matching is done using the name of the group and the usernames for its members (case insensitive in both cases).

Some notes regarding group membership syncing:

• Users are not added or deleted (or modified) in this object, only group membership is. Users are added to groups or removed from them, but user data remains intact.
• When adding members, if a user is not already present in Team Password Manager, it will not be added as a member of the group.

Example:

• Users in Group A in the LDAP server: tommy, amy, aaron, gemma
• Users in Group A in Team Password Manager: amy, aaron, john
• User tommy does not exist in Team Password Manager.
• User gemma exists in Team Password Manager.

When a add/update groups and sync members object is executed against this system, this will happen:

• The Group DN of Group A in Team Password Manager will be updated (if needed).
• Member john from Group A in Team Password Manager will be removed from the group.
• User tommy will not be added to the group in Team Password Manager because he doesn't exist in Team Password Manager.
• User gemma will be added to the group in Team Password Manager.

At the end of the execution, Group A in Team Password Manager will have these members: amy, aaron, gemma.

Add/update groups and sync members objects need the following configuration data to work:

• A Base Distinguished Name (Base DN): from which groups will be fetched. Example: OU=Group Policy OU, DC=TPMAD, DC=local
• A Search Filter: a filter that specifies which groups to fetch from the Base DN. Example (this will fetch all the groups that have a cn that begins with TPM): (&(objectCategory=group)(cn=TPM*))
• The group name attribute: the field in the LDAP entries where the group name is stored for a group. This is an important field since it's the field used to match groups in Team Password Manager. A typical example of group name field is: cn.

The previous data will fetch the groups from the LDAP server. Then, for each group, the following data is needed to fetch its members:

• A Members Base Distinguished Name (Members Base DN): from which members will be fetched. Example: OU=Group Policy OU, DC=TPMAD, DC=local (note that this is available since version 7.84.198)
• A Search Filter: a filter that specifies which users to fetch from the Members Base DN. To identify the group from which the members are fetched, we've created the following placeholder: [DN]. Whenever this placeholder is used in the filter, it will be replaced with the Group DN when the object is executed. Example: (&(objectCategory=person)(samaccountname=*)(memberof=[DN])). In this case, if the Group DN is, for instance CN=TPM IT,OU=Groups - Security,OU=Group Policy OU,DC=TPMAD,DC=local, then the resulting search filter will be: (&(objectCategory=person)(samaccountname=*)(memberof=CN=TPM IT,OU=Groups - Security,OU=Group Policy OU,DC=TPMAD,DC=local))
• The following user attributes:
  • Username: the field in the LDAP entries where the username is stored for a user. This is an important field since it's the field used to match users (in this case, members) in Team Password Manager. You can leave it empty if you want, but in this case, the email will be taken as the username. Typical examples of usernames fields are: samaccountname or cn.
  • Email: the field in the LDAP entries where the email address is stored for a user. The email address is required in Team Password Manager, so members in the LDAP entries without one will not be considered.

Here you have an example of an add/update groups object for an Active Directory:

Delete groups objects

Delete groups objects allow you to delete LDAP groups that no longer exist in a LDAP/AD server.

They work like this:

1. Using a base DN and a search filter, groups are fetched from the LDAP/AD server.
2. This list of groups is compared to the list of LDAP groups in Team Password Manager for the configured LDAP server.
3. If a group in the Team Password Manager LDAP list of groups is not present in the list of groups fetched from the LDAP server, the group is deleted.

(In short, if a LDAP group in Team Password Manager is not in the LDAP server, it's deleted)

Group matching is done using the name of the group (case insensitive).

Delete groups objects need the following configuration data to work:

• A Base Distinguished Name (Base DN): from which groups will be fetched. Example: OU=Group Policy OU, DC=TPMAD, DC=local
• A Search Filter: a filter that specifies which groups to fetch from the Base DN. Example (this will fetch all the groups that have a cn that begins with TPM): (&(objectCategory=group)(cn=TPM*))
• The group name attribute: the field in the LDAP entries where the group name is stored for a group. This is an important field since it's the field used to match groups in Team Password Manager. A typical example of group name field is: cn.

Important: deleting a group in Team Password Manager is irreversible. It will delete the group, any members and any permissions in passwords and projects. So, be careful when using this object. You might end up deleting groups if you're not using a base dn/search filter that are broad enough to include all the groups you want in the LDAP system (for example, because of groups changing their position in the LDAP tree). Also, be sure to use the same group name attribute you used in the add/update object when adding/updating groups. In any case, test the object before executing it if you're not sure of the results.

Here you have an example of an delete groups object for an Active Directory:

Enabling/disabling LDAP Sync objects

LDAP Sync objects are enabled by default, but you can disable them if you want. Disabled objects cannot be tested or executed, but remain defined in your Team Password Manager system. Just re-enable an object if you want to test or execute it.

To disable an object just click the "Disable" button and confirm. Do the same to enable it with the "Enable" button.

Deleting LDAP Sync objects

If you no longer need an LDAP Sync object you can delete it. Deleting an object will only delete its definition. If you executed it at some point, the log entries it generated are not deleted.

To delete an object just click the "Delete" button and confirm.

Testing LDAP Sync objects

Testing an LDAP Sync object simulates its execution. It will generate a screen showing what actions it would generate if executed but it will not do anything. It's recommeneded you test an object after creating it or if you're not sure of the results its execution would generate, but you can test it whenever you want.

To test an object just click the "Test" button and confirm. If you have many LDAP entries it may take a while.

Here's a sample output of a test on an Add/update groups object (the other types of objects have similar outputs):

Executing LDAP Sync objects

Executing an LDAP Sync object will make changes in Team Password Manager users or groups as defined. There are two ways to execute an object.

The first way to execute an object is from the object screen, clicking the "Execute" button and confirming it. If you have many LDAP entries it may take a while (more than the test if it needs to create/delete users or groups).

In this case, the object will be executed and an output similar to the one in Testing will be shown. Here's a sample output after executing an Add/update groups object (the other types of objects have similar outputs):

When an object is executed, it will log its actions in the Team Password Manager log. It will log a beginning and ending event and in between any actions that make changes in users or groups (for example, "Add user (LDAP Sync)").

The second way to execute an object is opening an URL as explained in the next section "Automating LDAP Sync objects execution".

Automating LDAP Sync objects execution

You can execute an LDAP Sync object by opening a URL without being logged in Team Password Manager. This URL, which is different for every object, can be found in the "Automate" tab of the object screen. Here's an example:

Note that opening this URL will not ask for confirmation and will not offer any kind of feedback (except if the URL is not found or other system errors). It will just execute the object, leaving traces in the Team Password Manager log.

This way of executing LDAP Sync objects was developed for the purpose of automating objects execution. You can do this using the curl command with any scheduler you have available (like cron, for instance).

Notes:

1. If you have many LDAP entries (users, groups, etc.) you may need to increase the value of max_execution_time, a PHP configuration parameter in php.ini (http://php.net/manual/en/info.configuration.php#ini.max-execution-time).
2. If you want to automate the execution of several objects, don't schedule them at the same time. It's better if they're executed one after the other.
3. The Team Password Manager user reported in the log and creation/update date of users/groups for objects executed this way is (system).