IDM 7.3.1

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 encryption key used to encrypt the values of authToken1 and certPassword. 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. For more information, refer to Registry Key Value Encryption.

If you do not want to encrypt the values of authToken1 and certPassword, you must remove the registry key value encKey from the registry.

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.

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, ForgeRock recommends using a later version.

Registry key value encryption

For security reasons, you should encrypt the values of the authToken1 and certPassword keys. During password synchronization plugin installation, they are encrypted automatically. If you need to change the values, you can encrypt the values manually by setting the encKey registry key value.

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

To encrypt the values of the authToken1 and certPassword:

  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

  3. Replace the existing values of encKey, authToken1 and certPassword keys with the generated values.

    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}