PingIDM

Configure the Active Directory password synchronization plugin

If you need to change any settings after installation, access the settings using the Registry Editor. For the full list of available registry key values, refer to Registry Key Values. For information about creating registry keys, refer to the corresponding Windows documentation.

After you change a registry key value associated with the password synchronization plugin, perform validation.

Create or edit registry key values

  1. Click the Start Menu, type registry, and click Registry Editor Desktop app.

  2. In the left pane of Registry Editor, expand the node:

    HKEY_LOCAL_MACHINE > SOFTWARE > ForgeRock > OpenIDM > PasswordSync

    For Example:

    Registry Editor Screenshot

  3. From here you can edit the registry key values, or create new ones.

    • To edit a value, double-click any item in the Name column. An Edit String window displays.

      Edit String window

    • To create a new string value, right-click the last folder of the expanded node (PasswordSync), select New > String Value, and enter the applicable information.

      Registry Editor new string value

Registry key values

Authentication method

The following registry key values let you customize the authorization method between the plugin and IDM.

Key Value Description

authType

(Required)

The authentication type:

basic

Plain HTTP or SSL authentication.

idm

Plain HTTP or SSL authentication using IDM headers.

oauth2

Oauth2 authentication using AM bearer tokens.

cert

Mutual SSL authentication using a certificate.

By default, the plugin does not validate the IDM certificate. To enable validation, create the registry key value netSslVerifyPeer set to True.

netSslVerifyPeer

(Optional)

When using cert as the authentication type, you can create this value set to True to force validation of the IDM certificate.

authToken0

(Required)

The username or certificate path for authentication.

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

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

authToken1

(Required)

The authentication password.

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

For certificate authentication, set authToken1 to the keystore password.

encKey

(Optional)

The key the plugin uses to decrypt the values of authToken1, certPassword, and userSearchBindPass. The installer sets this key and encrypts the values of authToken1 and certPassword when you install the plugin. If you change any of these values later, encrypt the new value with the idmsync.exe --encrypt command, then replace the registry value with the encrypted result. For more information, refer to Registry Key Value Encryption.

If you do not want to encrypt the values of authToken1, certPassword, and userSearchBindPass, you must remove the registry key value encKey from the registry. The plugin reads those values as cleartext only when encKey is absent or empty.

Password encryption

The following registry key values let you customize the encryption method for captured passwords.

Key Value Description

certFile

(Required)

The path to the keystore used for encrypting captured passwords. For example, path/to/keystore.p12. Only PKCS #12 keystores are supported.

certPassword

(Required)

The certFile keystore password.

keyAlias

(Required)

The certFile keystore alias.

keyType

(Optional)

The certFile keystore encryption algorithm. For example, aes128. If not set, defaults to aes128.

Connection & synchronization

The password synchronization plugin assumes that the Active Directory user attribute is sAMAccountName. Although the default attribute works in most deployments, you can specify an alternative attribute. For an example, refer to Example userAttribute Modification.

Key Value Description

userAttribute

(Optional)

The attribute that identifies the Active Directory user. The password synchronization plugin assumes that the Active Directory user attribute is sAMAccountName. Used with userSearchFilter.

userSearchFilter

(Optional)

The search filter for locating Active Directory users.

Can only be used if userAttribute is also specified (even if the value is the default attribute sAMAccountName).

To use userSearchFilter with a special attribute such as memberOf, the filter only tests for immediate group memberships, and not for membership in the primary group (typically, cn=Users or cn=Domain Users) of your domain. The filter does not handle nested memberships. For example, User A is member of Group A, which is a member of Group B—although User A is technically a member of Group B, the filter will not interpret it as such.

idmURL

(Required)

The URL where IDM is deployed, including the query that targets each user account.

passwordAttr

(Required)

The password attribute for the managed/user object, such as adPassword.

oauth2Url

(Optional)

For the authentication type OAuth2 Access Token, the token URL. For example:

https://am.example.com/am/oauth2/realms/root/access_token

oauth2Scope

(Optional)

For the authentication type OAuth2 Access Token, the OAuth2 token scope. For example fr:idm:*.

userSearchBaseDn

(Optional)

The bind BaseDN used in the Active Directory user search. Use to set a different base dn for attribute search. Default value is derived from defaultNamingContext.

Can only be used if userAttribute is also specified (even if the value is the default attribute sAMAccountName). Used with userSearchFilter.

userSearchBindPass

(Optional)

The bind password used in the Active Directory user search.

When the encKey registry key value is present and non-empty, the plugin reads this value as encrypted, so you must encrypt it with the idmsync.exe --encrypt command. Otherwise, set this value in cleartext. If this value is cleartext while encKey is present, the plugin can’t use the value. For more information, refer to Registry Key Value Encryption. The installer doesn’t encrypt this value during plugin installation.

Can only be used if userAttribute is also specified (even if the value is the default attribute sAMAccountName). Used with userSearchFilter.

