Directory Synchronization - Comprehensive Guide KB500 - OpenLM Software License Management
Israel +972 4 6308447         USA +1 619 831 0029              JAPAN +81 505 893 6263 担当:萩原

Directory Synchronization – Comprehensive Guide KB500

This is a comprehensive guide on how to synchronize the OpenLM Database with an organization’s directory service using the Directory Synchronization Service (DSS) and Directory Synchronization Agent (DSA) components. For a quick-start guide, check out this article instead.

 

Table of Contents:

1. Overview

2. Requirements

2.1. Port configuration

3. Install

3.1. Directory Synchronization Service

3.2. Directory Synchronization Agent

4. Configure

4.1. Directory Synchronization Service

4.2. Migrate OpenLM Server v4 LDAP sync definitions

4.3. DSS Configuration tools

DB Configuration

DB Upgrade

5. Usage

5.1. Agent Manager

5.1.1. Approve a new agent

5.1.2. Edit an agent’s properties

5.1.3. Edit agent properties in bulk

5.1.4. Delete an agent

5.2. Domain Manager

5.2.1. Add a new sync domain

5.2.2. Edit a domain’s properties

5.2.3. Delete a domain

5.3. Sync Manager

5.3.1. Add a new sync definition

Destination & Time tab

Object tab

Group Rules tab

Set as default group checkbox

5.3.2. Manually trigger a synchronization

5.3.3. Reset entity relationship data

5.3.4. Delete a sync definition

5.4. Entities

5.4.1. Ignore an entity from all synchronizations

5.4.2. Manually synchronize an entity

5.4.3. View entity relationships

5.5. Relations

5.5.1. Ignore an entity from a specific synchronization

 

1. Overview

OpenLM provides functionality for synchronizing the OpenLM database with user information from a domain directory (e.g. ActiveDirectory). This is accomplished using the Directory Synchronization Service (DSS) and Directory Synchronization Agent (DSA) components.

Previously, this functionality was named LDAP Synchronization and was part of OpenLM Server. In order to improve performance and stability, this functionality was split from Server and divided into two separate components: DSS and DSA.

Both components require to be installed for LDAP synchronization.

Architecture overview:

  1. DSS connects to OpenLM Server directly. It can be installed on the same machine as OpenLM Server or a separate one. The function of the DSS is to store the sync definitions and manage the DS Agents.
  2. One or more DSAs connect to the DSS. DSA can be installed on the same machine as DSS or a separate one. Its function is to take the sync definitions from DSS, query the domain directory and report the data back to DSS.
  3. Once DSS has received this data from DSA, it sends it back to OpenLM Server.

Note: A single DSA can be used to query multiple directories (i.e. both AD and eDirectory). This diagram illustrates only one of many possible configurations where two separate DSAs can be used.

 

2. Requirements

  1. OpenLM Server v5 or higher.
  2. A license file that has support for the Directory Synchronization extension (contact sales@openlm.com if unsure).
  3. If installing DSS and DSA on a machine separate from OpenLM Server, make sure that the machine is on the same network as the domain controller.

 

2.1. Port configuration:

Port 8081 must be free when installing DSA. If it is occupied and you get an error during the installation stage, edit the kestrel.config file in the DSA installation folder (C:\Program Files (x86)\OpenLM\OpenLM Directory Synchronization Agent), change the port number and restart the Directory Synchronization Agent service.

Additionally, if installing DSS and DSA on separate machines from OpenLM Server, you will have to make sure that proper firewall rules are set for the application ports:

  1. OpenLM Server machine: inbound for 5015, outbound for 7026
  2. DSS machine: both inbound and outbound for 7026
  3. DSA machine: outbound for 7026

 

 

3. Install

3.1. Directory Synchronization Service

1. Get the latest version of DSS from the OpenLM Downloads page. Double-click to run the installer.

2. Check the “I agree to the license terms and conditions” box and click Next.

3. You can change the installation folder if you want. Additionally, if checked, the “Create a desktop icon” box will place a shortcut to the DSS web-interface on your desktop. Click Next.

4. Enter the login details for the user that will be created to access the Directory Synchronization Service then click Next.

Password requirement: at least 8 characters and must contain at least one lowercase letter + one uppercase letter + one special character + one number.

Note: this user is created solely for administering DSS and is not related to the OpenLM Server administrator user.

5. Once setup is complete, click Finish. This will close the Setup Wizard and open the DSS user interface in your browser.

Note: to start using DSS, you will also need to install at least one instance of DSA (instructions below). Once that is done, proceed to the “Configuring” section to finish setup.

 

3.2. Directory Synchronization Agent

