IDM generates a self-signed certificate the first time it starts up. This procedure uses the self-signed certificate to demonstrate how to get the password synchronization plugin up and running. In a production environment, you should use a certificate that has been signed by a Certificate Authority (CA).

The default Java truststore contains signing certificates from well-known CAs. If your CA certificate is not in the default truststore, or if you are using a self-signed certificate, import it into a DS truststore as described here.

DS does not enable a trust manager provider by default. For DS to trust the IDM certificate, you must enable a trust manager provider and reference it from the password plugin configuration.

1. Export the IDM generated self-signed certificate to a file, as follows:

   $ keytool \
    -export \
    -alias openidm-localhost \
    -file openidm-localhost.crt \
    -keystore /path/to/openidm/security/keystore.jceks \
    -storetype jceks
   Enter keystore password: changeit
   Certificate stored in file <openidm-localhost.crt>

   The default IDM keystore password is changeit.

2. Import the self-signed certificate into a DS truststore. The following command creates a new truststore file and imports the certificate:

   $ keytool \
    -import \
    -alias openidm-localhost \
    -file openidm-localhost.crt \
    -keystore /path/to/opendj/config/truststore \
    -storepass:file /path/to/opendj/config/keystore.pin \
    -storetype PKCS12 \
    -noprompt
   Certificate was added to keystore

3. Add a trust manager provider to access the truststore:

   $ cd /path/to/opendj/bin
   $ ./dsconfig \
    create-trust-manager-provider \
    --hostname localhost \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --type file-based \
    --provider-name "PKCS12 Trust Manager" \
    --set enabled:true \
    --set trust-store-file:/path/to/opendj/config/truststore \
    --set trust-store-pin:"&{file:/path/to/opendj/config/keystore.pin}" \
    --trustAll \
    --no-prompt
   The File Based Trust Manager Provider was created successfully

For mutual authentication, you must import the DS certificate into the IDM truststore.

DS generates a self-signed certificate when you set up communication over LDAPS. This procedure uses the self-signed certificate to get the password synchronization plugin up and running. In a production environment, use a certificate that has been signed by a Certificate Authority.

1. Export the generated DS self-signed certificate to a file, as follows:

   $ keytool \
    -export \
    -alias server-cert \
    -file server-cert.crt \
    -keystore /path/to/opendj/config/keystore \
    -storepass:file /path/to/opendj/config/keystore.pin
   Certificate stored in file <server-cert.crt>

2. Import the DS self-signed certificate into the IDM truststore:

   $ keytool \
    -importcert \
    -alias server-cert \
    -keystore /path/to/openidm/security/truststore \
    -storepass changeit \
    -file server-cert.crt
   Owner: CN=localhost, O=OpenDJ RSA Self-Signed Certificate
   Issuer: CN=localhost, O=OpenDJ RSA Self-Signed Certificate
   ...
   Trust this certificate? [no]: yes
   Certificate was added to keystore

3. Add the certificate DN as a value of the allowedAuthenticationIdPatterns property for the CLIENT_CERT authentication module, in your project's conf/authentication.json file.

   For example, if you are using the DS self-signed certificate, add the DN "CN=localhost, O=OpenDJ RSA Self-Signed Certificate, OU=None, L=None, ST=None, C=None", as shown in the following excerpt:

   $ more /path/to/openidm/project-dir/conf/authentication.json
   ...
   {
        "name" : "CLIENT_CERT",
        "properties" : {
            "queryOnResource" : "security/truststore",
            "defaultUserRoles" : [
                "openidm-cert"
            ],
            "allowedAuthenticationIdPatterns" : [
                "CN=localhost, O=OpenDJ RSA Self-Signed Certificate, OU=None, L=None, ST=None, C=None"
            ]
        },
        "enabled" : true
   }
        ...

1. Download the password synchronization plugin (DS-IDM-account-change-notification-handler-6.0.0.7.zip) from the ForgeRock BackStage site.

2. Extract the contents of the .zip file to the directory where DS is installed:

   $ unzip ~/Downloads/DS-IDM-account-change-notification-handler-6.0.0.7.zip -d /path/to/opendj/
   Archive:  DS-IDM-account-change-notification-handler-6.0.0.7.zip
      creating: opendj/
      ...