userSearchBindUser

(Optional)

The bind user used in the Active Directory user search.

Can only be used if userAttribute is also specified (even if the value is the default attribute sAMAccountName). Used with userSearchFilter.

userSearchFilterStrict

(Optional)

Additional control for the behavior of userSearchFilter:

  • If set to true, requires userSearchFilter to return a value, which you can use to filter out Active Directory users/groups from being password-synced.

  • The default behavior is false, which results in userSearchFilter only being used to look up the Active Directory user attribute, and if it fails, password synchronization is still attempted with a default attribute.

IDM availability

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

You can modify this behaviour with the following registry key values:

Key Value Description

dataPath

(Required)

The location where the password synchronization 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 their password three times in a row, you will refer to only one file containing the last change.

maxFileRetry

(Optional)

The maximum number of password change retry attempts after which the plugin stops attempting to send changes.

netTimeout

(Optional)

The length of time (in milliseconds) before the plugin stops attempting a connection.

pollEach

(Optional)

The interval (in seconds) between each attempt to send changes.

Logging configuration

Key Value Description

logPath

(Optional)

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

(Optional)

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

(Optional)

The severity of messages to log:

  • debug

  • info

  • warning

  • error

  • fatal

Other

Key Value Description

pwdChangeInterval

(Optional)

Infinite password sync loop prevention.

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.

This feature requires AD Password Synchronization Plugin version 1.4.0 or later. Because version 1.4.0 can fail to make a secure connection with certain Windows versions, Ping recommends using a later version.

Registry key value encryption

The plugin reads the values of the authToken1, certPassword, and userSearchBindPass keys with the encKey registry key value, which the installer sets during plugin installation. When encKey is present and non-empty, the plugin treats those values as encrypted and decrypts them each time it reads them. If you need to change any of these values, encrypt the new value manually with the idmsync.exe --encrypt command and replace the registry value with the encrypted result. You don’t need to restart the service after changing these values.

If you do not want to encrypt the values of the authToken1, certPassword, and userSearchBindPass keys, you must delete encKey from the registry. In this case, these values can be set in cleartext (unencrypted).

To encrypt the values of the authToken1, certPassword, and userSearchBindPass keys:

  1. Optionally, generate a new encryption key; otherwise, you can use the existing encryption key and skip this step.

    PS C:\Program Files\OpenIDM Password Sync> .\idmsync.exe --key

keyValue

  2. Encrypt the sensitive registry key values:

    PS C:\Program Files\OpenIDM Password Sync> .\idmsync.exe --encrypt "keyValue" "authToken1Value"

authToken1-keyValue
    PS C:\Program Files\OpenIDM Password Sync> .\idmsync.exe --encrypt "keyValue" "certPasswordValue"

certPasswordValue-keyValue

    If you use Active Directory user search with a bind password (userSearchBindPass), encrypt that value also:

    PS C:\Program Files\OpenIDM Password Sync> .\idmsync.exe --encrypt "keyValue" "userSearchBindPassValue"

userSearchBindPassValue-keyValue

  3. Replace the existing values of the encKey, authToken1, and certPassword keys with the generated values. If you encrypted userSearchBindPass, replace its value also.

    For instructions on editing registry key values, refer to Create or Edit Registry Key Values.

Registry key value validation

After you change a registry key value associated with the password synchronization plugin, run path\to\idmsync.exe --validate to perform validation. For example:

PS C:\Program Files\OpenIDM Password Sync> .\idmsync.exe --validate

OpenIDM Password Sync Service

Validating configuration parameters as user "Administrator"

Logging parameters:
logPath:
   "Z:\" has read/write access permissions.

logLevel:
   "error" is a valid logLevel entry.

logSize:
   "" is not a valid logSize entry. Will use default 5120000 byte file size limit.

Service and data storage parameters:
dataPath:
   "Z:\" has read/write access permissions.

pollEach:
   "75" is a valid pollEach entry.

OpenIDM service parameters:
idmURL:
   "https://localhost:8444/openidm/managed/user?_action=patch&_queryId=for-userName&uid=${samaccountname}" is a valid idmURL entry.

keyAlias:
   "openidm-cert" is a valid keyAlias entry.

passwordAttr:
   "adPassword" is a valid passwordAttr entry.

idm2Only:
   Service is configured to run with OpenIDM version 3.x or newer.

netTimeout:
   "" is not a valid netTimeout entry. Will use default 16 second network timeout.

authType, authToken0 and authToken1:
   Service is configured to use "OAuth2 Access Token" authentication
   "oauth2" is a valid authType entry.

Password encryption parameters:
certFile and certPassword:
   "Z:\openidm-localhost.crt" file is a valid entry.

Example userAttribute modification

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. The examples in the following table use the employeeId attribute instead of sAMAccountName.

For instructions on editing registry key values, refer to Create or Edit Registry Key Values.

Key Value Data

userAttribute

employeeId

userSearchFilter

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

idmURL

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