1. Get the latest version of DSA from the OpenLM Downloads page. Double-click to run the installer.

2. Check the “I agree to the license terms and conditions” box and click Next.

3. Enter a descriptive name to recognize the Agent instance and the details of the DSS installation (found in the DSS UI → Service Configuration tab under DSS Server). Click Next.

4. You can change the installation folder if you want. Enter the path or click Browse then click Next when done.

5. Once setup is complete, click Finish. At this point, a DSA approval request will have been sent to the DSS. You need to open the DSS user interface and go to the Agent Manager tab to approve it, as described in section 5.1.1.

 

4. Configure

4.1. Directory Synchronization Service

Before DSS is operational, you have to finish its configuration. To do so:

1. Open the DSS user interface. This will either happen automatically when you click Finish on the DSS installer or by going to Windows Start → OpenLM → OpenLM Directory Synchronization Service.

2. Enter your login credentials and click Login. Alternatively, you can click Continue without logging in to access the UI in restricted mode. The tabs required for DSS configuration will still be accessible.

3. On the left menu, click on the Service Configuration tab.

4. Fill in the details as follows:

Illustration: default settings for OpenLM Server and DSS installed on the same machine

OpenLM Server:

  • IP/Hostname – the URL of the OpenLM Server machine that DSS will connect and report to. If HTTPS/SSL is turned on for OpenLM Server, make sure that the hostname here is exactly as it appears on the SSL certificate.
  • Port – the API port of the OpenLM Server (default: 5015)

DSS Server

  • IP/Hostname – the URL of the DSS server that will be reported to the OpenLM Server machine. If you have installed DSS on a machine different from OpenLM Server, specify its address. If using SSL, make sure the hostname is exactly as it’s reflected on the certificate file.
  • Port – the port through which the DSS UI is served (default: 7026). By default, this field is read-only. To change, edit kestrel.config in C:\Program Files (x86)\OpenLM\OpenLM Directory Synchronization Service\ and restart the Directory Synchronization Service.
  • SSL – toggle to either enable or disable HTTPS for the DSS communications port. If turned on, you will also have to specify the SSL certificate file (pfx) and the Password for the SSL certificate. DSA connection settings will also have to be adjusted by editing the OpenLM.Ldap.Agent.config file in the DSA installation folder.

 

5. Click Apply to finalize the configuration. This will send a connection request to OpenLM Server.

6. Open EasyAdmin (Windows Start → OpenLM → OpenLM EasyAdmin User Interface).

7. Go to EasyAdmin Start → Administration then click on External Platforms.

8. Click on the DSS tab on the left then click on Approve.

9. You should see a success message confirming that the connection to DSS has been established successfully.

At this point, the connection between OpenLM Server and DSS is established:

a) If you have any previous LDAP sync definitions, you must decide what to do with them before you can add new domains and configure new sync definitions. Consult section 4.2. below to continue.

b) If you don’t have any previous LDAP sync definitions stored, configuration is now complete. You will have to add at least one DSA instance before you can start adding domains and sync definitions as described in section 5.

 

4.2. Migrate OpenLM Server v4 LDAP sync definitions

Existing LDAP sync definitions from OpenLM Server versions prior to version 5 can be migrated once the DSS and DSA components have been installed. The migration wizard will appear automatically on the first configuration of DSS if you have followed the steps in the previous section.

At this point, you can click one of the radio buttons for three options:

  1. Start the migration – existing LDAP synchronization definitions will be migrated to the new Directory Synchronization Service once you click Apply. This operation may take a while, depending on the number of sync definitions and the amount of data they contain.
  2. Ignore old syncs – existing LDAP synchronization definitions will be ignored. You will only be able to create new sync definitions from scratch in the DSS UI. Once this option has been used, the migration wizard closes and importing old LDAP sync definitions will not be possible without extensive help from OpenLM Support.
  3. Decide later – this option works as a temporary “Skip” button. You will be able to use the DSS UI, but you won’t be able to create new syncs or add new domains until you come back to this screen and choose one of the two options above.

Selecting either 1 or 2 will present a final pop-up window informing you about the process:

Once migration has begun, you will see its status:

Once the wizard is complete, you will see a success message:

The last step is to assign an agent to the imported sync definitions that will execute them:

  1. Open the DSS user interface.
  2. Click on Sync Manager.
  3. Hover over the row of the imported sync and click the pen icon on the far right.
  4. Select an agent from the drop-down list.
  5. Click Save.

 

To do this for several definitions at once:

  1. Check the box of each definition you want to assign an agent to.
  2. Click Bulk Edit.
  3. Select an agent from the drop-down list.
  4. Click Save then Yes on the confirmation pop-up.

