Password sync agent

The Password Sync Agent cannot be pointed at multiple domain clusters.

If the Password Sync Agent is down for any length of time and misses a password change, these changes will not be synced on recovery without either a new password change for the entry or the use of pass-through authentication.

When synchronizing passwords with 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 Microsoft Active Directory to any supported Sync Destinations.

The PSA component provides password synchronization between directories that support differing password storage schemes. The PSA immediately hashes the password with a 160-bit salted secure hash algorithm 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. For more information, see Microsoft’s product documentation.

The default password hashing algorithm is SSHA256. To change the algorithm, create a registry key in the Windows registry under HKLM\SOFTWARE\UnboundID\PasswordSync called PASSWORD_HASHING_ALGORITHM. The options are SSHA, SSHA1, SSHA256, SSHA384, and SSHA512.

For outbound password synchronization from a PingDirectory server to AD, enable the Password Encryption component. See Configuring password encryption for more information.

A diagram illustrating password synchronization with Microsoft Active Directory

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

The PSA is safe to leave running on a domain controller indefinitely. To stop synchronizing passwords, remove the userPassword attribute mapping 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 Active Directory 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. Active Directory 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 Active Directory.
The Active Directory Sync Destination drops any passwords it can’t decrypt without logging anything about the dropped change.
Make sure that the Active Directory domain controller has SSL enabled and running.
Make sure the PingDataSync servers are configured to accept SSL connections when communicating with the Active Directory host.
At least one Active Directory Sync Source (ADSyncSource) needs to be configured on PingDataSync and should point to the domain controller(s) on which the PSA will reside.
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 the Active Directory Systems. It is not necessary if performing a one-way password synchronization from the PingDirectory server to the Active Directory server.

Install the password sync agent

About this task

The PingDirectory server distributes the PSA in zip file format with each PingDataSync package. The initial installation of the PSA requires a system restart. NOTE: The Password Sync Agent cannot be pointed at multiple domain clusters.

Steps

On the domain controller, double-click the setup.exe file to start the installation.
Select a folder for the PSA binaries, local database, and log files.
Enter the host names (or IP addresses) and SSL ports of the PingDataSyncs, such as sync.host.com:636. Do not add any prefixes to the host names.
Enter the Directory Manager distinguished name (DN) and password. This creates an ADSync user on PingDataSync.
Enter a password (secret key) for the ADSync user that will be used by the PSA when connecting to the PingDataSync instances.
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.
If synchronizing pre-encoded passwords from AD to a Ping Identity system, allow pre-encoded passwords in the default password policy.
```
$ bin/dsconfig set-password-policy-prop \
--policy-name "Default Password Policy" \
--set allow-pre-encoded-passwords:true
```

Upgrade or uninstall the password agent

PingDataSync provides the update tool for upgrades to the server code, including the PSA. The upgrade does not require a restart, because the core password filter is already running under LSA. The upgrade replaces the implementation binaries, which are encapsulated from the password filter DLL.

To uninstall the PSA on the AD system, use Add/Remove Programs on the Windows Control Panel. The implementation DLL will be unloaded, and the database and log files are deleted. Only the binaries remain.

The core password filter will still be 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. On restart, the password filter and implementation binaries (in the install folder) can be deleted.

The PSA cannot be reinstalled without another reboot.

Manually configure the password sync agent

Configuration settings for the Password Sync Service are stored in the Windows registry in HKLM\SOFTWARE\UnboundID\PasswordSync. Configuration values under this registry key can be modified during runtime. The agent automatically reloads and refreshes its settings from the registry. Verify that the agent is working by checking the current log file, located in <server-root>\logs\password-sync-current.log. NOTE: The Password Sync Agent cannot be pointed at multiple domain clusters.