--- title: Install the Directory Synchronization Agent (DSA) description: Install, upgrade, and change the Directory Synchronization Agent (DSA) on Windows, connect it to OpenLM Platform with its authorization file, and approve it in Directory Sync. product: OpenLM Platform --- To sync users and groups from your directory to OpenLM Platform, install the Directory Synchronization Agent (DSA) on a machine that can reach the directory. The DSA reads local directories (LDAP) or cloud directories (Microsoft Entra ID, Google, Okta), and sends the user and group data to OpenLM Platform through the Directory Synchronization Service (DSS). You set up the DSA once, in the installer. After that, you approve it and tell it what to sync in [Directory Sync](https://www.openlm.com/documentation/cloud/users/directory-sync/). ## Before you begin Confirm these prerequisites: - Verify that the machine meets the [system requirements](https://www.openlm.com/documentation/cloud/deployment-operations/system-requirements/?component=dsa). - Choose a 64-bit Windows machine with network access to your directory. For a local directory (LDAP), the machine needs access to the directory server, on port 389 by default, or 636 with SSL. To sync through a Global Catalog, the ports are 3268, or 3269 with SSL, as described in [Directory Sync with global catalog](https://www.openlm.com/documentation/cloud/users/directory-sync/#directory-sync-with-global-catalog). For a cloud directory (Microsoft Entra ID, Google, Okta), it needs internet access. - Allow outbound HTTPS (port 443) from the machine to your OpenLM Platform. The DSA opens every connection to OpenLM Platform itself, so the machine needs no inbound access from the internet. - Generate an [authorization file](https://www.openlm.com/documentation/cloud/getting-started/authorize-components) of type **Dsa** for this DSA. Leave **Encrypted authorization client** clear: the installer accepts only the plain file, named `dsa-authorization.json`. - Sign in to Windows with an administrator account. - If you run OpenLM Platform on your own servers, read [Choose the connection option](#choose-the-connection-option) first. ## Install the DSA in four steps To install the DSA, follow these steps: Download the DSA installer from the [Downloads page](https://www.openlm.com/downloads/). On a machine that can reach your directory, run the installer. Name the agent, select **OpenLM Cloud**, and import the authorization file. The installer starts the DSA service, and the agent asks OpenLM Platform for approval. In OpenLM Platform, open **Directory Sync**. On the **Agents** page, approve the new agent, which waits with the status **Pending**. In **Directory Sync**, add your directory on the **Domains** page, and define what to sync on the **Synchronizations** page. The DSA then reads your directory on the schedule you set, and sends the user and group data to OpenLM Platform. The following sections give the details. For every component on one page, see [OpenLM components installation and configuration](https://www.openlm.com/documentation/cloud/deployment-operations/components-installation/). ## Install on Windows Download the DSA installer, `OpenLM_Directory_Synchronization_Agent_Setup..msi`, from the [Downloads page](https://www.openlm.com/downloads/). Then install the DSA with the installer, or silently from the command line. ### Install with the installer To install the DSA with the installer: 1. Open the installer file, `OpenLM_Directory_Synchronization_Agent_Setup..msi`. 2. On the first page, select **I agree to the license terms and conditions**, and then select **Next**. **Next** becomes available after you select the check box. *The first page, with the license terms accepted* 3. On the **Directory Synchronization Agent (DSA) Configuration** page, enter an **Agent name**. Directory Sync lists the agent under this name, so use a name that tells you which machine runs it. The name can't contain spaces. 4. Keep the **Agent service port**, `8099`, unless another program on the machine uses that port. 5. Under **Choose your Open LM version**, select **OpenLM Cloud**, and then select **Next**. The installer selects **OpenLM On-Premise** by default. *Name the agent, and select OpenLM Cloud* 6. On the **DSA Authorization** page, select **Import authorization details from file**, and then select **Browse**. Ignore the instruction to generate the authorization details in OpenLM EasyAdmin. For OpenLM Platform, generate the file in **Identity**, as described in [Authorize components](https://www.openlm.com/documentation/cloud/getting-started/authorize-components). The file also carries the address of your OpenLM Platform. *Select Import authorization details from file* 7. Select the `dsa-authorization.json` file you generated for this DSA, and then select **Open**. The installer checks the file when you select it. 8. Select **Next**. 9. On the **Select destination folder** page, keep the default folder, `C:\Program Files\OpenLM\OpenLM Directory Synchronization Agent\`, and then select **Next** to start the installation. To install in another folder, select **Browse** first. *The default destination folder* 10. Wait for the installation to finish. At the end, the installer starts the DSA service. 11. On the **DSA installation completed successfully** page, select **Finish** to close the installer. Then approve the agent in Directory Sync. *The last page of the installer* To approve the agent, see [Approve the agent](#approve-the-agent). If the installer rejects the authorization file, see [Why does the installer reject the authorization file?](#why-does-the-installer-reject-the-authorization-file). If it reports `Failed to start DSA service`, see [Why does the installer fail to start the DSA service?](#why-does-the-installer-fail-to-start-the-dsa-service). ### Choose the connection option The **Choose your Open LM version** page offers two options, and the installer then asks for different details: - **OpenLM Cloud**: the installer asks for the authorization file on the **DSA Authorization** page. The DSA connects to the OpenLM Platform address in that file, and the agent registers in Directory Sync. - **OpenLM On-Premise**: the installer asks for a DSS host name and port instead. This option is for the Version 26 Directory Synchronization Service (DSS), not for OpenLM Platform. See the [Version 26 Directory Sync installation guide](https://www.openlm.com/documentation/legacy/directory-sync/). Select **OpenLM Cloud** for OpenLM Platform, including an OpenLM Platform that you run on your own servers. This differs from the Workstation Agent installer, where **OpenLM On-Premise** is the option for a self-hosted OpenLM Platform. In the DSA installer, **OpenLM On-Premise** means a Version 26 DSS. For a self-hosted OpenLM Platform, generate the authorization file on your own OpenLM Platform, and make sure the DSA machine trusts its TLS certificate. See [TLS certificates](https://www.openlm.com/documentation/cloud/deployment-operations/on-premise/tls-certificates). Without that trust, the agent can't connect. ### Silent installation To deploy the DSA from a script, install it silently: `msiexec` installs the DSA with the options you pass on the command line, without the installer pages. A silent installation doesn't check the options the way the installer does, so check the agent in Directory Sync afterwards. To install the DSA silently: 1. Open a command prompt as an administrator. 2. Run `msiexec` with the installation options, in this format: ```bash msiexec /i "" /qn AGENT_NAME="" CONNECTION_TYPE="Cloud" AUTHORIZATION_TYPE="1" DSA_AUTHORIZATION_FILE_PATH="" ``` Replace `` with the full path of the DSA MSI file, `` with the name of the agent, and `` with the full path of `dsa-authorization.json`. Use these parameters: - `AGENT_NAME`: the name that Directory Sync lists the agent under, without spaces. - `CONNECTION_TYPE`: `"Cloud"` for OpenLM Platform. Without it, the installer sets up an on-premises agent. - `AUTHORIZATION_TYPE`: `"1"` to import the authorization file in `DSA_AUTHORIZATION_FILE_PATH`. - `DSA_AUTHORIZATION_FILE_PATH`: the full path of the authorization file. The installer copies it into the installation folder as `dsa-authorization.json`. - `DSA_PORT`: the agent service port. The default is `8099`. - `INSTALLFOLDER`: the installation folder. The default is `C:\Program Files\OpenLM\OpenLM Directory Synchronization Agent\`. To write a log file, add `/l*v ""`, where `` is the path of the log file. A verbose log can contain the authorization details, so store it like the authorization file, and delete it when you no longer need it. 3. When the installation finishes, check that the **OpenLM Directory Synchronization Agent** service runs in Windows Services. Then approve the agent, as described in [Approve the agent](#approve-the-agent). ## Approve the agent A new DSA reads nothing until you approve it. To approve the agent: 1. In OpenLM Platform, open [Directory Sync](https://www.openlm.com/documentation/cloud/users/directory-sync/#open-directory-sync). It opens on the **Agents** page. 2. Find the new agent, with the status **Pending**. The agent registers a minute or two after its service starts. The list doesn't update by itself, so if the agent isn't listed, select **Refresh data**. *A new agent waits for approval with the status Pending* 3. Hover over the agent, and then select the **Approve agent** icon. The status changes to **Enabled** at once. Within a minute, the agent picks up the approval without a restart, and **Last Connection Date** shows when it last reported. *The approved agent, with its last connection date* ## Upgrade the DSA The DSA sends your directory data to OpenLM Platform through the Directory Synchronization Service (DSS). To upgrade, you install the new DSA version over the old one on your machine. You don't uninstall first. To upgrade the DSA: 1. Download the new installer from the [Downloads page](https://www.openlm.com/downloads/). 2. Sign in to Windows with an administrator account, and run the new `OpenLM_Directory_Synchronization_Agent_Setup..msi`. For a silent upgrade, run the same `msiexec /i` command you used to install, with the new MSI path. 3. On the first page, accept the license agreement and select **Next**. When the DSA is already installed, the installer goes straight to the installation: it shows no configuration pages and keeps the agent's settings. 4. Wait for the installation to finish, and then check that the **OpenLM Directory Synchronization Agent** service runs. The upgrade keeps the agent's configuration files, including `dsa-authorization.json`. It also keeps the agent's ID, status, and name, so the DSA continues as the same agent in Directory Sync. It doesn't register a new agent that waits as **Pending**. After the upgrade, open the **Agents** page and check that the agent shows **Enabled** and a recent **Last Connection Date**. The installer installs the same version again, but refuses an older version with the message "A newer version of OpenLM Directory Synchronization Agent is already installed." If the installation fails, the installer rolls back to the configuration it backed up before it started. An uninstall followed by a new installation is different: it registers a new agent. See [Why does a reinstalled DSA appear as a new agent?](#why-does-a-reinstalled-dsa-appear-as-a-new-agent). ## Change the DSA after installation Use these procedures when the DSA is installed and you need to change it: - **A new authorization file**: generate a new file of type **Dsa**, as described in [Authorize components](https://www.openlm.com/documentation/cloud/getting-started/authorize-components). Copy it into the installation folder as `dsa-authorization.json`, and restart the **OpenLM Directory Synchronization Agent** service. - **The agent service port**: an upgrade keeps the port, and the installer shows no configuration pages when the DSA is already installed. To use another port, uninstall the DSA and install it again with the new **Agent service port**. A new installation registers a new agent: see [Why does a reinstalled DSA appear as a new agent?](#why-does-a-reinstalled-dsa-appear-as-a-new-agent). - **A second DSA, for a directory on another network**: install a DSA on a machine that can reach that directory, with its own authorization file and an agent name that Directory Sync doesn't list yet. Approve it on the **Agents** page. Then select that agent when you [add the domain](https://www.openlm.com/documentation/cloud/users/directory-sync/#add-a-sync-domain). - **The log level**: change it in Directory Sync, as described in [Where are the DSA logs?](#where-are-the-dsa-logs). ## Uninstall the DSA Remove the DSA from Windows in one of these ways: - **Programs and Features**: in the Control Panel, select **Programs**, then **Uninstall a program**. Select **OpenLM Directory Synchronization Agent**, then **Uninstall**. - **Silent uninstallation**: run `msiexec /x` with the installer you installed from: ```bash msiexec /x "" /qn ``` Replace `` with the full path of the DSA MSI file. Uninstalling keeps the installation folder, with the agent's configuration, its logs, and the authorization file `dsa-authorization.json`. To remove the DSA completely, delete the folder after you uninstall, because the authorization file holds the client secret. Uninstalling also leaves the agent listed in Directory Sync, where it shows a warning icon when it stops reporting. To remove it there as well, delete it on the **Agents** page, as described in [Delete an agent](https://www.openlm.com/documentation/cloud/users/directory-sync/#delete-an-agent). ## Troubleshooting Use these answers when the DSA doesn't install, register, or read your directory as expected. ### Where are the DSA logs? Open the `log` folder in the installation folder, `C:\Program Files\OpenLM\OpenLM Directory Synchronization Agent\log` by default. The DSA writes one log a day, `OpenLM_Ldap_Agent-.log`, and archives a log that grows past 10 MB. Each start of the service begins with `Start OpenLM.Ldap.Agent, version `. When the agent registers, it logs `saved info: agentId = `, and a healthy agent then logs `MonitorConfigStatus finished for agentId . Is monitoring = True` every 30 seconds. The DSA logs at the level set for the agent in Directory Sync. To change the level, edit the agent, and change **Agent Log Level**, as described in [Edit an agent's properties](https://www.openlm.com/documentation/cloud/users/directory-sync/#edit-an-agents-properties). The new level applies without a restart. **Trace** also logs sensitive data, such as passwords, so set the level back when you finish troubleshooting. ### Why does the installer reject the authorization file? The installer checks the file when you select it, and reports a problem in a "DSA authorization file validation error" message: - `DSA authorization file name should be: dsa-authorization.json`: the file has another name, for example `dsa-authorization (1).json` after a second download. Rename it to `dsa-authorization.json`, in lowercase. An encrypted authorization file can't be used. Generate a file for a client without **Encrypted authorization client** instead. - `clientType property value must be DSA.`: the file belongs to another component, such as a Broker. Generate a file of type **Dsa**. - A message that a property can't be empty, or an error about the file contents: the file is incomplete or was changed. Download it again. ### Why does the installer fail to start the DSA service? At the end of the installation, the installer starts the DSA service and waits for it to run. If the service doesn't start, the installer shows `Failed to start DSA service. Error:` with the reason, and the buttons **Cancel**, **Retry**, and **Ignore**. `Cannot start service OpenLMLdapAgent on computer '.'` usually means that the service took longer to start than Windows allows, 30 seconds by default. The Windows System log then has the events 7009 and 7000 for **OpenLM Directory Synchronization Agent**. This can happen on a slow or busy machine, for example while antivirus software scans the new files. Select one of these options: - Select **Retry** to start the service again. - Select **Ignore** to finish the installation with the service stopped. Start **OpenLM Directory Synchronization Agent** later in Windows Services. The service also starts with Windows, after a delay. - Select **Cancel** to roll back the installation. ### Why doesn't the new agent appear in Directory Sync? The agent registers a minute or two after its service starts. The **Agents** list doesn't update by itself, so first select **Refresh data**. If the agent still isn't listed, check that the **OpenLM Directory Synchronization Agent** service runs, and look in the [DSA log](#where-are-the-dsa-logs) for these causes: - **No route to OpenLM Platform**: `Request to ... finished unsuccessfully after out of attempts.` Allow outbound HTTPS from the DSA machine to the address in `baseUrl` in the authorization file. - **Rejected credentials**: `DSA failed to retrieve access token.` The authorization client was deleted, or its secret was reset. Generate a new authorization file, copy it into the installation folder as `dsa-authorization.json`, and restart the service. - **No authorization details**: `Authorization settings are missing.` You chose to add the authorization details later, or a silent installation didn't get the file. Copy the file into the installation folder as `dsa-authorization.json`, and restart the service. - **Directory Sync isn't active**: `Most likely DirectorySync product is not activated in Products Service.` Ask an account administrator to activate Directory Sync in [OpenLM Products](https://www.openlm.com/documentation/cloud/openlm-administration/products/). - **The agent name is taken**: `Agent name already exists.` See [Why doesn't a reinstalled DSA appear in Directory Sync?](#why-doesnt-a-reinstalled-dsa-appear-in-directory-sync) ### Why does the log show an error in cloud mode? When the service starts, the DSA logs `DSA is working in cloud mode. It will work in secure mode` with the level `ERROR`. The line means that the DSA connects to OpenLM Platform with the authorization file, which is the normal state. You can ignore it. ### Why does the domain connection check fail? **Check Domain Connection** runs on the DSA machine, through the agent you select. Check these causes: - **The agent isn't approved**: a pending agent runs no checks and no syncs. Approve it, as described in [Approve the agent](#approve-the-agent). - **No route to the directory**: the DSA machine needs access to the domain controller on the domain's port, 389 by default, or 636 with **SSL**. - **Credentials**: the user needs read access to the directory. **Anonymous Connection** works only if your directory allows anonymous reads. The DSA log names the domain, and the port and SSL setting it tried: `Error connecting domain: ... with settings: port:, Ssl:`. A successful check logs `Successfully validated domain `. ### Why does a reinstalled DSA appear as a new agent? A new installation registers the DSA as a new agent, even when the configuration files of an earlier installation stay in the installation folder. The earlier agent stays in Directory Sync, with the last connection date of the old installation. Approve the new agent, and then delete the earlier one. Directory Sync asks you to hand its syncs over to another agent. ### Why doesn't a reinstalled DSA appear in Directory Sync? Agent names must be unique. If you reinstall the DSA with the name of an agent that Directory Sync still lists, the registration fails, and the DSA log shows `Publishing agent configuration returned error : Agent name already exists.` The DSA then stops trying to register, and logs `Agent is disabled/ has Id 0 or don't have enouth data to perform MonitorConfigStatus` every 30 seconds. To register it, delete the earlier agent on the **Agents** page, or use another agent name. Then uninstall the DSA, and install it again. ### Why doesn't a silent installation register the agent? Check the installation command: - **Missing `CONNECTION_TYPE="Cloud"`**: without it, the DSA installs as an on-premises agent, which doesn't connect to OpenLM Platform. The log then shows `OpenLM.Ldap.Agent runs in on-premise mode`, and requests to `https://localhost/api/dss/` that fail. Uninstall it, and install it again with the parameter. - **The agent name is taken**: see [Why doesn't a reinstalled DSA appear in Directory Sync?](#why-doesnt-a-reinstalled-dsa-appear-in-directory-sync) - **The authorization file path is wrong**: a silent installation doesn't check the file. Copy the file into the installation folder as `dsa-authorization.json`, and restart the service. ## Next steps The approved agent reads nothing until you tell it what to sync. In [Directory Sync](https://www.openlm.com/documentation/cloud/users/directory-sync/), connect your directory and run a first sync: 1. On the **Domains** page, [add your directory](https://www.openlm.com/documentation/cloud/users/directory-sync/#add-a-sync-domain). Select **Check Domain Connection** to test it through the new agent, and then select **Save Domain & Add Sync**. 2. [Define the synchronization](https://www.openlm.com/documentation/cloud/users/directory-sync/#add-a-sync-definition): the agent, the start node in your directory, what to read, how to group it, and the schedule. 3. On the **Synchronizations** page, select the synchronization, and then select **Sync Now** to [run it once](https://www.openlm.com/documentation/cloud/users/directory-sync/#run-a-sync-manually). Check the result in [Sync History](https://www.openlm.com/documentation/cloud/users/directory-sync/#sync-history). After that, continue the setup with [Connect your first license manager](https://www.openlm.com/documentation/cloud/getting-started/connect-first-license-manager).