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. LDAP sync objects of type "Activate/Deactivate Users" and "Test DN, Search Filter and Attributes" were introduced in version 15.200.312.

1. Introduction
2. LDAP Groups
3. LDAP Paged Searches
4. Enabling/disabling LDAP Sync
5. LDAP Sync objects
   • Add/update users objects
   • Delete users objects
   • Activate/deactivate users objects
   • Add/update groups and sync members
   • Delete groups objects
   • Test DN, Search Filter and Attributes objects
6. Enabling/disabling LDAP Sync objects
7. Deleting LDAP Sync objects
8. Testing LDAP Sync objects
9. Executing LDAP Sync objects
10. Automating LDAP Sync objects execution

1. 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).
• Activate or Deactivate LDAP users in Team Password Manager that match a filter 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).
• Test a DN, Search Filter and Attributes from 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.

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

2. LDAP Groups

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

LDAP groups are groups that 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 an 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.

3. 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 especially 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.

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

5. LDAP Sync Objects

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

• Add/update users.
• Delete users.
• Activate/deactivate users.
• Add/update groups and sync members.
• Delete groups.
• Test DN, search filter and attributes.

Note that LDAP sync objects of type "Activate/Deactivate Users" and "Test DN, Search Filter and Attributes" were introduced in version 15.200.312.

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 it connects to in order 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 an 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 an 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 an 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 is 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 a delete users object for an Active Directory:

Activate/deactivate users objects

Note: this type of object was introduced in version 15.200.312.

Activate/deactivate users objects allow you to activate or deactivate LDAP users that match a filter in an 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 in Team Password Manager, it's activated or deactivated (depending on the action configured). Note that if the user is already active or inactive, nothing is done.

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

Activate/deactivate 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. Examples:
  • Fetch the users from the TPM group: (&(objectCategory=person)(objectClass=user)(memberOf=CN=TPM,OU=Groups - Security,OU=Group Policy OU,DC=TPMAD,DC=local))
  • Fetch disabled users in Active Directory: (&(objectCategory=person)(objectClass=user)(userAccountControl:1.2.840.113556.1.4.803:=2))
  • Fetch enabled users in Active Directory: (&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))
• 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.
• Action: Activate or Deactivate.

Here you have an example of an activate/deactivate users object for an Active Directory. In this case, it deactivates LDAP users in Team Password Manager that are disabled in 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 an 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 an 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 an 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 an 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 is 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 a delete groups object for an Active Directory:

Test DN, Search Filter and Attributes objects

Note: this type of object was introduced in version 15.200.312.

Test objects allow you to retrieve LDAP entries from an LDAP/AD server and match attributes to them. They don't modify anything in Team Password Manager, they're only used for testing and debugging. They can only be tested, they cannot be executed (or automated) and they cannot be enabled or disabled.

They work like this:

1. Using a base DN and a search filter, entries are retrieved from the LDAP/AD server.
2. The attributes of the retrieved entries are compared to a list of attributes, and the ones that match are shown (the attribute and its value).

Test objects need the following configuration data to work:

• A Base Distinguished Name (Base DN): from which entries will be retrieved. Example: OU=Group Policy OU, DC=TPMAD, DC=local
• A Search Filter: a filter that specifies which entries to retrieve from the Base DN. Example (all objects): (objectClass=*)
• A list of attributes, each one separated by comma. The dn attribute is always included. Example: samaccountname, mail. If you want to get all the attributes, use this: *,+. If you leave this field empty, only the dn attribute will be compared.

Example usage

As you know, for LDAP/AD users to be imported (synced) into Team Password Manager, a username and email address are needed. Imagine you're testing an "Add/update users object" and a specific LDAP/AD user is not found. With a test object you can find out why this happens. You'd create a test object with these data:

• Base DN: the users base DN.
• Search Filter: a filter to get the user with any data you have about the user. For example, we know the username is ferran something, so we use ferran*: (&(objectCategory=person)(samaccountname=ferran*))
• Attributes: since the username and email are required, we'll enter them: samaccountname, mail. Another option would be to see all the attributes of the entry, like this: *,+.

This object, when tested, will return:

• Any entries that match the base DN and the search filter.
• The dn and attributes (and their values) of the attributes we've entered, if the entries have them.

This would be the result when testing this object. As you can see ferran.admin doesn't have the mail attribute, and that's why it couldn't be imported:

You can use these test objects for any kind of entries of the LDAP/AD server, not just users.

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

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

8. 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 recommended 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.

Note that testing a specific LDAP Sync object is different from using an LDAP sync object of type "Test DN, Search Filter and Attributes". Testing a specific LDAP Sync object tests its functionality, for example adding or updating users, while an object of type "Test DN, Search Filter and Attributes" is used to get entries from the LDAP/AD system that match a specific criteria.

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

9. 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 a URL as explained in the next section "Automating LDAP Sync objects execution".

10. 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).