Directory Sync (Old Name→Directory Synchronization) - Comprehensive Guide v2x
Israel +972 4 6308447         USA +1 619 831 0029              JAPAN +81 505 893 6263 担当:萩原

Directory Sync (Old Name→Directory Synchronization) – Comprehensive Guide v2x

You are here:
< All Topics

This is a comprehensive guide on how to synchronize the OpenLM Database with an organization’s directory service using the Directory Sync. To see how to set up Directory Sync on Cloud, follow this guide.

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 Sync product, which consists of two components:

  • DSA
  • DSS

Both components are required 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  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 is ready to send 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 21 or higher.
  2. A license file that has support for the Directory Sync 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 AD domain controller.
  4. A designated schema in any supported database – MariaDB, MS SQL, My SQL (Firebird has been deprecated).

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\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 Installation

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. In the next prompt you will be asked to select the database type that you want to use. Select it from the dropdown list and click Next. If you are upgrading and require to migrate data, go to step 4.2

4. Provide the database configurations details then click Next:

Note this prompt may be slightly different, depending on the DB type used.

5. You can change the installation folder if you want. The default one is C:\Program Files\OpenLM\OpenLM Directory Sync (DSS) Service\ . Click Next.

6. Once the 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).

4. Configuration

4.1. Directory Synchronization Service (DSS)

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

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

Note: If you use Identity Service, configure the DSS in the Identity Service and restart the DSS service. Use this guide for more. If you do not use Identity Service – then no login is required.

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

3. 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\OpenLM\OpenLM Directory Sync (DSS) Service\ and restart the Directory Sync (DSS) 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. See this document for the workflow of DSS with Server and Identity configured with SSL (HTTPS)

Additional Service Configurations:

Time&Date

  • It allows to specify the timezone displayed and used in DSS UI:

Advanced:

  • The Advanced tab allows deleting users and Groups from the DSS database. It should be used to delete entities and relations from the DSS Database and should not be used in the process of initial configuration of DSS. Be mindful as this is an irreversible action:

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

Note: If you are using Identity Service, the DSS will automatically detect this configuration:

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

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

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