At this point migration is complete. You can now open the DSS user interface and add domains, sync definitions and manage agents as described in section 5 below.

 

4.3. DSS Configuration tools

DB Configuration

Note that you must first create a database using the DSS system requirements and upgrade its schema using the “DB Upgrade” procedure below before DSS can use an external database.

Configure which database the Directory Synchronization Service (DSS) will use to store its data.

By default, DSS is configured to work with an embedded Firebird DB. MySQL and SQL Server can also be used.

DB provider – select the provider of your database. Can be either Firebird, MySQL or Microsoft SQL Server with either standard authentication or Windows Authentication.

Server name – (MySQL or SQL Server only) the IP or hostname of the external database server.

Port – (MySQL or SQL Server only) the database server listening port.

Database file location – (Firebird only) the path to the database file.

DB Name – (MySQL or SQL Server only) the name of the database

Username – the name of the database user.

Password – the password for the database user.

Embedded – (Firebird only) checked by default. Uncheck if using a separate Firebird database.

Test – click to test the connection to the database.

Apply – save the settings.

 

DB Upgrade

This tool allows you to upgrade the Directory Synchronization Service (DSS) database to the latest database schema. This operation is necessary if using a newly created database that has not been previously formatted to the DSS schema.

To upgrade the database, select the database type you have, enter the login and connection details as on the DB Configuration tab, click Upgrade then follow the wizard instructions.

 

5. Usage

5.1. Agent Manager

On the Agent Manager tab you can see all the Directory Synchronization Agents controlled by the DSS.

 

5.1.1. Approve a new agent

All newly installed DSAs configured to report to the DSS have to be approved before they are operational.

To do so:

1. Click the Agent Manager tab.

2. Hover over the agent row that has its status as “Pending approval” and click on the Edit icon on the right.

3. On the Approve Agent screen, open the Status drop-down menu and select Enabled then click Approve.

 

5.1.2. Edit an agent’s properties

1. Hover over the row of the agent you want to change and click on the Edit icon on the right.

2. Change any of the required fields. Consult the text below for the meaning of each value.

Agent name – a name for the agent. Must be unique (i.e. different from other pre-existing agent names).

Description (optional) – enter any text to help you recall or identify the agent

Status – can be set to either:

    • Enabled – the agent is operational, querying the DSS for sync jobs and executing them.
    • Suspended – all synchronizations run by this agent will be suspended. Once status is changed back to Enabled they will resume

Agent request interval – specify how often the agent will query the DSS to check for sync jobs. Can be any value between 5 and 600 (seconds).

Sync method – can be set to either:

    • Parallel – this mode means that the agent will run several syncs in parallel, at the same time.
    • Serial mode – syncs are run one-by-one based on the FIFO method (first in, first out).

3. Click Save when done.

 

5.1.3. Edit agent properties in bulk

To change the properties for several agents at once:

1. Check the box for each agent you want to edit

2. Click on Bulk Edit.

This will open the Bulk Editor window.

The available properties are the same as described in section 5.1.2. above.

3. Once done, click Save to apply the changes.

 

5.1.4. Delete an agent

To delete one or more agents, check the box of the agent you wish to delete then click Delete.

Note: if one or more syncs are assigned to an agent you will be prompted to select a surrogate agent before you can delete it.

 

5.2. Domain Manager

On the Domain Manager tab you can configure the domain directories you would like OpenLM to sync with.

 

5.2.1. Add a new sync domain

1. Click on Add Domain. The Add Domain screen will open. Configure the fields according to the instructions below.

Domain type – the type of the LDAP domain directory that you want to synchronize with. Currently you can select either of these:

    • Active Directory
    • eDirectory
    • ApacheDS

Domain name – the hostname/IP of the domain controller

Port – the port of the domain controller

SSL – toggle if the connection to the domain controller is SSL encrypted

Username – the username of the domain controller user

Password – the password of the domain controller user

 

2. Click on Check domain connectivity to run a test. You will be prompted to select an agent which will run the connectivity test. The operation itself can take up to 2 minutes. Once finished, you will see either a success or failure message below the button.

3. Click either on Save to save the domain configuration OR click on Save Domain & Add Sync to save the configuration and open the Add Sync screen with this domain already preselected.

 

5.2.2. Edit a domain’s properties

1. Hover over the row of the domain you want to change and click on the Edit icon on the right.

2. Change any of the required fields. The meaning of each field is described in section 5.1.1 above.

3. Click Save when done.

 

5.2.3. Delete a domain

To delete one or more domains, check the box of the domain you wish to delete then click on Delete.

You will see a final warning popup:

Note: if there are any sync definitions associated with a domain, the sync definitions will also have to be deleted. Checking this box is required in order to proceed.

 

5.3. Sync Manager

On the Sync Manager tab you can configure the synchronization definitions for the domains OpenLM will sync with.

 

5.3.1. Add a new sync definition

To add a new sync definition:

1. Click Add Sync.

2. Fill the fields as follows:

Sync name – enter any text to identify the sync definition. Must be unique (i.e. different) from other sync definition names.

 

Status – toggle whether this sync is enabled or disabled.

 

Destination & Time tab

Agent – select the agent that will execute this sync.

 

Domain name – select the domain to be synced. The drop-down list will be auto populated with domains from the Domain Manager tab.

 

Start node – enter the LDAP path for the node that this sync will start from. For large service directories, specifying a node in the tree narrows the search and improves performance. By default this value is automatically filled to correspond to the root of the selected domain directory. Click Test to validate the directory start node (can take up to 2 minutes). Make sure the LDAP connection string is in the right format.

Example #1: select the organizational unit “OU_AB” for the “testdev1domain.openlm.biz” domain on domain controller 10.0.0.153

LDAP://10.0.0.153/OU=OU_AB,DC=testdev1domain,DC=openlm,DC=biz

Example #2: select the “SecGroup” security group for the “openlm.com” domain on domain controller server2008r2ldap.openlm.biz

LDAP://server2008r2ldap.openlm.biz/CN=SecGroup,DC=openlm,DC=com

Example #3: select the group “Group_AB1” under organizational unit “OU_A” which in turn is under organizational unit “OU_AB” for the “testdev1domain.openlm.biz” domain

LDAP://10.0.0.153/CN=Group_A2,OU=OU_A,OU=OU_AB,DC=testdev1domain,DC=openlm,DC=biz

For help with finding the correct node path, a tool like LDAP Admin can be used: right-click on a node tree and select “Copy dn to clipboard”.

 

Sync schedule – define the schedule for when the sync will be run:

    • By time – select a day and a start time for the sync then click Add to add it to the schedule. Multiple times can be added.
    • By interval – enter a start time (format hh:mm) and the interval at which the sync will be repeated (can be any value from 1 to 720 hours). If the DSS is restarted, it will wait for the start time to trigger the sync.

 

Object tab

Sync object type – select the object type to be synchronized:

    • Users – only user objects will be synchronized. Here you can check the Only users monitored by OpenLM box (description below).
    • Computers – only computer objects will be synchronized.

 

Only users monitored by OpenLM

Checking this box means that when the sync is run, only the records of directory users with a matching OpenLM username will be imported and synchronized. This option is useful if you want to avoid adding directory users that have no correlated license activity recorded in the OpenLM system.

Technical note: for performance reasons, the monitored user list is cached by DSS. When a scheduled sync is triggered, DSS evaluates how much time has passed since the list was last retrieved from Server (provided this isn’t the first time a sync is run). If this time period is greater than the ActiveUsersRefreshIntervalHours parameter in the appsettings.json file, DSS will first query OpenLM Server to update the user list and then proceed to query the directory via DSA using this updated list. If the time period is lower than the set parameter, DSA will query the directory using the user list from cache. Manual syncs bypass this condition. Set this parameter to a lower amount if you need to trigger syncs more frequently and anticipate that monitored OpenLM users will be added/changed during the sync interval.

 

Sync attribute – Select or enter the directory attribute for synchronizing the username. The “Sync attribute” is supported only for the “Users” object type. Select from:

    • cn is the standard “Common Name” attribute used by all LDAP directories.
    • sAMAccountName (e.g. “jdoe”) is used by Windows Server pre-2000 Active Directory versions.
    • userPrincipalName (e.g. “john.doe@company.com”) is used by Windows Server post-2000 Active Directory versions.

 

Membership filter – Choose whether to sync all objects (no filter) or only objects that belong to either Organizational Units (OUs) or Security Groups.

 

Search depth – define the sync depth. This option allows limiting the synchronization process to a certain hierarchical level:

    • 0 (default) – the full tree group hierarchy will be synchronized.
    • 1 – only the start node group will be synchronized.
    • 2 – the start node group and its 1st level descendants will be synchronized.
    • 3 – the start node and its 2nd level descendants will be synchronized.
    • And so on.

 

Group Rules tab

Select the rule by which groups will be created:

No groups – This is the default selection for group synchronization. This option negates any groups that an object belongs to. All objects will be assigned to the system default OpenLM_Everyone group.

 

Flat – All objects will become members of the group defined by the administrator. All objects found in the specified sync tree will be assigned as members of this single group. Any other hierarchical structures will be ignored.

 

