Guide to configuring and integrating the password synchronization plugins into your IDM deployment.

Preface

ForgeRock Identity Platform™ is the only offering for access management, identity management, user-managed access, directory services, and an identity gateway, designed and built as a single, unified platform.

The platform includes the following components that extend what is available in open source projects to provide fully featured, enterprise-ready software:

  • ForgeRock Access Management (AM)

  • ForgeRock Identity Management (IDM)

  • ForgeRock Directory Services (DS)

  • ForgeRock Identity Gateway (IG)

1. About This Guide

In this guide you will learn how to use password synchronization plugins to synchronize passwords between ForgeRock Identity Management (IDM) and an LDAP server, either ForgeRock Directory Services (DS) or Active Directory.

This guide is written for systems integrators building solutions based on ForgeRock Identity Management services. This guide describes the two password synchronization plugins, and shows you how to set up and configure the plugins as part of your IDM deployment.

2. Formatting Conventions

Most examples in the documentation are created in GNU/Linux or Mac OS X operating environments. If distinctions are necessary between operating environments, examples are labeled with the operating environment name in parentheses. To avoid repetition file system directory names are often given only in UNIX format as in /path/to/server, even if the text applies to C:\path\to\server as well.

Absolute path names usually begin with the placeholder /path/to/. This path might translate to /opt/, C:\Program Files\, or somewhere else on your system.

Command-line, terminal sessions are formatted as follows:

$ echo $JAVA_HOME
/path/to/jdk

Command output is sometimes formatted for narrower, more readable output even though formatting parameters are not shown in the command.

Program listings are formatted as follows:

class Test {
    public static void main(String [] args)  {
        System.out.println("This is a program listing.");
    }
}

3. Accessing Documentation Online

ForgeRock publishes comprehensive documentation online:

  • The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.

    While many articles are visible to community members, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.

  • ForgeRock product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.

4. Using the ForgeRock.org Site

The ForgeRock.org site has links to source code for ForgeRock open source software, as well as links to the ForgeRock forums and technical blogs.

If you are a ForgeRock customer, raise a support ticket instead of using the forums. ForgeRock support professionals will get in touch to help you.

Chapter 1. Synchronizing Passwords Between IDM and an LDAP Server

Password synchronization ensures uniform password changes across the resources that store the password. After password synchronization, a user can authenticate with 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.

IDM can propagate passwords to the resources that store a user's password. In addition, you can download plugins from the ForgeRock BackStage site to intercept and synchronize passwords that are changed natively in ForgeRock Directory Services (DS) and Active Directory.

If you use these plugins to synchronize passwords, set up password policy enforcement on the LDAP resource, rather than on IDM. Alternatively, ensure that all password policies that are enforced are identical to prevent password updates on one resource from being rejected by IDM or by another resource.

The password synchronization plugin intercepts password changes on the LDAP resource before the passwords are stored in encrypted form. The plugin then sends the intercepted password value to IDM, using an HTTP POST request to patch the corresponding managed user object.

Note

The plugins do not use the LDAP connector to transmit passwords, but send a generic HTTP POST request with a patch-by-query action, similar to the following:

HTTP POST /managed/user?_action=patch-by-query&uid=bjensen&password=MyPassw0rd

If the IDM instance is unavailable when a password is changed in either DS or Active Directory, the respective password plugin intercepts the change, encrypts the password, and stores the encrypted password in a JSON file. The plugin then checks whether the IDM instance is available, at a predefined interval. When IDM becomes available, the plugin performs a PATCH on the managed user record, to replace the password with the encrypted password stored in the JSON file.

To be able to synchronize passwords, both password synchronization plugins require that the corresponding managed user object exist in the IDM repository.

The following sections describe how to use the password synchronization plugin for DS, and the corresponding plugin for Active Directory.

Chapter 2. Synchronizing Passwords With ForgeRock Directory Services (DS)

IDM must be installed, and running before you continue with the procedures in this section.

Important

Password synchronization with DS requires keys to encrypt the password and certificates to secure communications with IDM. In a production environment, you should use a certificate generated by a Certificate Authority. For evaluation or testing, you can use the self-signed certificate and key pair that are generated when you set up the DS server.

2.1. Establishing Secure Communication Between IDM and DS