3. Move 90-openidm-accountchange-plugin.ldif from /path/to/opendj/config/schema/ to /path/to/opendj/db/schema/:

   $ mv config/schema/90-openidm-accountchange-plugin.ldif db/schema/

4. Restart DS to load the additional schema from the password synchronization plugin:

   $ cd /path/to/opendj/bin
   $ ./stop-ds --restart
   Stopping Server...
   ...
   [23/Nov/2016:13:19:11 +0200] category=EXTENSIONS severity=NOTICE
    msgID=org.opends.messages.extension.571 msg=Loaded extension from file
    '/path/to/opendj/lib/extensions/openidm-account-change-handler.jar' (build version, revision 1)
   ...
   [23/Nov/2016:13:19:43 +0200] category=CORE severity=NOTICE msgID=org.opends.messages.core.139
   ... The Directory Server has started successfully

5. Configure the password synchronization plugin.

   The password plugin configuration is specified in the openidm-accountchange-plugin-sample-config file which should have been extracted to path/to/opendj/config when you extracted the plugin.

   Use a text editor to update the configuration, for example:

   $ cd /path/to/opendj/config
   $ more openidm-accountchange-plugin-sample-config
   dn: cn=OpenIDM Notification Handler,cn=Account Status Notification Handlers,cn=config
   objectClass: top
   objectClass: ds-cfg-account-status-notification-handler
   objectClass: ds-cfg-openidm-account-status-notification-handler
   cn: OpenIDM Notification Handler
   ...

   At a minimum, you must set the value of the ds-cfg-trust-manager-provider property, as the default value references a trust manager provider that does not exist. In addition, you can configure the following elements of the plugin:

   ds-cfg-enabled

   Specifies whether the plugin is enabled.

   Default value: true

   ds-cfg-attribute

   The attribute in IDM that stores user passwords. This property is used to construct the patch request on the IDM managed user object.

   Default value: password

   ds-cfg-query-id

   The query-id for the patch-by-query request. This query must be defined in the repository configuration.

   Default value: for-userName

   ds-cfg-attribute-type

   Specifies zero or more attribute types that the plugin will send along with the password change. If no attribute types are specified, only the DN and the new password will be synchronized to IDM.

   Default values: entryUUID and uid

   ds-cfg-log-file

   The directory where plugin log files are written, and where modified passwords are written when the plugin cannot contact IDM. The default location is a directory named /path/to/opendj/logs/pwsync. Passwords in this directory will be encrypted.

   Default value: logs/pwsync

   Note that this setting has no effect if ds-cfg-update-interval is set to 0 seconds.

   ds-cfg-update-interval

   The interval, in seconds, at which password changes are propagated to IDM. If this value is 0, updates are made synchronously in the foreground, and no encrypted passwords are stored in the ds-cfg-log-file directory.

   Default value: 0 seconds

   ds-cfg-openidm-url

   The endpoint at which the plugin should find IDM managed user accounts.

   Default value: https://localhost:8444/openidm/managed/user

   For HTTP basic authentication, specify the http protocol in the URL, and a non-mutual authentication port, for example http://localhost:8080/openidm/managed/user.

   ds-cfg-ssl-cert-nickname

   The alias of the client certificate in the DS truststore. The default client key alias is server-cert. Do not use this self-signed certificate in production.

   Default value: server-cert

   ds-cfg-private-key-alias

   The alias of the private key that should be used by IDM to decrypt the session key.

   Default value: openidm-localhost

   ds-cfg-request-retry-attempts

   Sets the number of times the plugin will attempt a synchronization request if the first attempt fails. If this value is zero, the request is not retried. If the value is more than zero, the request will be retried that number of additional times before the request is removed from the queue. Note that if ds-cfg-update-interval is set to zero, the request will not be retried regardless of what this property is set to.

   In cases where a request fails for a transient reason (such as when IDM is down or the connection is timing out), the number of retry attempts will not decrement. The reason the request failed will be included in logs, and attempts will continue to occur until IDM responds.

   Default value: 0

   ds-cfg-certificate-subject-dn

   The certificate subject DN of the IDM private key. The default configuration assumes that you are using the self-signed certificate that is generated when IDM first starts.

   Default value: CN=localhost, O=OpenIDM Self-Signed Certificate, OU=None, L=None, ST=None, C=None

   ds-cfg-key-manager-provider

   The DS key manager provider. The key manager provider specified here must be enabled. If you do not specify a keystore, the default configuration references a PKCS#12 keystore file that contains a self-signed certificate.

   Default value: cn=Default Key Manager,cn=Key Manager Providers,cn=config

   ds-cfg-trust-manager-provider

   The DS trust manager provider. The trust manager provider specified here must be enabled. Before you use the plugin, you must create a trust manager provider and set this value accordingly.

   Default value: cn=PKCS12 Trust Manager,cn=Trust Manager Providers,cn=config

   ds-cfg-openidm-username

   An IDM administrative username that the plugin will use to make REST calls to IDM.

   Default value: openidm-admin

   For SSL authentication and HTTP basic authentication, the user specified here must have the rights to patch managed user objects.

   This property is commented out by default, because the default configuration assumes mutual SSL authentication. If you use HTTP or SSL authentication, you must uncomment this property.

   ds-cfg-openidm-password

   The password of the IDM administrative user specified in the previous property.

   Default value: openidm-admin

   This property is commented out by default, because the default configuration assumes mutual SSL authentication. If you use HTTP or SSL authentication, you must uncomment this property.

   If you are using mutual authentication, the default configuration might be suitable for your deployment. Otherwise, update the plugin configuration as required.

