--- title: Password Sync Agent description: When synchronizing passwords with Microsoft Active Directory (AD) systems, PingDataSync requires that the Ping Identity Password Sync Agent (PSA) be installed on all domain controllers in the synchronization topology. This component provides real-time outbound password synchronization from AD to any supported sync destinations. component: pingdirectory version: 11.0 page_id: pingdirectory:pingdatasync_server_administration_guide:pd_sync_password_sync_agent canonical_url: https://docs.pingidentity.com/pingdirectory/11.0/pingdatasync_server_administration_guide/pd_sync_password_sync_agent.html revdate: June 11, 2024 page_aliases: ["pd_sync_install_password_sync_agent.adoc", "pd_sync_upgrading_password_sync_agent.adoc", "pd_sync_upgrade_uninstall_password_agent.adoc", "pd_sync_manually_config_password_sync_agent.adoc"] section_ids: configuring-the-password-policy: Configuring the password policy install_psa: Installing the Password Sync Agent using-the-executable: Using the executable steps: Steps using-msiexec: Using msiexec before-you-begin: Before you begin steps-2: Steps upgrading-the-password-sync-agent: Upgrading the Password Sync Agent before-you-begin-2: Before you begin steps-3: Steps next-steps: Next steps uninstall_psa: Uninstalling the Password Sync Agent steps-4: Steps choose-from: Choose from: result: Result next-steps-2: Next steps manually-configure-the-password-sync-agent: Manually configure the Password Sync Agent --- # Password Sync Agent When synchronizing passwords with Microsoft Active Directory (AD) *(tooltip: \
\

A directory service for Windows domain networks, included in most Windows Server operation systems.\

\
)* systems, PingDataSync requires that the Ping Identity Password Sync Agent (PSA) be installed on all domain controllers in the synchronization topology. This component provides real-time outbound password synchronization from AD to any supported sync destinations. | | | | - | --------------------------------------------------------------------- | | | The Password Sync Agent can't be pointed at multiple domain clusters. | The PSA component provides password synchronization between directories that support differing password storage schemes. The PSA immediately hashes the password with a 256-bit salted secure hashing algorithm (SSHA256) and erases the memory where the clear-text password was stored. The component only transmits data over a secure (SSL) connection, and follows Microsoft's security guidelines when handling clear-text passwords. The PSA also uses Microsoft Windows password filters, which are part of the local security authority (LSA) process. The password filters enable implementing password policy validation and change notification mechanisms. Learn more in the [Microsoft documentation](https://learn.microsoft.com/en-us/windows/win32/secauthn/lsa-authentication). The following diagram illustrates how the PSA synchronizes password changes from AD to a PingDataSync server connected to a PingDirectory server: ![A diagram illustrating password synchronization with AD](_images/vbk1564012155463.png) The PSA supports failover between servers. It caches the hashed password changes in a local database until it can be guaranteed that all PingDataSync servers in the topology have received them. The failover features enable any or all of the PingDataSync servers to be taken offline without losing any password changes from AD. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If the Password Sync Agent is down for any length of time and misses a password change, the change won't be synced on recovery without either a new password change for the entry or the use of pass-through authentication. | The PSA is safe to leave running on a domain controller indefinitely. To stop synchronizing passwords, remove the `userPassword` attribute mapping *(tooltip: \
\

Matching corresponding attributes between an IdP and an SP to identify federated users or add supplemental user information.\

\
)* in PingDataSync, or stop the server. The PSA will not allow its local cache of password changes to grow out of control; it automatically cleans out records from its local database as soon as they have been acknowledged. It also purges changes that have been in the database for more than a week. Before installing the PSA, consider the following: * The PSA pre-encodes all passwords with a one-way salted SHA-256 hash before uploading them to PingDataSync. Password changes from AD can only be synchronized to destinations that support setting pre-encoded passwords. Currently, pre-encoded password synchronization is limited to PingDirectory, DSEE, Oracle OUD, and OpenDJ. AD explicitly does not allow for the synchronization of pre-encoded passwords. * Syncing a pre-encoded password to PingDirectory skips password validation. * Unlike the changelog password encryption plugin, the PSA never has access to a decryptable version of the password, so it cannot sync it to any source that doesn't support pre-encoded passwords, such as AD. * The AD sync destination drops any passwords it can't decrypt without logging anything about the dropped change. * Make sure that the AD Domain Controller (ADDC) has SSL enabled and running. * Make sure the PingDataSync servers are configured to accept SSL connections when communicating with the AD host. * At least one AD sync source needs to be configured on PingDataSync and should point to the domain controller(s) on which the PSA will reside. * You must add the certificate of the ADDC to the certificate trust store of the PingDataSync server. To do this, export the certificate from the ADDC and then use the `manage-certificates trust-server-certificate` tool to import it into the trust store of the PingDataSync server. * At the time of installation, all PingDataSync servers in the sync topology must be online and available. * The PSA component is for outbound-only password synchronization from AD systems. It is not necessary if performing a one-way password synchronization from the PingDirectory server to the AD server. For outbound password synchronization from a PingDirectory server to AD *(tooltip: \
\

A directory service for Windows domain networks, included in most Windows Server operation systems.\

\
)*, enable the Password Encryption component. Learn more in [Configuring password encryption](pd_sync_config_password_encryption.html). ## Configuring the password policy The PSA sends only pre-encoded passwords. If you're synchronizing passwords from AD to a Ping Identity system, you must allow pre-encoded passwords in the default password policy. For example: ```shell $ bin/dsconfig set-password-policy-prop \ --policy-name "Default Password Policy" \ --set allow-pre-encoded-passwords:true ``` ## Installing the Password Sync Agent The PingDirectory server distributes the PSA in a `.zip` archive with each PingDataSync package. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The initial installation of the PSA requires a system restart of the ADDC. The installer could force that restart, so you should plan for an installation maintenance window to avoid unexpected downtime. | ### Using the executable #### Steps 1. On the domain controller, double-click the `setup.exe` file to start the installation. 2. Select a folder for the PSA binaries, local database, and log files. 3. Enter the host names (or IP addresses) and SSL ports of the PingDataSync servers, such as `sync.host.com:636`. Don't add any prefixes to the host names. 4. Enter the Directory Manager distinguished name (DN) *(tooltip: \
\