There are three possible modes of communication between the DS password synchronization plugin and IDM:

  • SSL Authentication. In this case, you must import the IDM certificate into the DS truststore (either the self-signed certificate that is generated the first time IDM is started, or a CA-signed certificate).

    For more information, see Procedure 2.1, "To Import the IDM Certificate into the DS Keystore".

  • Mutual SSL Authentication. In this case, you must import the IDM certificate into the DS truststore, as described in Procedure 2.1, "To Import the IDM Certificate into the DS Keystore", and import the DS certificate into the IDM truststore, as described in Procedure 2.2, "To Import the DS Certificate into the IDM Truststore". You must also add the DS certificate DN as a value of the allowedAuthenticationIdPatterns property in your project's conf/authentication.json file. Mutual SSL authentication is the default configuration of the password synchronization plugin, and the one described in this procedure.

  • HTTP Basic Authentication. In this case, the connection is secured using a username and password, rather than any exchange of certificates. IDM supports basic authentication for testing purposes only. You should not use basic authentication in production. To configure the plugin for basic authentication, set the following properties in the plugin configuration:

    • ds-cfg-openidm-url

    • ds-cfg-openidm-username

    • ds-cfg-openidm-password

    For more information, see Section 2.2, "Installing the DS Password Synchronization Plugin". Note that the password sync plugin also requires the IDM certificate to encrypt the password such that it can be decrypted when it is replayed on IDM. Therefore, even if you use HTTP basic authentication, you must import the IDM certificate into the DS truststore, as described in Procedure 2.1, "To Import the IDM Certificate into the DS Keystore".

Procedure 2.1. To Import the IDM Certificate into the DS Keystore

Unless you use certificates signed by a well-known CA, you must export the certificate from the IDM keystore into the DS keystore to secure communication from IDM to DS.

IDM generates a self-signed certificate the first time it starts up. This procedure uses the self-signed certificate 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.

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:

    $ cd /path/to/openidm/security
    $ keytool \
     -export \
     -alias openidm-localhost \
     -file openidm-localhost.crt \
     -keystore 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 the DS keystore:

    $ cd /path/to/opendj/config
    $ keytool \
     -import \
     -alias openidm-localhost \
     -file /path/to/openidm/security/openidm-localhost.crt \
     -keystore keystore \
     -storepass:file keystore.pin \
     -storetype PKCS12 \
     -noprompt
    Certificate was added to keystore
  3. Create and enable a trust manager provider in DS:

    $ cd /path/to/opendj/bin
    $ ./dsconfig create-trust-manager-provider \
     --hostname localhost \
     --port 4444 \
     --bindDN "cn=Directory Manager" \
     --bindPassword password \
     --provider-name PKCS12 \
     --type file-based \
     --set enabled:true \
     --set trust-store-type:PKCS12 \
     --set trust-store-file:config/keystore \
     --set trust-store-pin-file:config/keystore.pin \
     --trustAll \
     --no-prompt
Procedure 2.2. To Import the DS Certificate into the IDM Truststore

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:

    $ cd /path/to/opendj/config
    $ keytool \
     -export \
     -alias server-cert \
     -file server-cert.crt \
     -keystore keystore \
     -storepass:file keystore.pin
    Certificate stored in file <server-cert.crt>
  2. Import the DS self-signed certificate into the IDM truststore:

    $ cd /path/to/openidm/security
    $ keytool \
     -importcert \
     -alias server-cert \
     -keystore truststore \
     -storepass changeit \
     -file /path/to/opendj/config/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
    }
         ...

2.2. Installing the DS Password Synchronization Plugin

The following steps install the password synchronization plugin on a DS directory server that is running on the same host as IDM (localhost). If you are running DS on a different host, use the fully qualified domain name instead of localhost.

