How do I troubleshoot the DS Password Synchronization plugin in IDM (All versions)?

Overview

This article includes the following details that you should check (and rectify) in order to troubleshoot the DS password sync plugin in IDM:

• DS password sync flow
• Keystores and certificates
• IDM log
• SSL debugging
• DS configuration files
• IDM configuration files
• DS logs
• IDM audit logs

DS password sync flow

The expected DS password sync plugin flow is as follows:

1. DS receives an operation to modify an account password.
2. The DS password sync plugin is invoked and passes the cleartext password.
3. The DS password sync plugin encrypts the password and performs a Patch operation against the corresponding IDM managed user's ldapPassword attribute.
4. The onUpdate trigger within managed.json assigns the decrypted ldapPassword attribute value to the password attribute.
5. The Implicit sync process is triggered for the managed user to LDAP mapping.
6. The condition associated with the password attribute mapping is evaluated and returns false as the cleartext ldapPassword and password attribute values are the same.
7. The LDAP connector does not perform an update to DS as there are no modifications to be performed.

Avoiding loops

To ensure this flow is followed correctly and you do not end up with a loop whereby the password change originating from DS results in an update from IDM back to DS for the same LDAP entry, the condition associated with the password attribute mapping (sync.json file) should be similar to the following:

This mapping applies a condition to the sync of the password attribute, which is dependent upon the managed user's ldapPassword attribute value being different from the password attribute value.

Keystores and certificates

Incorrect keystore and certificate details can cause issues with the DS password sync plugin (some of which have been shown in the IDM log section below). The key things to check are:

1. The IDM certificate has been imported into the DS truststore.
2. The DS certificate has been imported into the IDM keystore. This step only applies if you have implemented mutual SSL authentication (server and client certificate authentication); the password sync plugin is configured to use mutual SSL authentication by default.
3. The encryption key used for the password is correct and present in both the DS truststore and the IDM keystore.

IDM certificate

This process is documented in the Enable DS to Trust the IDM Certificate.

You can check that the IDM certificate has been imported properly as follows:

1. Use the keytool command to list the certificate aliases in the IDM keystore to check which certificate is being used; this could be the openidm-localhost certificate or a CA certificate depending on your setup.
2. Use the keytool command to list the certificate aliases in the DS truststore and check that the certificate alias returned in step 1 is present. The following example keytool command shows that the openidm-localhost certificate has been imported into the DS keystore: $ keytool -list -keystore truststore -storetype JKS -storepass password -v Keystore type: JKS Keystore provider: SUN Your keystore contains 2 entries Alias name: openidm-localhost Creation date: May 19, 2021 Entry type: PrivateKeyEntry Certificate chain length: 1 Certificate[1]: Owner: CN=openidm-localhost, O=OpenIDM Self-Signed Certificate, OU=None, L=None, ST=None, C=None Issuer: CN=openidm-localhost, O=OpenIDM Self-Signed Certificate, OU=None, L=None, ST=None, C=None Serial number: 152f283769d Valid from: Valid from: Wed May 19 10:11:34 BST 2021 until: Thu May 19 10:11:34 BST 2022 Certificate fingerprints: SHA1: CC:09:33:57:F3:AE:BC:0F:D3:49:30:E2:5F:EA:AA:9F:43:67:65:B7 SHA256: B3:16:98:AD:97:D9:A0:5E:44:AE:FD:A8:35:4A:4E:84:59:EC:52:53:99:8C:4D:ED:DC:EB:1A:2B:22:0C:51:4A Signature algorithm name: SHA256withRSA Subject Public Key Algorithm: 2048-bit RSA key Version: 3 ******************************************* *******************************************

DS certificate

This process is documented in the Enable IDM to trust DS Certificates and is only required for mutual authentication, although the password sync plugin is configured to use mutual SSL authentication by default.

You can check that the DS certificate has been imported properly as follows:

1. Use the keytool command to list the certificate aliases in the IDM keystore and check that the server-cert certificate (or equivalent CA certificate depending on your setup) is being used.
2. Check that the certificate DN has been added as a value of the allowedAuthenticationIdPatterns property for the CLIENT_CERT authentication module in the authentication.json file (located in the /path/to/idm/conf directory).

Encryption key

The DS password is encrypted before it is sent to IDM. The encryption key used is openidm-localhost by default but could be different if you have changed it.

You should check the encryption key as follows:

1. Check which encryption key is actually being used by DS using one of the following methods. If this is not the key you expected, you should update the ds-cfg-private-key-alias property in the config.ldif file with the correct key:
   • Look for the value of the ds-cfg-private-key-alias property in the config.ldif file (located in the /path/to/ds/config directory).
   • Check the value of the private-key-alias property using the dsconfig command.
2. Check that this encryption key is present in both the DS truststore and the IDM keystore, otherwise IDM will not be able to decrypt the password when it is received. If it is not there, import it into the appropriate stores per the documentation links above.

IDM log