A name uniquely identifying an object within the hierarchy of a directory tree.\

\
)* and password. This creates an ADSync user on PingDataSync. 5. Enter a password (secret key) for the ADSync user that will be used by the PSA when connecting to the PingDataSync instances. 6. Click **Next** to begin the installation. All of the specified PingDataSync servers are contacted, and any failures will roll back the installation. If everything succeeds, a message displays indicating that a restart is required. The PSA will start when the computer restarts, and the LSA process is loaded into memory. The LSA process cannot be restarted at runtime. ### Using `msiexec` You can also install the PSA using the `msiexec` command, enabling you to automate deployment of the PSA across multiple domain controllers with a script. #### Before you begin You must run this `msiexec` installation in PowerShell. #### Steps 1. Gather the necessary information for the following PSA-related arguments: | Argument | Required | Description | | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SYNC_SERVER_` | Yes | Specifies the host name and port of each PingDataSync server in the topology:- Format the value as `host name:port`. Don't add any prefixes to the host name. - To indicate the specific PingDataSync server, replace `` with `1 - 4`. | | `DIR_MGR_DN` | Yes | Specifies the DN of the Directory Manager account in the PingDataSync topology. This user must exist in each of the PingDataSync servers. | | `DIR_MGR_PWD` | Yes | Specifies the password for the Directory Manager account. | | `ADSYNC_USER_PWD` | Yes | Specifies the password of the ADSync user on the PingDataSync instances.The installer creates the ADSync user with the specified password, or verifies that the password is correct if the user already exists. The PSA uses this account to connect to the PingDataSync server instances. | | `TARGETDIR` | No | Specifies the installation directory that `msiexec` creates for the PSA. | 2. Determine which `msiexec` options to use. We've provided some required and common options in the following table, and you can learn more in the [Microsoft documentation](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/msiexec). | Option | Required | Description | | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/I` | Yes | Specifies the path to the `PasswordSyncAgent.msi` file. | | `/L` | No | Specifies the logging options for the installation. | | `/promptrestart` | No | Prompts the user to restart instead of forcing an automatic restart after installation. This option can't be combined with the `/qn` option. | | `/qn` | No | Runs `msiexec` without user interaction. This option is necessary if you want to automate the installation, but automated installations require a forced restart. Microsoft doesn't support using the /qn option in combination with the /promptrestart option. | 3. Run the `msiexec` command with the appropriate options and arguments. For example: ```shell msiexec /promptrestart /I PasswordSyncAgent.msi /L* "C:\Users\Administrator\Documents\install.log" SYNC_SERVER_1="localhost:1636" SYNC_SERVER_2="localhost:2636" 'DIR_MGR_DN="CN=Directory Manager"' DIR_MGR_PWD="rootpassword" ADSYNC_USER_PWD="adsyncpassword" ``` ## Upgrading the Password Sync Agent ### Before you begin You must know which version of the PSA you're running. To check the version number, go to **Control Panel > Programs > Programs and Features** and find the row containing the **Password Sync Agent** item. The version number is displayed on that row. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you are running a version earlier than 4.7, you must [uninstall the Password Sync Agent](#uninstall_psa) before upgrading because the installer has trouble locating the registry values from the older version. If you don't uninstall the older version of the PSA in this scenario, the upgraded PSA fails to start after the update. | You can upgrade the PSA by following these steps: ### Steps 1. Extract the new version of the PSA. Check the `Readme` file included with the PSA. If the header doesn't indicate a version, download version 4.7 or later before upgrading. 2. Follow the instructions for [installing the PSA](#install_psa). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You don't need to restart the computer to complete this step. The core password filter DLL is already running under LSA. The update replaces the implementation binaries, which are encapsulated from the password filter DLL and can be updated dynamically. | ### Next steps After you complete the installation, a dialog window might indicate that a restart is necessary due to configuration changes: * If the logging service has restarted, you can safely ignore this message. * If the logging service has not restarted, you should restart the computer to ensure that the PSA resumes syncing password changes. ## Uninstalling the Password Sync Agent You can use any of these options to uninstall the PSA from the AD *(tooltip: \
\

