Managing Passwords OpenIDM provides password management features that help you enforce password policies, limit the number of passwords users must remember, and let users reset and change their passwords. Enforcing Password Policy A password policy is a set of rules defining what sequence of characters constitutes an acceptable password. Acceptable passwords generally are too complex for users or automated programs to generate or guess. Password policies set requirements for password length, character sets that passwords must contain, dictionary words and other values that passwords must not contain. Password policies also require that users not reuse old passwords, and that users change their passwords on a regular basis. OpenIDM enforces password policy rules as part of the general policy service. For more information about the policy service, see "Using Policies to Validate Data". The default password policy applies the following rules to passwords as they are created and updated: A password property is required for any user object. The value of a password cannot be empty. The password must include at least one capital letter. The password must include at least one number. The minimum length of a password is 8 characters. The password cannot contain the user name, given name, or family name. You can remove these validation requirements, or include additional requirements, by configuring the policy for passwords. For more information, see "Configuring the Default Policy for Managed Objects". The password validation mechanism can apply in many situations. Password change and password reset Password change involves changing a user or account password in accordance with password policy. Password reset involves setting a new user or account password on behalf of a user. By default, OpenIDM controls password values as they are provisioned. To change the default administrative user password, openidm-admin, see "Replace Default Security Settings". Password recovery Password recovery involves recovering a password or setting a new password when the password has been forgotten. OpenIDM provides a self-service end user interface for password changes, password recovery, and password reset. For more information, see "Configuring User Self-Service". Password comparisons with dictionary words You can add dictionary lookups to prevent use of password values that match dictionary words. Password history You can add checks to prevent reuse of previous password values. For more information, see "Creating a Password History Policy". Password expiration You can configure OpenIDM to call a workflow that ensures users are able to change expiring or to reset expired passwords. Creating a Password History Policy To create a password history policy, you need to include customized scripts as described in "Storing Multiple Passwords For Managed Users" in the Samples Guide. Copy these scripts to your`project-dir/script` directory. You also need to modify the following configuration files: Modify the sync.json file to include connections to the custom onCreate-onUpdate-sync.js script: "onCreate" : { "type" : "text/javascript", "file" : "script/onCreate-onUpdate-sync.js" }, "onUpdate" : { "type" : "text/javascript", "file" : "script/onCreate-onUpdate-sync.js" } If you have existing onCreate and onUpdate code blocks, you may need to consolidate options either in the applicable script file, or in a source entry. Modify the router.json file to include code blocks for the managed/user object and associated policy. These policies apply to the arbitrary ldapPassword parameter which you will also add to the managed.json file: { "pattern" : "managed/user.*", "onRequest" : { "type" : "text/javascript", "file" : "script/set-additional-passwords.js", "additionalPasswordFields" : [ "ldapPassword" ] }, "methods" : [ "create", "update" ] }, { "pattern" : "policy/managed/user.*", "onRequest" : { "type" : "text/javascript", "file" : "script/set-additional-passwords.js", "additionalPasswordFields" : [ "ldapPassword" ] }, "methods" : [ "action" ] } In the policy.json file, include the pwpolicy.js file from your project’s script/ subdirectory, as additionalFiles: "type" : "text/javascript", "file" : "policy.js", "additionalFiles": [ "script/pwpolicy.js" ] Now make the following changes to your project’s managed.json file. Find the "name" : "user", object code block, normally near the start of the file. Include the following code blocks for the onValidate, onCreate, and onUpdate scripts. The value for the storedFields and historyFields should match the additionalPasswordFields that you included in the router.json file. You may vary the value of historySize, depending on the number of recent passwords you want to record in the history for each user. A historySize of 2 means that users who change their passwords can’t use their previous two passwords. "name" : "user", "onValidate" : { "type" : "groovy", "file" : "script/storeFields.groovy", "storedFields" : [ "ldapPassword" ] }, "onCreate" : { "type" : "text/javascript", "file" : "script/onCreate-user-custom.js", "historyFields" : [ "ldapPassword" ], "historySize" : 2 }, "onUpdate" : { "type" : "text/javascript", "file" : "script/onUpdate-user-custom.js", "historyFields" : [ "ldapPassword" ], "historySize" : 2 } In same file under properties, add the following code block for ldapPassword "ldapPassword" : { "title" : "Password", "type" : "string", "viewable" : false, "searchable" : false, "minLength" : 8, "userEditable" : true, "secureHash" : { "algorithm" : "SHA-256" }, "policies" : [ { "policyId" : "at-least-X-capitals", "params" : { "numCaps" : 2 } }, { "policyId" : "at-least-X-numbers", "params" : { "numNums" : 1 } }, { "policyId" : "cannot-contain-others", "params" : { "disallowedFields" : [ "userName", "givenName", "sn" ] } }, { "policyId" : "re-auth-required", "params" : { "exceptRoles" : [ "system", "openidm-admin", "openidm-reg", "openidm-cert" ] } }, { "policyId" : "is-new", "params" : { "historyLength" : 2 } } ] } Add the following fieldHistory code block, which maps field names to a list of historical values for the field. "fieldHistory" : { "title" : "Field History", "type" : "object", "viewable" : false, "searchable" : false, "minLength" : 8, "userEditable" : true, "scope" : "private" }, After your next reconciliation, the password policies that you just set up in OpenIDM should apply. Storing Separate Passwords Per Linked Resource OpenIDM supports storing multiple passwords in a managed user entry, to enable synchronization of different passwords on different external resources. To store multiple passwords, you must extend the managed user schema to include additional properties for each target resource. You can set separate policies on each of these new properties, to ensure that the stored passwords adhere to the password policies of the specific external resources. The following addition to a sample managed.json configuration shows an ldapPassword property that has been added to managed user objects. This property will be mapped to the password property on an LDAP system: "ldapPassword" : { "title" : "Password", "type" : "string", "viewable" : false, "searchable" : false, "minLength" : 8, "userEditable" : true, "scope" : "private", "secureHash" : { "algorithm" : "SHA-256" }, "policies" : [ { "policyId" : "at-least-X-capitals", "params" : { "numCaps" : 2 } }, { "policyId" : "at-least-X-numbers", "params" : { "numNums" : 1 } }, { "policyId" : "cannot-contain-others", "params" : { "disallowedFields" : [ "userName", "givenName", "sn" ] } }, { "policyId" : "re-auth-required", "params" : { "exceptRoles" : [ "system", "openidm-admin", "openidm-reg", "openidm-cert" ] } }, { "policyId" : "is-new", "params" : { "historyLength" : 2 } } ] }, This property definition shows that the ldapPassword will be hashed, with an SHA-256 algorithm, and sets the policy that will be applied to values of this property. To use this custom managed object property and its policies to update passwords on an external resource, you must make the corresponding configuration and script changes in your deployment. For a detailed sample that implements multiple passwords, see "Storing Multiple Passwords For Managed Users" in the Samples Guide. That sample can also help you set up password history policies. Generating Random Passwords There are many situations when you might want to generate a random password for one or more user objects. OpenIDM provides a way to customize your user creation logic to include a randomly generated password that complies with the default password policy. This functionality is included in the default crypto script, bin/defaults/script/crypto.js, but is not invoked by default. For an example of how this functionality might be used, see the openidm/bin/defaults/script/ui/onCreateUser.js script. The following section of that file (commented out by default) means that users created by using the Admin UI, or directly over the REST interface, will have a randomly generated, password added to their entry: if (!object.password) { // generate random password that aligns with policy requirements object.password = require("crypto").generateRandomString([ { "rule": "UPPERCASE", "minimum": 1 }, { "rule": "LOWERCASE", "minimum": 1 }, { "rule": "INTEGERS", "minimum": 1 }, { "rule": "SPECIAL", "minimum": 1 } ], 16); } Comment out this section to invoke the random password generation when users are created. Note that changes made to scripts take effect after the time set in the recompile.minimumInterval, described in "Setting the Script Configuration". The generated password can be encrypted, or hashed, in accordance with the managed user schema, defined in conf/managed.json. For more information, see "Encoding Attribute Values". You can use this random string generation in a number of situations. Any script handler that is implemented in JavaScript can call the generateRandomString function. Synchronizing Passwords Between OpenIDM 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. OpenIDM can propagate passwords to the resources that store a user’s password. In addition, OpenIDM provides two plugins to intercept and synchronize passwords that are changed natively in OpenDJ and Active Directory. When you use the password synchronization plugins, set up password policy enforcement on OpenDJ or Active Directory rather than on OpenIDM. Alternatively, ensure that all password policies that are enforced are identical to prevent password updates on one resource from being rejected by OpenIDM or by another resource. The password synchronization plugins intercept 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. If the OpenIDM instance is unavailable when a password is changed in either OpenDJ 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 OpenIDM instance is available, at a predefined interval. When OpenIDM 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 OpenIDM repository. The following sections describe how to use the password synchronization plugin for OpenDJ, and the corresponding plugin for Active Directory. These plugins are available only with a subscription, from the ForgeRock BackStage site. Synchronizing Passwords With OpenDJ Password synchronization with OpenDJ requires communication over the secure LDAP protocol (LDAPS). If you have not set up OpenDJ for LDAPS, do this before you start, as described in the OpenDJ Administration Guide. OpenIDM must be installed, and running before you continue with the procedures in this section. Establishing Secure Communication Between OpenIDM and OpenDJ There are three possible modes of communication between OpenIDM and the OpenDJ password synchronization plugin: SSL Authentication. In this case, you must import the OpenIDM certificate into OpenDJ’s truststore (either the self-signed certificate that is generated the first time OpenIDM is started, or a CA-signed certificate). For more information, see "To Import OpenIDM’s Certificate into the OpenDJ Truststore". Mutual SSL Authentication. In this case, you must import the OpenIDM certificate into OpenDJ’s truststore, as described in "To Import OpenIDM’s Certificate into the OpenDJ Truststore", and import the OpenDJ certificate into OpenIDM’s truststore, as described in "To Import OpenDJ’s Certificate into the OpenIDM Truststore". You must also add the OpenDJ 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. OpenIDM supports basic authentication for testing purposes only. You should not use basic authentication in production. The steps to configure the plugin for basic authentication are described in the general configuration steps in "Installing the OpenDJ Password Synchronization Plugin". Version 1.0.3 of the OpenDJ password synchronization plugin supports mutual SSL authentication only. To Import OpenIDM’s Certificate into the OpenDJ Truststore You must export the certificate from OpenIDM’s keystore into OpenDJ’s truststore so that the OpenDJ agent can make SSL requests to the OpenIDM endpoints. OpenIDM 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. Export OpenIDM’s 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 OpenIDM keystore password is changeit. Import the self-signed certificate into OpenDJ’s truststore: $ cd /path/to/opendj/config $ keytool \ -importcert \ -alias openidm-localhost \ -keystore truststore \ -storepass `cat keystore.pin` \ -file /path/to/openidm/security/openidm-localhost.crt Owner: CN=localhost, O=OpenIDM Self-Signed Certificate, OU=None, L=None, ST=None, C=None Issuer: CN=localhost, O=OpenIDM Self-Signed Certificate, OU=None, L=None, ST=None, C=None Serial number: 15413e24ed3 Valid from: Tue Mar 15 10:27:59 SAST 2016 until: Tue Apr 14 10:27:59 SAST 2026 Certificate fingerprints: MD5: 78:81:DE:C0:5D:86:3E:DE:E0:67:C2:2E:9D:48:A0:0E SHA1: 29:14:FE:30:E7:D8:13:0F:A5:DD:DD:38:B5:D0:98:BA:E8:5B:96:59 SHA256: F8:F2:F6:56:EF:DC:93:C0:98:36:95:...7D:F4:0D:F8:DC:22:7F:D1:CF:F5:FA:75:62:7A:69 Signature algorithm name: SHA512withRSA Version: 3 Trust this certificate? [no]: yes Certificate was added to keystore To Import OpenDJ’s Certificate into the OpenIDM Truststore For mutual authentication, you must import OpenDJ’s certificate into the OpenIDM truststore. OpenDJ 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, you should use a certificate that has been signed by a Certificate Authority. Export OpenDJ’s generated 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 `cat keystore.pin` Certificate stored in file <server-cert.crt> Import the OpenDJ self-signed certificate into OpenIDM’s 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 Serial number: 41cefe38 Valid from: Thu Apr 14 10:17:39 SAST 2016 until: Wed Apr 09 10:17:39 SAST 2036 Certificate fingerprints: MD5: 0D:BC:44:B3:C4:98:90:45:97:4A:8D:92:84:2B:FC:60 SHA1: 35:10:B8:34:DE:38:59:AA:D6:DD:B3:44:C2:14:90:BA:BE:5C:E9:8C SHA256: 43:66:F7:81:3C:0D:30:26:E2:E2:09:...9F:5E:27:DC:F8:2D:42:79:DC:80:69:73:44:12:87 Signature algorithm name: SHA1withRSA Version: 3 Trust this certificate? [no]: yes Certificate was added to keystore 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 OpenDJ 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 } ... Installing the OpenDJ Password Synchronization Plugin The following steps install the password synchronization plugin on an OpenDJ directory server that is running on the same host as OpenIDM (localhost). If you are running OpenDJ on a different host, use the fully qualified domain name instead of localhost. Download the OpenDJ password synchronization plugin from the ForgeRock BackStage site. You must use the plugin version that corresponds to your OpenDJ version. Extract the contents of the opendj-accountchange-handler-version.zip file to the directory where OpenDJ is installed: $ unzip ~/Downloads/opendj-accountchange-handler-version.zip -d /path/to/opendj/ Archive: opendj-accountchange-handler-version.zip creating: opendj/ ... Restart OpenDJ to load the additional schema from the password synchronization plugin: $ cd /path/to/opendj/bin $ ./stop-ds --restart Stopping Server... ... [14/Apr/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) ... [14/Apr/2016:13:19:43 +0200] category=CORE severity=NOTICE msgID=org.opends.messages.core.139 ... The Directory Server has started successfully Configure the password synchronization plugin, if required. The password plugin configuration is specified in one of the following files: Plugin versions 1.0.3 and 1.1.1 - in openidm-pwsync-plugin-config.ldif Plugin version 3.5.0 - in openidm-accountchange-plugin-sample-config Depending on your plugin version, one of these configuration files 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-pwsync-plugin-config.ldif 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 ... + You can configure the following elements of the plugin. Depending on your plugin version, the property names might differ. Applicable version numbers are provided in the following list: + ds-cfg-enabled Specifies whether the plugin is enabled. Default value: true ds-cfg-attribute The attribute in OpenIDM that stores user passwords. This property is used to construct the patch request on the OpenIDM managed user object. Default value: password ds-cfg-query-id (3.5) ds-task-id (1.x) 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 OpenIDM. Default values: entryUUID and uid ds-cfg-log-file The log file location where the changed passwords are written when the plugin cannot contact OpenIDM. The default location is the logs directory of the server instance, in the file named pwsync. Passwords in this file 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 OpenIDM. If this value is 0, updates are made synchronously in the foreground, and no encrypted passwords are stored in the ds-cfg-log-file. Default value: 0 seconds ds-cfg-openidm-url (3.5) ds-cfg-referrals-url (1.x) The endpoint at which the plugin should find OpenIDM 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 OpenDJ keystore. If LDAPS is configured during the GUI setup of OpenDJ, the default client key alias is server-cert. Default value: server-cert ds-cfg-private-key-alias (3.5) ds-cfg-realm (1.x) The alias of the private key that should be used by OpenIDM to decrypt the session key. Default value: openidm-localhost ds-cfg-certificate-subject-dn (3.5) ds-certificate-subject-dn (1.x) The certificate subject DN of the OpenIDM private key. The default configuration assumes that you are using the self-signed certificate that is generated when OpenIDM 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 OpenDJ key manager provider. The key manager provider specified here must be enabled. Default value: cn=JKS,cn=Key Manager Providers,cn=config ds-cfg-trust-manager-provider The OpenDJ trust manager provider. The trust manager provider specified here must be enabled. Default value: cn=JKS,cn=Trust Manager Providers,cn=config ds-cfg-openidm-username (3.5) ds-openidm-httpuser (1.1.1) An OpenIDM administrative username that the plugin will use to make REST calls to OpenIDM. 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 in version of 3.5.0 of the plugin configuration, and must be uncommented if you use HTTP or SSL authentication. This property does not exist in version 1.0.3 of the plugin, as the plugin supports mutual SSL authentication only. ds-cfg-openidm-password (3.5) ds-openidm-httppasswd (1.1.1) The password of the OpenIDM administrative user specified by the previous property. Default value: openidm-admin This property is commented out in version of 3.5.0 of the plugin configuration, and must be uncommented if you use HTTP or SSL authentication. This property does not exist in version 1.0.3 of the plugin, as the plugin supports mutual SSL authentication only. When you have updated the plugin configuration to fit your deployment, add the configuration to OpenDJ’s configuration: For plugin version 3.5.0: $ cd /path/to/opendj/bin $ ./ldapmodify \ --port 1389 \ --hostname `hostname` \ --bindDN "cn=Directory Manager" \ --bindPassword "password" \ --defaultAdd \ --filename ../config/openidm-accountchange-plugin-sample-config For plugin version 1.x: $ cd /path/to/opendj/bin $ ./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 for the new configuration to take effect: $ ./stop-ds --restart Stopping Server... ... [14/Apr/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/openidm-account-change-handler.jar' (build 1.1.1, revision 1) ... [14/Apr/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 Adjust your OpenDJ 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" \ --trustStorePath ../config/admin-truststore \ --no-prompt Apr 14, 2016 1:28:32 PM org.forgerock.i18n.slf4j.LocalizedLogger info INFO: Loaded extension from file '/path/to/opendj/lib/extensions/openidm-account-change-handler.jar' (build 1.1.1, revision 1) Password synchronization should now be configured and working. To test that the setup has been successful, change a user password in OpenDJ. That password should be synchronized to the corresponding OpenIDM managed user account, and you should be able to query the user’s own entry in OpenIDM using the new password. Synchronizing Passwords With Active Directory Use the Active Directory password synchronization plugin to synchronize passwords between OpenIDM 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 OpenIDM 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. Configuring OpenIDM for Password Synchronization With Active Directory To support password synchronization with Active Directory, you must make the following configuration changes to your managed user schema (in your project’s conf/managed.json file): Add a new property, named userPassword to the user object schema. This new property corresponds with the userPassword attribute in an Active Directory user entry. The following excerpt shows the required addition to the managed.json file: { "objects" : [ { "name" : "user", ... "schema" : { ... "properties" : { "password" : { ... "encryption" : { "key" : "openidm-sym-default" }, "scope" : "private" }, "userPassword" : { "description" : "", "title" : "", "viewable" : true, "searchable" : false, "userEditable" : false, "policies" : [ ], "returnByDefault" : false, "minLength" : "", "pattern" : "", "type" : "string", "encryption" : { "key" : "openidm-sym-default" }, "scope" : "private" }, ... }, "order" : [ "_id", "userName", "password", ... "userPassword" ] } }, ... ] } Add an onUpdate script to the managed user object that checks whether the values of the two password properties (password and userPassword) match, and sets them to the same value if they do not. The excerpt shows the required addition to the managed.json file: { "objects" : [ { "name" : "user", ... "onUpdate" : { "type" : "text/javascript", "source" : "if (newObject.userPassword !== oldObject.userPassword) { newObject.password = newObject.userPassword; }" }, ... ] } Installing the Active Directory Password Synchronization Plugin The following steps install the password synchronization on an Active directory server: Download the Active Directory password synchronization plugin from the ForgeRock BackStage site. 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. If you want to save the settings in a configuration file, you can use the /saveinf switch as follows. C:\Path\To > 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: C:\Path\To > idm-setup.exe /verysilent /loadinf=C:\temp\adsync.inf 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 OpenIDM 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 managed/user object on OpenIDM, 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 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 name of an administrative user that can authenticate to OpenIDM, for example, openidm-admin. Password. Enter the password of the user that authenticates to OpenIDM, for example, openidm-admin. Select authentication type. Select the type of authentication that Active Directory will use to authenticate to OpenIDM. 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 OpenIDM. 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 OpenIDM’s trust store. To generate a self-signed certificate for Active Directory, follow these steps: 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> 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 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 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 OpenIDM. To do so, import the PKCS12 file into the OpenIDM keystore file, named truststore, in the /path/to/openidm/security directory. On the machine that is running OpenIDM, 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. Archive file with certificate. Browse to select the archive file that will be used for password encryption. That file is normally set up 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 OpenIDM’s keystore, so that OpenIDM can locate the key with which to decrypt the data. To import the certificate into OpenIDM’s keystore, keystore.jceks, run the following command on the OpenIDM 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. 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). Data storage Provide the details for the storage of encrypted passwords in the event that OpenIDM 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 OpenIDM is available, for example, 60, to poll OpenIDM 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. After running the installation wizard, restart the computer. 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. The Password Sync Service uses Windows certificate stores to verify OpenIDM’s identity. The certificate that OpenIDM uses must therefore be added to the list of trusted certificates on the Windows machine. For production purposes, you should 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 OpenIDM on first startup. To add the OpenIDM certificate to the list of trusted certificates, use the Microsoft Management Console. Select Start and type mmc in the Search field. In the Console window, select File > Add/Remove Snap-in. From the left hand column, select Certificates and click Add. Select My user account, and click Finish. 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. Click Finish when you have added the three certificate snap-ins. Still in the Microsoft Management Console, expand Certificates - Current User > Personal and select Certificates. Select Action > All Tasks > Import to open the Certificate Import Wizard. Browse for the OpenIDM certificate (openidm-localhost.crt by default, if you use OpenIDM’s self-signed certificate). Enter the Password for the certificate (changeit by default, if you use OpenIDM’s self-signed certificate). Accept the default for the Certificate Store. Click Finish to complete the import. 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 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 OpenIDM headers, set authType to idm. For SSL mutual authentication using a certificate, set authType to cert. By default, the plugin does not validate the OpenIDM 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. 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: Optionally, generate a new encryption key by running the following command: idmsync.exe --key Encrypt the values of the sensitive registry keys as follows: idmsync.exe --encrypt "key-value" "authToken1Value" idmsync.exe --encrypt "key-value" "certPasswordValue" 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 OpenIDM 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 OpenIDM is unavailable When OpenIDM 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 OpenIDM 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 OpenIDM 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. Scheduling Tasks and Events Managing Authentication, Authorization and Role-Based Access Control