The IDM log (openidm.log, located in the /path/to/idm/logs directory) can be useful for identifying any issues with the password synchronization process from the IDM side. You should increase logging in the IDM debug log to FINEST (set the .level property to FINEST in logging.properties, which is located in the /path/to/idm/conf directory).

SSL and keys

If you see the following message in your IDM log after changing a password in DS, it means the SSL connection is working and the request has been received and successfully decrypted:

Although the SSL connection is working, you could still see errors if the provided key is unknown to IDM, for example:

If the SSL connection is not working, you will see a SSL handshake exception, for example:

Configuration issues

The following message indicates there is an issue with your configuration that is causing a loop whereby the password change originating from DS results in an update from IDM back to DS for the same LDAP entry:

To resolve this issue, you must prevent the managed user's password being synced to DS if the change originated from the DS password sync plugin. See the DS password sync flow section above for more details on achieving this. Alternatively, you can change the value of the ds-cfg-update-interval property (in the openidm-accountchange-plugin-sample-config file) to 1 or 2 seconds; this changes the sync operation to an asynchronous process and may resolve this issue

SSL debugging

SSL debugging traces the SSL handshaking phase. You can enable SSL debugging via the OPENIDM_OPTS environment variable.

• On Unix® and Linux® systems:$ cd /path/to/idm/ $ export OPENIDM_OPTS="-Djavax.net.debug=all" $ ./startup.sh
• On Microsoft® Windows® systems:C:\> cd \path\to\idm C:\path\to\idm> set OPENIDM_OPTS=-Djavax.net.debug=all C:\path\to\idm> startup.bat

DS configuration files

The following configuration files are useful to check how DS has been configured and how the password sync plugin has been configured on the DS side:

• config.ldif (located in the /path/to/ds/config directory).
• openidm-accountchange-plugin-sample-config (located in the /path/to/ds/config directory).

You can then compare the configuration on the DS side with the configuration on the IDM side to ensure they correspond and correct if necessary.

IDM configuration files

The following configuration files (located in the /path/to/idm/conf directory) are useful to check how synchronization has been configured on the IDM side and compare with the DS configuration:

• sync.json
• managed.json
• authentication.json
• provisioner configuration file for DS, for example provisioner.openicf-ldap.json.
• any associated scripts used to manage or transform the password attribute during sync, such as a separate onUpdate script (these are typically located in the /path/to/idm/script directory).

DS logs

The DS log files (access, errors and replication) can be useful for identifying any issues with the password synchronization process from the DS side. The logs collected should cover the period during which you are experiencing issues and the timestamps should correspond to the logs collected for IDM.

Enabling debug logging for the DS password sync plugin

You can enable debug logging for just the DS password sync plugin to minimize the size of the resulting DS logs as follows:

1. Enable debug logging using one of the following dsconfig commands depending on your version:
   • DS 7.1 and later: $ ./dsconfig set-log-publisher-prop --hostname ds.example.com --port 4444 --bindDN uid=admin --bindPassword password --publisher-name "File-Based Debug Logger" --set enabled:true --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
   • DS 7: $ ./dsconfig set-log-publisher-prop --hostname ds.example.com --port 4444 --bindDN uid=admin --bindPassword password --publisher-name "File-Based Debug Logger" --set enabled:true --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
   • DS 6.x: $ ./dsconfig set-log-publisher-prop --hostname ds.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --publisher-name "File-Based Debug Logger" --set enabled:true --trustAll --no-prompt
2. Set the debug target class using one of the following dsconfig commands depending on your version:
   • DS 7.1 and later: $ ./dsconfig create-debug-target --hostname ds.example.com --port 4444 --bindDN uid=admin --bindPassword password --publisher-name "File-Based Debug Logger" --type generic --target-name org.forgerock.openidm.accountchange.OpenidmAccountStatusNotificationHandler --set enabled:true --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
   • DS 7: $ ./dsconfig create-debug-target --hostname ds.example.com --port 4444 --bindDN uid=admin --bindPassword password --publisher-name "File-Based Debug Logger" --type generic --target-name org.forgerock.openidm.accountchange.OpenidmAccountStatusNotificationHandler --set enabled:true --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
   • DS 6.x: $ ./dsconfig create-debug-target --hostname ds.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --publisher-name "File-Based Debug Logger" --type generic --target-name org.forgerock.openidm.accountchange.OpenidmAccountStatusNotificationHandler --set enabled:true --trustAll --no-prompt

IDM audit logs

The IDM audit logs (located in the /path/to/idm/audit directory) can be useful for tracking system activity; the activity.csv file is particularly relevant.

See Also

DS (All versions) fail to start after upgrade if you use the Password Sync Plugin for IDM

How do I upgrade DS (All versions) if I have the DS Password Sync Plugin for IDM installed?

Password synchronization plugins

Related Training

ForgeRock Identity Management Deep Dive (IDM-420)

Related Issue Tracker IDs

N/A