12.2. Password Synchronization

OpenIDM Integrator's Guide
Chapter 12. Managing Passwords

Password synchronization intercepts user password changes, and ensures uniform password changes across resources that store the password. Following password synchronization, the user authenticates using the same password on each resource. No centralized directory or authentication server is required for performing authentication. Password synchronization reduces the number of passwords users need to remember, so they can use fewer, stronger passwords.

OpenIDM can propagate passwords to the resources storing a user's password. OpenIDM can intercept and synchronize passwords changed natively on OpenDJ and Active Directory. See the example in samples/misc/managed.json where you installed OpenIDM for a sample password synchronization configuration.

Before using the sample, you must set up OpenDJ and Active Directory, and adjust the password attributes, set in the sample as ldapPassword for OpenDJ, adPassword for Active Directory, and password for the internal OpenIDM password. Also, either set up password policy enforcement on OpenDJ or Active Directory rather than OpenIDM, or ensure that all password policies enforced are identical to prevent password updates on one resource from being rejected by OpenIDM or by another resource.

Also set up password synchronization plugins for OpenDJ and for Active Directory. The password synchronization plugins help by intercepting password changes on the resource before the passwords are stored in encrypted form. The plugins then send intercepted password values to OpenIDM over an encrypted channel.

Procedure 12.1. To Install the OpenDJ Password Synchronization Plugin

Before you start, make sure you configure OpenDJ to communicate over LDAPS as described in the OpenDJ documentation.

The following steps install the plugin in OpenDJ directory server running on the same host as OpenIDM. If you run OpenDJ on a different host use the fully qualified domain name rather than localhost, and use your certificates rather than the example.

Import the self-signed OpenIDM certificate into the trust store for OpenDJ.

$ cd /path/to/OpenDJ/config
$ keytool
 -import
 -alias openidm-localhost
 -keystore truststore
 -storepass `cat keystore.pin`
 -file /path/to/openidm/samples/security/openidm-localhost-cert.txt
Owner: CN=localhost, O=OpenIDM Self-Signed Certificate
Issuer: CN=localhost, O=OpenIDM Self-Signed Certificate
Serial number: 4e4bc38e
Valid from: Wed Aug 17 15:35:10 CEST 2011 until: Tue Aug 17 15:35:10 CEST 2021
Certificate fingerprints:
  MD5:  B8:B3:B4:4C:F3:22:89:19:C6:55:98:C5:DF:47:DF:06
  SHA1: DB:BB:F1:14:55:A0:53:80:9D:62:E7:39:FB:83:15:DA:60:63:79:D1
  Signature algorithm name: SHA1withRSA
  Version: 3
Trust this certificate? [no]:  yes
Certificate was added to keystore

Download the OpenDJ password synchronization plugin, OPENIDM AGENTS-OPENDJ, from the OpenIDM download page under the ForgeRock Open Stack download page.

Unzip the module delivery.

$ unzip ~/Downloads/opendj-accountchange-handler-.zip
   creating: opendj/
   creating: opendj/config/
   creating: opendj/config/schema/
...

Copy files to the directory where OpenDJ is installed.
```
$ cd opendj
$ cp -r * /path/to/OpenDJ/
```
Restart OpenDJ to load the additional schema from the module.
```
$ cd /path/to/OpenDJ/bin
$ ./stop-ds --restart
```

Add the configuration provided to OpenDJ's configuration.

$ ./ldapmodify
 --port 1389
 --hostname `hostname`
 --bindDN "cn=Directory Manager"
 --bindPassword "password"
 --defaultAdd
 --filename ../config/openidm-pwsync-plugin-config.ldif
Processing ADD request for cn=OpenIDM Notification Handler,
 cn=Account Status Notification Handlers,cn=config
ADD operation successful for DN cn=OpenIDM Notification Handler
 ,cn=Account Status Notification Handlers,cn=config

Restart OpenDJ.

$ ./stop-ds --restart
...
[16/Jan/2012:15:55:47 +0100] category=EXTENSIONS severity=INFORMATION
 msgID=1049147 msg=Loaded extension from file '/path/to/OpenDJ/lib/extensions
 /opendj-accountchange-handler-.jar' (build <unknown>,
 revision <unknown>)
...
[16/Jan/2012:15:55:51 +0100] category=CORE severity=NOTICE msgID=458891 msg=The
 Directory Server has sent an alert notification generated by class
 org.opends.server.core.DirectoryServer (alert type
 org.opends.server.DirectoryServerStarted, alert ID 458887):
 The Directory Server has started successfully

Enable the plugin for the appropriate password policy.

The following command enables the plugin for the default password policy.

$ ./dsconfig
 set-password-policy-prop
 --port 4444
 --hostname `hostname`
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --policy-name "Default Password Policy"
 --set account-status-notification-handler:"OpenIDM Notification Handler"
 --trustStorePath ../config/admin-truststore
 --no-prompt

Procedure 12.2. To Install the Active Directory Password Synchronization Plugin

Use the Active Directory password synchronization plugin to synchronize passwords between OpenIDM and Active Directory (on systems running at least Microsoft Windows 2008).

Install the plugin on Active Directory primary domain controllers (PDCs) to intercept password changes, and send the password values to OpenIDM over an encrypted channel. You must have Administrator privileges to install the plugin. In a clustered Active Directory environment, you must also install the plugin on all PDCs.