8. 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, the 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 The workflow of DSS with Server and Identity configured with SSL (HTTPS

If the OpenLM Server and Identity are on SSL (HTTPS):

1. After turning on SSL (HTTPS) on OpenLM Server and Identity Service, open the Connectivity tab of DSS UI and change the Server’s IP/hostname value to HTTPS: FQDN (example “https://hostname.domain”). This should be done because SSL certificates are issued to FQDNs, which is common practice. Click Apply.

2. After DSS is approved in HTTPS Server, it is mandatory to update the Identity Service location in appsettings.json of DSS by:

-changing manually “Authority” field from “http:identityHost:port” to “https:identityHost:port” or

-from Identity UI Security settings, change the DSS URL by adding “/” at the end of the URL and clicking Save (a workaround to allow Identity to apply new settings and send a request to DSS). For example by changing: http://hostname:7026 to http://hostname:7026/

3. After changes from steps 1 and 2, just restart first DSS, and then DSA services and continue working as usual.

4.3 DSS & DSA SSL Configuration

  1. Turn ON the SSL toggle and provide the certificate path and its password.
  2. Restart the DSS service.
  3. Go to the Identity Service UI and provide the new DSS URL (https://FQDN:port).
  4. Restart DSS service again.
  5. Open the DSS UI using the new URL https://FQDN:port.
  6. Set in DSS UI [DSS SERVER IP/Hostname] field the new URL (https://FQDN).
  7. Click the Apply button.

4.4 Upgrading from Directory Sync 1.4 (Firebird ) to Directory Sync v2x. Database migration during upgrade:

Consult this document to see how to upgrade OpenLM Server to v5.6 and this to consult LDAP migration to Directory Sync v1.4

If you are upgrading the Directory Sync, a specially designated checkbox will appear automatically in the DSS migration wizard if the system detects you are using the Firebird engine. If a different database type is used, no migration is required, you’re all set. The guide below also assumes that the migration from OpenLM Server 5.6 to v 21 has been executed.

  1. Check the “Migrate data” box. From the dropdown list, choose the desired database then click Next.

2. The installation requires a clear database schema. You will need to fill in the configuration details as in the screenshot below: Server name, Database name, User, and Password. Click Next.Note: depending on your database type, the fields in the screen below may look slightly different

3. Select the folder you want to install the program to. Click Browse to do so or leave the default one (recommended). When the folder has been chosen, click Next.

4. The DSS is ready to be installed. Tick the box if you wish to create a desktop icon then click Install.

5. The installation/migration has been completed. Click Finish.

6. Open up your DSS page. Go to the Service Configuration tab. Here specify the Server’s configuration details (v21 has a different one than v.5.6) then click Apply.

To check if the changes are successfully applied, open up DSS from Easy Admin. (Administration→Directory Sync (DSS))

7. Continue with the Directory Sync (DSS) Agent upgrade.

4.5. Directory Sync 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 Sync (DSS) Service (DSS) will use to store its data.

DSS will be configured to work with an external database: mysql / mssql/ mariadb (Check the system requirements).

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

Server name – the IP or hostname of the external database server.

Port – (MySQL or MariaDB) the database server listening port.

DB Name – the name of the database

User ID – (MySQL, MariaDB or SQL Server Authentication) the name of the database user.

Password – (MySQL, MariaDB or SQL Server Authentication) the password for the database user.

Test – click to test the connection to the database.

Apply – save the settings.

DB Upgrade

This tool allows you to upgrade the Directory Sync (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. 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 (no spaces allowed) to recognize the Agent instance and the details of the DSS installation (found in the Directory Sync UI → Service Configuration tab under DSS Server), then select your Server version: On-premise or Cloud. Click Next.

4. The next prompt will require you to authorize. You can skip this step if you don’t use Identity Service.

5. To obtain the Authorization file go to EasyAdmin and follow the path: Start→Administration→System&Security→Security→Authorization→Add

6. Select the Client type from the drop-down list – DSA. Click Save.

(Note the Secret Key will only be displayed once. Please make sure to save it before closing the window).

7. Copy or Download the JSON file with the Client ID and Client Secret:

8. Go back to the installation process and import or copy&paste the credentials:

9. You can change the installation folder if you want. Enter the path or click Browse, then click Next when completed.

10. Once the 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 6.1.1.

When completed the upgrade, check that it went smooth, (in the case of data migration – the migration was successful)

6. Usage

6.1. Agent Manager

On the Agent Manager tab, you can see all the Directory Sync (DSS) Agents controlled by the DSS.

6.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. Double click on the agent row that has its status as “Pending approval” (or click Edit Agent icon).

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

6.1.2. Edit an agent’s properties

1. Double click on the row of the agent you want to change (or click the Edit Agent icon) and click on the Advanced Settings.

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 the 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 Changes when done.

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

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

6.1.4. Delete an agent

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

6.2. Domain Manager

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

6.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
  • AzureAD
  • Google CDS

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 an administrator account. Note that read access is required. A service account is recommended. If a normal account is used, the password might expire at which point the sync would stop working

Password – the password of the domain controller user

For Azure:

  • Domain Name
  • Client ID
  • Client Secret
  • Tenant ID

For more details about AzureAd synchronization consult this link.

For more details about Google CDS consult this link.

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.

6.2.2. 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 to proceed.

6.3. Sync Manager

On the Sync Manager tab you can configure the synchronization definitions for the domains OpenLM will sync with. The Sync Manager centralizes access to all sync configurations.

6.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 the OpenLM box (description below).
  • Computers – only computer objects will be synchronized.

Note: for Azure AD – only Users option is supported

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 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 period is lower than the set parameter, DSA will query the directory using the user list from the 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. Make sure that the attribute exists for your specific directory type. 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.

Note: for Azure AD – only UserPrincipalName option is supported

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

Note: for Azure AD – there are two options

  1. All objects
  2. Only members of a group

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.

Note: for Azure AD – only the Security Groups option is supported

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

Note about ApacheDS:

Because of some specific ApacheDs rules in group’s implementation, DSS is synchronizing ApacheDs groups in a different way from other directory types. The group in ApacheDs is usually specified as objectClass = groupOfNames OR groupOfUniqueNames. Respectively, child objects (members) in such cases are members or uniqueMember. Based on these relations is defined group membership. So, groupOfNames should contain member(s), and groupOfUniqueNames should contain uniqueMember(s). See the example below:

Link to the mapping details here.

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

6.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 6.4.1) that might have been previously set. It does not affect actual user data.

6.3.4. Stop Sync button

Sometimes syncs get stuck on the “Update Openlm DB” phase. Use the “Stop Sync” button to cancel those syncs in order to be able to run them again.

6.3.5. 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 that if a sync is running, it cannot be deleted.

6.4. Entities

On the Entities tab, you can see the entities created by the DSS synchronizations and set individual to 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. Also, there is the possibility to customize the list of columns, print or export the table and configure the amount of entities displayed on one page:

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

6.4.2. Manually synchronize an entity

Clicking the

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

6.4.3. View entity relationships

Clicking on the

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

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

The “Ignore” checkbox is per entity for the sync it is associated with. The list of columns can be customized and the table can be printed or exported. Also, the number of relations displayed on the page can be configured:

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

6.5.1. Ignore an entity from a specific synchronization

Checking the Ignore box for a specific Relation 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.

Previous Directory Sync (DSS) (Old Name->Directory Synchronization) – Quick Start Guide HT500
Next DSS, DSA 21.5 – new security release – insights
Table of Contents