--- title: Configure the Active Directory password synchronization plugin description: Configure the Active Directory password synchronization plugin registry keys for authentication, encryption, sync, and logging component: pingidm version: 7.5 page_id: pingidm:pwd-plugin-guide:conf-ad-pwd-sync canonical_url: https://docs.pingidentity.com/pingidm/8.1/pwd-plugin-guide/conf-ad-pwd-sync.html llms_txt: https://docs.pingidentity.com/pingidm/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Password", "Synchronization", "Plugins", "Active Directory", "Configuration"] superseded_by: https://docs.pingidentity.com/pingidm/8.1/pwd-plugin-guide/conf-ad-pwd-sync.html section_ids: create-edit-regkey-values: Create or edit registry key values regkey-values: Registry key values authentication_method: Authentication method password_encryption: Password encryption connection_synchronization: Connection & synchronization ad-sync-keys-noidm: IDM availability logging_configuration: Logging configuration other: Other regkey-encryption: Registry key value encryption regkey-validation: Registry key value validation ad-pwd-userAttribute-mod: Example userAttribute modification --- # 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](#regkey-values). For information about creating registry keys, refer to the corresponding [Windows documentation](https://docs.microsoft.com/en-us/system-center/scsm/registry-keys). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------ | | | After you change a registry key value associated with the password synchronization plugin, [perform validation](#regkey-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](_images/ad-regedit.png) 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](_images/ad-regedit-edit.png) * 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](_images/ad-regedit-new-value.png) ## 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](#regkey-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](#ad-pwd-userAttribute-mod). | 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](#regkey-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 Identity 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. ```none 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](#create-edit-regkey-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: ```none 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](#create-edit-regkey-values). | Key Value | Data | | ------------------ | --------------------------------------------------------------------------------------------- | | `userAttribute` | `employeeId` | | `userSearchFilter` | `(&(objectClass=user)(sAMAccountName=%s))` | | `idmURL` | `https://localhost:8444/openidm/managed/user?_action=patch&_queryFilter=uid+eq+${employeeId}` |