Hierarchical – Create groups according to the hierarchical LDAP node trees. You can choose which kind of object classes to include in this rule:

    • Organizational Units (OUs) – any existing OUs in the directory will have groups created with the same name and the objects belonging inside them will be assigned as members of these groups.
    • Security Groups – any existing Security Groups in the directory will have groups created with the same name and the objects inside them will be assigned as members of these groups.
    • Distribution groups – any existing distribution groups in the directory will have groups created with the same name and the objects inside them will be assigned as members of these groups.
    • Customized & Unknown Object Classes – any unknown and custom object classes (those outside the standard directory class types of OUs, Security Groups and DGs) – will have groups created with the same name and the objects inside them will be assigned as members of these groups.

 

Include start node – whether to include or not the start node in the synchronization.

 

Search depth – define the sync depth. This option allows limiting the synchronization process to a certain hierarchical level:

    • 0 (default) – the full tree group hierarchy will be synchronized.
    • 1 – only the start node group will be synchronized.
    • 2 – the start node group and its 1st level descendants will be synchronized.
    • 3 – the start node and its 2nd level descendants will be synchronized.
    • And so on.

Entity attribute – Groups will be created according to the specific attribute a member has. Type or select an attribute from the drop-down menu that you would like to synchronize by (e.g. “Division”, “Employee ID”, “Initials”, “Department”, etc.). For each unique attribute, a new OpenLM group is created. If a user/computer is found to have the same attribute, it is added to the respective group.

 

Regular expression to specify the sub-level of the selected attribute (optional) – allows to synchronize by an attribute that matches the Regex expression. E.g. if the “Country” attribute is selected, entering “USA” means that only objects that have their “Country” attribute set to “USA” will be synchronized.

 

Set as default group checkbox

For reporting purposes, the default group is considered the group towards which a user’s license usage time is counted. By default, all users created manually or synchronized into OpenLM are assigned to the system default OpenLM_Everyone group. Checking this box allows you to override this behavior:

  • For the Flat and Entity Attribute synchronization rules, the default group will be the one you input or select from the menu.
  • For the Hierarchical synchronization rule, the default group will be the first one that is found during the scan (e.g. if JohnDoe belongs to groups A, B and C – the default group is A)

While “Set as default group” is checked, the default group of an object is set and overwritten each time the synchronization runs.

 

5.3.2. Manually trigger a synchronization

Clicking the icon with one or more sync definitions selected will manually trigger the respective synchronizations to be run.

Once triggered, you should see an animated icon indicating progress. Hovering over the icon will display the current status of the synchronization.

 

5.3.3. Reset entity relationship data

Clicking the icon with one or more sync definitions selected will clear all relationship data that was generated by that sync definition, including any “ignore” flags (see 5.4.1) that might have been previously set. It does not affect actual user data.

 

5.3.4. Delete a sync definition

To delete one or more sync definitions, check the box of the definition you wish to delete then click on Delete.

You will see a final warning pop-up before it is deleted.

Note: if a sync is running, it cannot be deleted.

 

5.4. Entities

On the Entities tab, you can see the entities created by the DSS synchronizations and set individual ignore flags. The columns show the ID an entity has in the DSS database, the entity name, the entity type, which definition last synced it and when was the last time it was synced. Use the filters to see which entities were modified by which sync, or search for a specific entity.

 

5.4.1. Ignore an entity from all synchronizations

Checking the Ignore box for a specific entity and then clicking Save will ignore that entity from all synchronization definitions. Any updates that might occur in the directory records will not be reflected in the OpenLM database for that entity.

 

5.4.2. Manually synchronize an entity

Clicking the icon will manually trigger synchronization for that specific entity. This option overrides any “ignore” flags that might have been previously set.

 

5.4.3. View entity relationships

Clicking on the icon for a specific entity will open the Relations tab and display the relations that specific entity has.

 

5.5. Relations

On the Relations tab, you can see all the relations an entity has in the DSS database, including: the agent that queried the directory for this entity, the domain which the entity belongs to, the sync definition it is associated with, the entity name, its parent name (if any) and the last time it was synced on. Use the filters to see which relations were updated and when.

Clicking on any of the links will switch to the appropriate tab, showing more information about the linked item (agent, domain, sync or entity).

 

5.5.1. Ignore an entity from a specific synchronization

Checking the Ignore box for a specific entity and then clicking Save will ignore that entity from the synchronization it is associated with under “Sync Name”. Any updates that might occur in the directory records will not be reflected in the OpenLM database for that entity, for this specific sync definition.

in Misc. OpenLM configs

Related Articles