Changing the Password Synchronization Plugin Configuration After Installation

If you need to change any settings after installation, access the settings using the Registry Editor under HKEY_LOCAL_MACHINE > SOFTWARE > ForgeRock > OpenIDM > PasswordSync. For information about creating registry keys, see the corresponding Windows documentation.

You can change the following registry keys to reconfigure the plugin:

Keys to set the method of authentication
  • authType sets the authentication type.

    For plain HTTP or SSL authentication using IDM headers, set authType to idm.

    For SSL mutual authentication using a certificate, set authType to cert.

    By default, the plugin does not validate the IDM certificate. To configure this validation, set the following registry key: netSslVerifyPeer = True.

  • authToken0 sets the username or certificate path for authentication.

    For example, for plain HTTP or SSL authentication, set authToken0 to openidm-admin.

    For SSL mutual authentication, set authToken0 to the certificate path, for example path/to/certificate/cert.p12. Only PKCS #12 format certificates are supported.

  • authToken1 sets the password for authentication.

    For example, for plain HTTP or SSL authentication, set authToken1 to openidm-admin.

    For SSL mutual authentication, set authToken1 to the password to the keystore.

Keys to set encryption of captured passwords
  • certFile sets the path to the keystore used for encrypting captured passwords, for example path/to/keystore.p12. Only PKCS #12 keystores are supported.

  • certPassword sets the password to the keystore.

  • keyAlias specifies the alias that is used to encrypt passwords.

  • keyType sets the cypher algorithm, for example aes128

Keys to set encryption of sensitive registry values

For security reasons, you should encrypt the values of the authToken1 and certPassword keys. These values are encrypted automatically when the plugin is installed, but when you change the settings, you can encrypt the values manually by setting the encKey registry key.

Note

If you do not want to encrypt the values of the authToken1 and certPassword keys, you must remove the encKey from the registry, otherwise the plugin will use the value stored in that key to decrypt those values (even if they include an empty string).

To encrypt the values of the authToken1 and certPassword keys:

  1. Optionally, generate a new encryption key by running the following command:

    idmsync.exe --key
  2. Encrypt the values of the sensitive registry keys as follows:

    idmsync.exe --encrypt "key-value" "authToken1Value"
    idmsync.exe --encrypt "key-value" "certPasswordValue"
  3. Replace the existing values of the encyKey, authToken1 and certPassword keys with the values you generated in the previous step.

    If you do not want to generate a new encryption key, skip the first step and use the existing encryption key from the registry.

Keys to set the IDM connection information

The password synchronization plugin assumes that the Active Directory user attribute is sAMAccountName. The default attribute will work in most deployments. If you cannot use the sAMAccountName attribute to identify the Active Directory user, set the following registry keys on your Active Directory server, specifying an alternative attribute. These examples use the employeeId attribute instead of sAMAccountName:

  • userAttribute = employeeId

  • userSearchFilter = (&(objectClass=user)(sAMAccountName=%s))

  • idmURL = https://localhost:8444/openidm/managed/user?_action=patch&_queryFilter=uid+eq+${employeeId}

Keys to set the behavior when IDM is unavailable

When IDM is unavailable, or when an update fails, the password synchronization plugin stores the user password change a JSON file on the Active Directory system and attempts to resend the password change at regular intervals.

After installation, you can change the behaviour by setting the following registry keys:

Also the netTimeout in milliseconds can be set.

  • dataPath - the location where the plugin stores the unsent changes. When any unsent changes have been delivered successfully, files in this path are deleted. The plugin creates one file for each user. This means that if a user changes his password three times in a row, you will see only one file containing the last change.

  • pollEach - the interval (in seconds) at which the plugin attempts to resend the changes.

  • netTimeout - the length of time (in milliseconds) after which the plugin stops attempting a connection.

Keys to set the logging configuration
  • logPath sets the path to the log file.

    If you change this parameter, you must restart the machine for the new setting to take effect. If you change the logPath and do not restart the machine, the service will write the logs to the new location but the sync module will continue to write logs to the old location until the machine is restarted.

  • logSize - the maximum log size (in Bytes) before the log is rotated. When the log file reaches this size, it is renamed idm.log.0 and a new idm.log file is created.

  • logLevel sets the logging level, debug, info, warning, error, or fatal.

Key to configure support for older IDM versions

If the idm2only key is set to true, the plugin uses an old version of the patch request. This key must not exist in the registry for IDM versions 3.0 and later.

Key to configure infinite loop prevention

Note

This feature requires AD Password Synchronization Plugin version 1.4.0 or later.

When Active Directory syncs passwords with IDM bidirectionally, it is possible to enter an infinite loop, where Active Directory and IDM are constantly updating the password and telling the other system to do the same. To help prevent this situation, you can set the pwdChangeInterval key to the number of seconds that must elapse between password updates.

If you change any of the registry keys associated with the password synchronization plugin, run the idmsync.exe --validate command to make sure that all of the keys have appropriate values.

The password synchronization plugin is installed and run as a service named OpenIDM Password Sync Service. You can use the Windows Service Manager to start and stop the service. To start or stop the plugin manually, run the idmsync.exe --start or idmsync.exe --stop command.

Read a different version of :