6. Add the plugin configuration to the DS configuration:

   $ cd /path/to/opendj/bin
   $ ./ldapmodify \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword "password" \
    ../config/openidm-accountchange-plugin-sample-config
   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

7. Restart DS for the new configuration to take effect:

   $ ./stop-ds --restart
   Stopping Server...
   ...
   [23/Nov/2016:13:25:50 +0200] category=EXTENSIONS severity=NOTICE
    msgID=org.opends.messages.extension.571 msg=Loaded extension from file
    '/path/to/opendj/lib/extensions/opendj-openidm-account-change-notification-handler-4.0.0-sources.jar'
    (build 4.0.0, revision 1)
   ...
   [23/Nov/2016:13:26:27 +0200] category=CORE severity=NOTICE msgID=org.opends.messages.core.139
    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 org.opends.messages.core-135): The Directory Server has started successfully

8. Adjust your DS password policy configuration to use the password synchronization plugin.

   The following command adjusts the default password policy:

   $ cd /path/to/opendj/bin
   $ ./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" \
    --no-prompt

1. Reset your DS password policy configuration so that it no longer uses the password synchronization plugin.

   The following command resets the default password policy:

   $ cd /path/to/opendj/bin
   $ ./dsconfig \
    set-password-policy-prop \
    --port 4444 \
    --hostname `hostname` \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --policy-name "Default Password Policy" \
    --reset account-status-notification-handler \
    --no-prompt

2. Delete the IDM Notification Handler from the DS configuration:

   $ ./dsconfig \
    delete-account-status-notification-handler \
    --port 4444 \
    --hostname `hostname` \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --handler-name "OpenIDM Notification Handler" \
    --no-prompt
   The Account Status Notification Handler was deleted successfully

3. Remove the password synchronization plugin from the DS extensions:

   $ cd /path/to/opendj
   $ rm lib/extensions/opendj-openidm-account-change-notification-handler*

4. Restart DS for the new configuration to take effect:

   $ cd /path/to/opendj/bin
   $ ./stop-ds --restart

1. Download the Active Directory password synchronization plugin from the ForgeRock BackStage site.

2. Install the plugin using one of the following methods:

   • Double-click the setup file to launch the installation wizard.

   • Alternatively, from a command-line, start the installation wizard with the idm-setup.exe command. To save the settings in a configuration file, use the /saveinf switch as follows:

     PS C:\path\to\dir> idm-setup.exe /saveinf=C:\temp\adsync.inf

   • If you have a configuration file with installation parameters, you can install the password plugin in silent mode as follows:

     PS C:\path\to\dir> idm-setup.exe /verysilent /loadinf=C:\temp\adsync.inf