Download the Active Directory password synchronization plugin, AD CONNECTOR, from the OpenIDM download page under the ForgeRock Open Stack download page.
Unzip the plugin, and double-click setup.exe to launch the installation wizard.
Complete the installation with the help of the following hints.

CDDL license agreement

You must accept the agreement to proceed with the installation.

OpenIDM URL

URL where OpenIDM is deployed such as https://openidm.example.com:8444/openidm for SSL mutual authentication

Private Key alias

Alias used for the OpenIDM certificate also stored in the keystore.jceks file, such as openidm-localhost used for evaluation

Private Key password

Password to access the PFX keystore file, such as changeit for evaluation. PFX files contain encrypted private keys, certificates used for authentication and encryption.

Directory poll interval (seconds)

Number of seconds between calls to check that Active Directory is available, such as 60

Query ID parameter

Query identifier configured in OpenIDM the openidm/conf/repo.*.json file. Use for-userName for evaluation.

OpenIDM user password attribute

Password attribute for the managed/user object to which OpenIDM applies password changes

OpenIDM user search attribute

The sAMAccountName value holder attribute name in the query definition. For example, "SELECT * FROM ${unquoted:_resource} WHERE userName = ${uid}". Use uid for the evaluation.

Select Certificate File

The PKCS 12 format PFX file containing the certificate used to encrypt communications with OpenIDM. Use openidm/samples/security/openidm-localhost.p12 for evaluation.

Select Output Directory

Select a secure directory where the password changes are queued. The queue contains the encrypted passwords. Yet, the server has to prevent access to this folder except access by the Password Sync service. The path name cannot include spaces.

Select Log Directory

The plugin stores logs in the location you select. The path name cannot include spaces.

Select Destination Location

Setup installs the plugin in the location you select, by default C:\Program Files\OpenIDM Password Sync.
After running the installation wizard, restart the computer.
If you must change any settings after installation, access settings using the Registry Editor under HKEY_LOCAL_MACHINE > SOFTWARE > ForgeRock > OpenIDM > PasswordSync.

Procedure 12.3. To Set Up OpenIDM to Handle Password Changes

Follow these steps to configure OpenIDM to access password changes from the directory server.

Add the directory server certificate to the OpenIDM trust store so that OpenIDM knows to trust the directory server during mutual authentication.

The following commands show how to do this with the default OpenDJ and OpenIDM settings.

$ cd /path/to/OpenDJ/config/
$ keytool
 -keystore keystore
 -storepass `cat keystore.pin`
 -export
 -alias server-cert
 > /tmp/opendj.crt
$ cd /path/to/openidm/security/
$ keytool
 -import
 -alias opendj-server-cert
 -file /tmp/opendj.crt
 -keystore truststore
 -storepass changeit
 -trustcacerts
Owner: CN=localhost.localdomain, O=OpenDJ Self-Signed Certificate
Issuer: CN=localhost.localdomain, O=OpenDJ Self-Signed Certificate
Serial number: 4f143976
Valid from: Mon Jan 16 15:51:34 CET 2012 until: Wed Jan 15 15:51:34 CET 2014
Certificate fingerprints:
   MD5:  7B:7A:75:FC:5A:F0:65:E5:84:43:6D:10:B9:EA:CC:F0
   SHA1: D1:C6:C9:8A:EA:09:FD:1E:48:BB:B2:F5:95:41:50:2C:AB:4D:0F:C9
   Signature algorithm name: SHA1withRSA
   Version: 3
Trust this certificate? [no]:  yes
Certificate was added to keystore

Add the configuration to managed objects to handle password synchronization.

You can find an example for synchronization with both OpenDJ and Active Directory in samples/misc/managed.json, JavaScript lines folded for readability:

{
    "objects": [
        {
            "name": "user",
            "properties": [
                {
                    "name": "ldapPassword",
                    "encryption": {
                        "key": "openidm-sym-default"
                    }
                },
                {
                    "name": "adPassword",
                    "encryption": {
                        "key": "openidm-sym-default"
                    }
                },
                {
                    "name": "password",
                    "encryption": {
                        "key": "openidm-sym-default"
                    }
                }
            ],
            "onUpdate": {
                "type": "text/javascript",
                "source":
                 "if (newObject.ldapPassword != oldObject.ldapPassword) {
                     newObject.password = newObject.ldapPassword
                  } else if (newObject.adPassword != oldObject.adPassword) {
                      newObject.password = newObject.adPassword
                  }"
            }
        }
    ]
}

This sample assumes you define the password as ldapPassword for OpenDJ, and adPassword for Active Directory.

When you change a password in OpenDJ, you will notice that the value changes in OpenIDM.
```
$ tail -f openidm/audit/activity.csv | grep bjensen
...userName=bjensen, ... password={$crypto={...data=tEsy7ZXo6nZtEqzW/uVE/A==...
...userName=bjensen, ... password={$crypto={...data=BReT79lnQEPcvfQG3ibLpg==...
```
Be aware that the plugin is patching the password value of the managed user in OpenIDM. The target password property must exist for the patch to work. After the password has been updated in OpenIDM, automatic synchronization is launched and the password is updated in Active Directory.

OpenIDM Integrator's GuideChapter 12. Managing Passwords

12.2. Password Synchronization

OpenIDM Integrator's Guide
Chapter 12. Managing Passwords