You must use the plugin version that corresponds to your IDM and DS versions. For more information, see Table 2.1, "Supported Connectors, Connector Servers, and Plugins" in the Release Notes. This procedure assumes that you are using IDM 5.5 and DS 5.5.

  1. Download the password synchronization plugin (IDM-DS-account-change-notification-handler-${platform.long.version}.zip) from the ForgeRock BackStage site.

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

    $ unzip ~/Downloads/IDM-DS-account-change-notification-handler-${platform.long.version}.zip -d /path/to/opendj/
    Archive:  IDM-DS-account-change-notification-handler-${platform.long.version}.zip
       creating: opendj/
       ...
  3. 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
  4. 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 keystore. 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-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,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.

  5. 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
  6. 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-5.5.0-sources.jar'
     (build 5.5.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
  7. 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

Password synchronization should now be configured and working.

You can test that the setup has been successful as follows:

  1. Change a user password in DS.

    The new password should be synchronized to the corresponding IDM managed user account.

  2. Make sure that the PASSTHROUGH_AUTHENTICATION module is disabled (to ensure that the user is not authenticating with her DS credentials) and that the MANAGED_USER module is enabled (so that the user can authenticate with her managed user credentials).

  3. You should now be able to log into the Self Service UI (https://localhost:8443/#login/) as that user ID, with the new password.

2.3. Uninstalling the DS Password Synchronization Plugin

To uninstall the plugin, change the DS configuration as follows:

  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

Chapter 3. Synchronizing Passwords With Active Directory

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

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

3.1. Installing the Active Directory Password Synchronization Plugin

The following steps install the password synchronization on an Active directory server:

  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.

        OpenIDM architecture

        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

Password synchronization should now be configured and working. To test that the setup was successful, change a user password in Active Directory. That password should be synchronized to the corresponding IDM managed user account, and you should be able to query the user's own entry in IDM using the new password.

3.2. Changing the Password Synchronization Plugin Configuration After Installation

If you need to change any settings after installation, access the settings using the Registry Editor under HKEY_LOCAL_MACHINE > SOFTWARE > ForgeRock > OpenIDM > PasswordSync.

For information about creating registry keys, see Configure a Registry Item in the Windows documentation.

You can change the following registry keys to reconfigure the plugin:

Keys to set the method of authentication
  • authType sets the authentication type.

    For plain HTTP or SSL authentication using IDM headers, set authType to idm.

    For SSL mutual authentication using a certificate, set authType to cert.

    By default, the plugin does not validate the IDM certificate. To configure this validation, set the following registry key: netSslVerifyPeer = True.

  • authToken0 sets the username or certificate path for authentication.

    For example, for plain HTTP or SSL authentication, set authToken0 to openidm-admin.

    For SSL mutual authentication, set authToken0 to the certificate path, for example path/to/certificate/cert.p12. Only PKCS12 format certificates are supported.

  • authToken1 sets the password for authentication.

    For example, for plain HTTP or SSL authentication, set authToken1 to openidm-admin.

    For SSL mutual authentication, set authToken1 to the password to the keystore.

Keys to set encryption of captured passwords
  • certFile sets the path to the keystore used for encrypting captured passwords, for example path/to/keystore.p12. Only PKCS12 keystores are supported.

  • certPassword sets the password to the keystore.

  • keyAlias specifies the alias that is used to encrypt passwords.

  • keyType sets the cypher algorithm, for example aes128

Keys to set encryption of sensitive registry values

For security reasons, you should encrypt the values of the authToken1 and certPassword keys. 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.

Note

If you do not want to encrypt the values of the authToken1 and certPassword keys, you must remove the encKey from the registry, otherwise the plugin will use the value stored in that key to decrypt those values (even if they include an empty string).

To encrypt the values of the authToken1 and certPassword keys:

  1. Optionally, generate a new encryption key by running the following command:

    idmsync.exe --key
  2. Encrypt the values of the sensitive registry keys as follows:

    idmsync.exe --encrypt "key-value" "authToken1Value"
    idmsync.exe --encrypt "key-value" "certPasswordValue"
  3. Replace the existing values of the encyKey, authToken1 and certPassword keys with the values you generated in the previous step.

    If you do not want to generate a new encryption key, skip the first step and use the existing encryption key from the registry.

Keys to set the IDM connection information

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. These examples use the employeeId attribute instead of sAMAccountName:

  • userAttribute = employeeId

  • userSearchFilter = (&(objectClass=user)(sAMAccountName=%s))

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

Keys to set the behavior when IDM is unavailable

When IDM is unavailable, or when an update fails, the password synchronization plugin stores the user password change a JSON file on the Active Directory system and attempts to resend the password change at regular intervals.

After installation, you can change the behaviour by setting the following registry keys:

Also the netTimeout in milliseconds can be set.

  • dataPath - the location where the 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 his password three times in a row, you will see only one file containing the last change.

  • pollEach - the interval (in seconds) at which the plugin attempts to resend the changes.

  • netTimeout - the length of time (in milliseconds) after which the plugin stops attempting a connection.

Keys to set the logging configuration
  • logPath sets the path to the log file.

  • logSize - 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 sets the logging level, debug, info, warning, error, or fatal.

Key to configure support for older IDM versions

If the idm2only key is set to true, the plugin uses an old version of the patch request. This key must not exist in the registry for IDM versions 3.0 and later.

If you change any of the registry keys associated with the password synchronization plugin, run the idmsync.exe --validate command to make sure that all of the keys have appropriate values.

The password synchronization plugin is installed and run as a service named OpenIDM Password Sync Service. You can use the Windows Service Manager to start and stop the service. To start or stop the plugin manually, run the idmsync.exe --start or idmsync.exe --stop command.

3.3. Uninstalling the Active Directory Password Synchronization Plugin

You can uninstall the Active Directory Password Synchronization plugin from multiple locations:

  • Uninstall from the Windows Control Panel (Control Panel > Programs and Features, select OpenIDM Password Sync from the list and select Uninstall).

  • Run the uninstaller (unins000.exe) found in the OpenIDM Password Sync install directory (by default, C:\Program Files\OpenIDM Password Sync).

After the uninstaller has run, Windows will prompt you to restart. Restart to complete the uninstall process.

3.3.1. Removing Installed Authentication Certificates

If you selected to authenticate with mutual authentication, you can manually remove the IDM certificates you installed using the following steps:

  1. Open the Microsoft Management Console, expand Certificates - Current User > Personal, and select Certificates.

  2. Delete the previously installed certificate from the list of certificates.

  3. Repeat this process for:

    Certificates - Current User > Trusted Root Certification Authorities
    Certificates > Local Computer > Personal
    Certificates > Local Computer > Trusted Root Certification Authorities
  4. If the OpenIDM Password Sync service is still listed with stored certificates:

    1. Select File > Add/Remove Snap-in.

    2. Select Certificates - OpenIDM Password Sync from the column on the right and select Remove.

Chapter 4. Troubleshooting Password Sync

While default configuration settings work in many circumstances, some configurations introduce additional complexity that you should keep in mind during development. This chapter covers some known issues and how to address them.

4.1. Preventing Infinite Loops

Note

For the sake of simplicity, we reference Active Directory in this chapter, but all instructions are also applicable to DS unless otherwise noted.

In cases where the Active Directory syncs passwords with IDM in both directions, it is possible for a password update in Active Directory to trigger a password sync with IDM that is then sent as an update to the same Active Directory service that triggered the sync. This can cause an infinite loop, where Active Directory and IDM are constantly updating the password and telling the other system to do the same.

This can be prevented by making a few changes to your configuration:

  1. Update the user object in managed.json to add two new fields: adPassword, which should match the parameters for password; and adPasswordChange:

    ...
    “adPassword” : {
        “description” : “”,
        “title” : “adPassword”,
        “viewable” : true,
        “searchable” : false,
        “userEditable” : true,
        “policies” : [],
        ...
    “adPasswordChange” : {
        “description” : “”,
        “title” : “AD Flag Password Change”,
        “viewable” : true,
        “searchable” : false,
        “userEditable” : false,
        “policies” : [ ],
        “returnByDefault” : false,
        “minLength” : “”,
        “pattern” : “”,
        “type” : “string”
    },

  2. Update the onUpdate script referenced in managed.json to include a check comparing the updated adPassword with the old value, and updating password if there's a mismatch. Note that in cases where the password was changed outside of Active Directory, we also set adPasswordChange to true:

    ...
    var clear_old_object = openidm.decrypt(oldObject);
    var clear_new_object = openidm.decrypt(newObject);
    
    if (clear_new_object.adPassword != clear_old_object.adPassword) {
        newObject.password = newObject.adPassword;
        newObject.adPasswordChange = ‘false’;
        console.log(‘AD Plugin Changing the Password in OpenIDM’);
    } else if (clear_old_object.password != clear_new_object.password) {
        newObject.adPassword = newObject.password;
        newObject.adPasswordChange = ‘true’;
        console.log(‘User changing their password in OpenIDM ‘);
    }
    ...
         
  3. Update the mapping between IDM and Active Directory in sync.json to also check adPasswordChange. If adPasswordChange is true, the change needs to be sent to Active Directory:

    ...
    {
        “target” : “__PASSWORD__”,
        “source” : “password”,
        “condition” : {
            “type” : “text/javascript”,
            “globals” : { },
            “source” : “object.password != null && object.adPasswordChange == ‘true’;”
        }
    },
        

The DS password sync plugin defaults to password as the IDM user password attribute to sync. In order to use the solution outlined above, you will need to change the user password attribute the DS sync plugin is using to something unique (such as ldapPassword).

By default, the Active Directory password sync plugin installer sets adPassword as the IDM user password attribute to sync. Since this is already a distinct user password attribute from the password attribute found in the default user managed object, no further changes are needed to use this solution.

IDM Glossary

correlation query

A correlation query specifies an expression that matches existing entries in a source repository to one or more entries on a target repository. While a correlation query may be built with a script, it is not a correlation script.

As noted in Section 15.3.2.6, "Correlating Source Objects With Existing Target Objects" in the Integrator's Guide, you can set up a query definition, such as_queryId, _queryFilter, or_queryExpression, possibly with the help of alinkQualifier.

correlation script

A correlation script matches existing entries in a source repository, and returns the IDs of one or more matching entries on a target repository. While it skips the intermediate step associated with acorrelation query, a correlation script can be relatively complex, based on the operations of the script.

entitlement

An entitlement is a collection of attributes that can be added to a user entry via roles. As such, it is a specialized type of assignment. A user or device with an entitlement gets access rights to specified resources. An entitlement is a property of a managed object.

JSON

JavaScript Object Notation, a lightweight data interchange format based on a subset of JavaScript syntax. For more information, see the JSON site.

JSON Pointer

A JSON Pointer defines a string syntax for identifying a specific value within a JSON document. For information about JSON Pointer syntax, see the JSON Pointer RFC.

JWT

JSON Web Token. As noted in the JSON Web Token draft IETF Memo, "JSON Web Token (JWT) is a compact URL-safe means of representing claims to be transferred between two parties." For IDM, the JWT is associated with the JWT_SESSION authentication module.

managed object

An object that represents the identity-related data managed by IDM. Managed objects are configurable, JSON-based data structures that IDM stores in its pluggable repository. The default configuration of a managed object is that of a user, but you can define any kind of managed object, for example, groups or roles.

mapping

A policy that is defined between a source object and a target object during reconciliation or synchronization. A mapping can also define a trigger for validation, customization, filtering, and transformation of source and target objects.

OSGi

A module system and service platform for the Java programming language that implements a complete and dynamic component model. For a good introduction, see the OSGi site. Currently only the Apache Felix container is supported.

reconciliation

During reconciliation, comparisons are made between managed objects and objects on source or target systems. Reconciliation can result in one or more specified actions, including, but not limited to, synchronization.

resource

An external system, database, directory server, or other source of identity data to be managed and audited by the identity management system.

REST

Representational State Transfer. A software architecture style for exposing resources, using the technologies and protocols of the World Wide Web. REST describes how distributed data objects, or resources, can be defined and addressed.

role

IDM distinguishes between two distinct role types - provisioning roles and authorization roles. For more information, see Section 9.4, "Working With Managed Roles" in the Integrator's Guide.

source object

In the context of reconciliation, a source object is a data object on the source system, that IDM scans before attempting to find a corresponding object on the target system. Depending on the defined mapping, IDM then adjusts the object on the target system (target object).

synchronization

The synchronization process creates, updates, or deletes objects on a target system, based on the defined mappings from the source system. Synchronization can be scheduled or on demand.

system object

A pluggable representation of an object on an external system. For example, a user entry that is stored in an external LDAP directory is represented as a system object in IDM for the period during which IDM requires access to that entry. System objects follow the same RESTful resource-based design principles as managed objects.

target object

In the context of reconciliation, a target object is a data object on the target system, that IDM scans after locating its corresponding object on the source system. Depending on the defined mapping, IDM then adjusts the target object to match the corresponding source object.

Read a different version of :