A directory service for Windows domain networks, included in most Windows Server operation systems.\

\
)* system. ### Steps * Uninstall the PSA: #### Choose from: * Go to **Control Panel → Programs → Programs and Features** and double-click the **Password Sync Agent** item. * Run `setup.exe` for the installed version of the PSA and select **Remove Password Sync Agent**. * Run the following command in PowerShell: **`msiexec /x "PasswordSyncAgent.msi"`** ### Result The implementation DLL gets unloaded, and the database and log files are deleted. Only the binaries remain. The core password filter is still running under the LSA process. It imposes zero overhead on the domain controller because the implementation DLL has been unloaded. To remove the password filter itself (located at `C:\WINDOWS\System32\ubidPassFilt.dll`), restart the computer. After restarting the computer, you can delete the password filter and implementation binaries from the install folder. ### Next steps You must restart the computer again before reinstalling the PSA. ## Manually configure the Password Sync Agent Configuration settings for the Password Sync Service are stored in the Windows registry in `HKLM\SOFTWARE\UnboundID\PasswordSync`. You can modify configuration values under this registry key during runtime, because the PSA automatically reloads and refreshes its settings from the registry. To verify that the PSA is working, check the current log file, located in `\logs\password-sync-current.log`. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * The default password hashing algorithm is SSHA256. To change the algorithm, create a registry key in `HKLM\SOFTWARE\UnboundID\PasswordSync` called `PASSWORD_HASHING_ALGORITHM`. The options are `SSHA`, `SSHA1`, `SSHA256`, `SSHA384`, and `SSHA512`. * To enable debug logging, set the `LOG_VERBOSITY` registry key to `1`. |