3. Provide the following information during the installation. You must accept the license agreement shown to proceed with the installation:

   OpenIDM Connection information

   • OpenIDM URL. Enter the URL where IDM is deployed, including the query that targets each user account. For example:

     https://localhost:8444/openidm/managed/user?_action=patch&_queryId=for-userName&uid=${samaccountname}

   • OpenIDM User Password attribute. The password attribute for the managed/user object, such as password.

     If the password attribute does not exist in the IDM managed/user object, the password sync service will return an error when it attempts to replay a password update that has been made in Active Directory. If your managed user objects do not include passwords, you can add an onCreate script to the Active Directory > Managed Users mapping that sets an empty password when managed user accounts are created. The following excerpt of a sample sync.json file shows such a script in the mapping:

     "mappings" : [
      {
        "name" : "systemAdAccounts_managedUser",
        "source" : "system/ad/account",
        "target" : "managed/user",
        "properties" : [
          {
            "source" : "sAMAccountName",
            "target" : "userName"
          }
        ],
        "onCreate" : {
          "type" : "text/javascript",
          "source" : "target.password=''"
        },
     ...

     The onCreate script creates an empty password in the managed/user object, so that the password attribute exists and can be patched.

   OpenIDM Authentication Parameters

   Provide the following information:

   • User name. Enter the name of an administrative user that can authenticate to IDM, for example, openidm-admin.

   • Password. Enter the password of the user that authenticates to IDM, for example, openidm-admin.

   • Select authentication type. Select the type of authentication that Active Directory will use to authenticate to IDM.

     For plain HTTP authentication, select OpenIDM Header. For SSL mutual authentication, select Certificate.

   Certificate authentication settings

   If you selected Certificate as the authentication type on the previous screen, specify the details of the certificate that will be used for authentication.

   • Select Certificate file. Browse to select the certificate file that Active Directory will use to authenticate to IDM. The certificate file must be configured with an appropriate encoding, cryptographic hash function, and digital signature. The plugin can read a public or a private key from a PKCS12 archive file.

     For production purposes, you should use a certificate that has been issued by a Certificate Authority. For testing purposes, you can generate a self-signed certificate. Whichever certificate you use, you must import that certificate into the IDM trust store.

     To generate a self-signed certificate for Active Directory, follow these steps:

     1. On the Active Directory host, generate a private key, which will be used to generate a self-signed certificate with the alias ad-pwd-plugin-localhost:

        > keytool.exe ^
         -genkey ^
         -alias ad-pwd-plugin-localhost ^
         -keyalg rsa ^
         -dname "CN=localhost, O=AD-pwd-plugin Self-Signed Certificate" ^
         -keystore keystore.jceks ^
         -storetype JCEKS
        Enter keystore password: changeit
        Re-enter new password: changeit
        Enter key password for <ad-pwd-plugin-localhost>
              <RETURN if same as keystore password>

     2. Now use the private key, stored in the keystore.jceks file, to generate the self-signed certificate:

        > keytool.exe ^
         -selfcert ^
         -alias ad-pwd-plugin-localhost ^
         -validity 365 ^
         -keystore keystore.jceks ^
         -storetype JCEKS ^
         -storepass changeit

     3. Export the certificate. In this case, the keytool command exports the certificate in a PKCS12 archive file format, used to store a private key with a certificate:

        > keytool.exe ^
         -importkeystore ^
         -srckeystore keystore.jceks ^
         -srcstoretype jceks ^
         -srcstorepass changeit ^
         -srckeypass changeit ^
         -srcalias ad-pwd-plugin-localhost ^
         -destkeystore ad-pwd-plugin-localhost.p12 ^
         -deststoretype PKCS12 ^
         -deststorepass changeit ^
         -destkeypass changeit ^
         -destalias ad-pwd-plugin-localhost ^
         -noprompt

     4. The PKCS12 archive file is named ad-pwd-plugin-localhost.p12. Import the contents of the keystore contained in this file to the system that hosts IDM. To do so, import the PKCS12 file into the IDM keystore file, named truststore, in the /path/to/openidm/security directory.

        On the machine that is running IDM, enter the following command:

        $ keytool \
         -importkeystore \
         -srckeystore /path/to/ad-pwd-plugin-localhost.p12 \
         -srcstoretype PKCS12 \
         -destkeystore truststore \
         -deststoretype JKS

   • Password to open the archive file with the private key and certificate. Specify the keystore password (changeit, in the previous example).

   Password Encryption settings

   Provide the details of the certificate that will be used to encrypt password values.

   • Select certificate file. Browse to select the certificate that will be used for password encryption. The certificate must be in PKCS12 format.

     For evaluation purposes, you can use a self-signed certificate, as described earlier. For production purposes, you should use a certificate that has been issued by a Certificate Authority.

     Whichever certificate you use, the certificate must be imported into the IDM keystore, so that IDM can locate the key with which to decrypt the data. To import the certificate into the IDM keystore, keystore.jceks, run the following command on the IDM host (UNIX):

     $ keytool \
      -importkeystore \
      -srckeystore /path/to/ad-pwd-plugin-localhost.p12 \
      -srcstoretype PKCS12 \
      -destkeystore /path/to/openidm/security/keystore.jceks \
      -deststoretype jceks

   • Private key alias. Specify the alias for the certificate, such as ad-pwd-plugin-localhost. The password sync plugin sends the alias when communicating with IDM, which uses the alias to retrieve the corresponding private key in IDM's keystore.

   • Password to open certificate file. Specify the password to access the PFX keystore file, such as changeit, from the previous example.

   • Select encryption standard. Specify the encryption standard that will be used when encrypting the password value (AES-128, AES-192, or AES-256).

     If you select an encryption key type greater than AES-128, you must install the Unlimited JCE Policy for your JRE, on the machine on which the password sync plugin is installed. To install the unlimited JCE Policy, follow these steps:

     • Download the JCE zip file for Java 8 from the Oracle Technology Network site.

     • Locate the lib\security folder of your JRE, for example, C:\Program Files\Java\jre8\lib\security.

     • Remove the following .jar files from the lib\security folder:

       local_policy.jar

       US_export_policy.jar

     • Unzip the JCE zip file and copy the two _policy.jar files to the lib\security folder of your JRE.

     • If the password sync plugin is already running, you must restart it for the installation of the JCE policy files to take effect.

   Data storage

   Provide the details for the storage of encrypted passwords in the event that IDM is not available when a password modification is made.

   • Select a secure directory in which the JSON files that contain encrypted passwords are queued. The server should prevent access to this folder, except access by the Password Sync service. The path name cannot include spaces.

   • Directory poll interval (seconds). Enter the number of seconds between calls to check whether IDM is available, for example, 60, to poll IDM every minute.

   Log storage

   Provide the details of the messages that should be logged by the plugin.

   • Select the location to which messages should be logged. The path name cannot include spaces.

   • Select logging level. Select the severity of messages that should be logged, either error, info, warning, fatal, or debug.

   Select Destination Location

   Setup installs the plugin in the location you select, by default C:\Program Files\OpenIDM Password Sync.

4. After running the installation wizard, restart the computer.

5. If you selected to authenticate over plain HTTP in the previous step, your setup is now complete.

   If you selected to authenticate with mutual authentication, complete this step.

   1. The Password Sync Service uses Windows certificate stores to verify IDM's identity. The certificate that IDM uses must therefore be added to the list of trusted certificates on the Windows machine.

      In a production environment, use a certificate that has been issued by a certificate authority. For test purposes, you can use the self-signed certificate that is generated by IDM on first startup.

      To add the IDM certificate to the list of trusted certificates, use the Microsoft Management Console.

      1. Select Start and type mmc in the Search field.

      2. In the Console window, select File > Add/Remove Snap-in.

      3. From the left hand column, select Certificates and click Add.

      4. Select My user account, and click Finish.

      5. Repeat the previous two steps for Service account and Computer account.

         For Service account, select Local computer, then select OpenIDM Password Sync Service.

         

         For Computer account, select Local computer.

      6. Click Finish when you have added the three certificate snap-ins.

      7. Still in the Microsoft Management Console, expand Certificates - Current User > Personal and select Certificates.

      8. Select Action > All Tasks > Import to open the Certificate Import Wizard.

      9. Browse for the IDM certificate (openidm-localhost.crt by default, if you use IDM's self-signed certificate).

      10. Enter the Password for the certificate (changeit by default, if you use the IDM self-signed certificate).

      11. Accept the default for the Certificate Store.

      12. Click Finish to complete the import.

      13. Repeat the previous six steps to import the certificate for:

          Certificates - Current User > Trusted Root Certification Authorities

          Certificates - Service > OpenIDM Password Sync\Personal

          Certificates - Service > OpenIDM Password Sync\Trusted Root Certification Authorities

          Certificates > Local Computer > Personal

          Certificates > Local Computer > Trusted Root Certification Authorities