Synchronize Passwords With ForgeRock Directory Services (DS)

1. Download the password synchronization plugin.

2. Extract the .zip file contents to the DS installation directory:

   unzip ~/Downloads/DS-IDM-account-change-notification-handler-7.1.zip -d /path/to/opendj/

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

   /path/to/opendj/bin/stop-ds --restart
   Stopping Server...
   ...msg=Loaded extension from file '/path/to/opendj/lib/extensions/opendj-openidm-account-change-notification-handler-7.1.jar'
   ...
   ...msg=The Directory Server has started successfully

4. Configure the password synchronization plugin:

   /path/to/opendj/bin/dsconfig \
   create-account-status-notification-handler \
   --type openidm \
   --handler-name "OpenIDM Notification Handler" \
   --set enabled:true \
   --set openidm-url:https://openidm-localhost:8444/openidm/managed/user \
   --set private-key-alias:openidm-localhost \
   --set certificate-subject-dn:"CN=openidm-localhost, O=OpenIDM Self-Signed Certificate, OU=None, L=None, ST=None, C=None" \
   --set ssl-cert-nickname:ssl-key-pair \
   --set key-manager-provider:PKCS12 \
   --set trust-manager-provider:PKCS12 \
   --set password-attribute:password \
   --set attribute-type:entryUUID \
   --set attribute-type:uid \
   --set query-id:for-userName \
   --set log-file:logs/pwsync \
   --set update-interval:5s \
   --set request-retry-attempts:5000 \
   --hostname localhost \
   --port 4444 \
   --bindDn uid=admin \
   --bindPassword password \
   --usePkcs12TrustStore /path/to/opendj/config/keystore \
   --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
   --no-prompt
   The Openidm Account Status Notification Handler was created successfully

   Adapt the settings to match your DS and IDM deployments:

   Setting	Details
   enabled	Enables the plugin. Leave this setting as shown.
   openidm-url	The endpoint where the plugin finds IDM managed user accounts. Port 8444 is the IDM default for mutual TLS connections.
   private-key-alias	The IDM private key, used to decrypt the JSON objects from DS that contain passwords. The example references the default IDM private key of the self-signed key pair generated at setup time.
   certificate-subject-dn	The certificate subject DN for the IDM public key. The DS plugin encrypts JSON objects with the IDM public key, so this must match the certificate for the IDM private key specified for the private-key-alias property. The example shows the subject DN of the default IDM self-signed certificate.
   ssl-cert-nickname	The alias of the DS TLS certificate used to authenticate to IDM. The example uses the default DS server certificate generated at setup time.
   key-manager-provider	The provider for the keystore where DS finds its TLS key pair specified in ssl-cert-nickname. The example uses the default DS provider configured at setup time.
   trust-manager-provider	The provider for the keystore where DS finds the IDM public key specified in certificate-subject-dn. The example uses the default DS provider configured at setup time, and updated in "Enable DS to Trust the IDM Certificate".
   password-attribute	The name of the password field in the JSON that DS sends to IDM for a password change. This attribute type must be defined in the managed object schema in IDM, and it must have either the user password or auth password syntax.
   attribute-type	LDAP attributes that the DS plugin sends to IDM with the password. IDM can use these to uniquely identify the user, even if the user's account has moved. If no attribute types are specified, DS sends only the DN and the new password to IDM.
   query-id	The query-id for the patch-by-query request. Leave this setting as shown.
   log-file	The DS directory where the plugin writes log files containing encrypted passwords before notifying IDM. This setting has no effect in the example, where the update-interval is zero seconds.
   update-interval	The interval at which the DS plugin sends password changes to IDM. If this value is zero, the plugin sends updates synchronously. No encrypted passwords are stored in the configured log-file directory. The plugin does not retry failed requests, irrespective of the request-retry-attempts setting.
   request-retry-attempts	The number of times the plugin attempts a synchronization request if the first attempt fails. If this value is zero, the request is not retried. If the value is greater than zero, the plugin retries the specified number of times before giving up and removing the request from its queue. When a request fails due to a transient condition, such as failure to contact IDM, or a connection timeout, the plugin does not decrement the number of retry attempts. The plugin logs a message with the reason the request failed, and continues to retry until IDM responds.

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

   /path/to/opendj/bin/stop-ds --restart

6. Update DS password policies to use the password synchronization plugin.

   The following example updates the default DS password policy:

   /path/to/opendj/bin/dsconfig \
   set-password-policy-prop \
   --policy-name "Default Password Policy" \
   --set account-status-notification-handler:"OpenIDM Notification Handler" \
   --hostname localhost \
   --port 4444 \
   --bindDN uid=admin \
   --bindPassword password \
   --usePkcs12TrustStore /path/to/opendj/config/keystore \
   --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
   --no-prompt

   For details on configuring DS password policies, see Passwords in the DS Security Guide.

The password synchronization plugin uses client certificate authentication to authenticate to IDM. You must also update your security configuration to add the IDM key alias.

1. If your authentication configuration does not already include client certificate authentication, configure it as follows:

   1. Add the CLIENT_CERT authentication module to your authentication configuration.

   2. Set the allowedAuthenticationIdPatterns property to the certificate DN of the DS SSL certificate (ssl-key-pair by default).

   3. Add internal/role/openidm-cert to the array of defaultUserRoles.

   The following example assumes that you are using the default DS ssl-key-pair certificate that has a certificate subject DN of CN=DS, O=ForgeRock:

   "authModules" : [
       ...
       {
           "name" : "CLIENT_CERT",
           "properties" : {
               "queryOnResource" : "managed/user",
               "defaultUserRoles" : [
                   "internal/role/openidm-cert",
                   "internal/role/openidm-authorized"
               ],
               "allowedAuthenticationIdPatterns" : [
                   ".*CN=DS, O=ForgeRock.com.*"
               ]
           },
           "enabled" : true
       },
       ...
   ]

   For more information about client certificate authentication, see "CLIENT_CERT".

2. Update the IDM secret store (conf/secrets.json) to add the alias used in the private-key-alias plugin setting to the idm.default secretId:

   "mappings": [
       {
           "secretId" : "idm.default",
           "types": [ "ENCRYPT", "DECRYPT" ],
           "aliases": [ "&{openidm.config.crypto.alias|openidm-sym-default}", "openidm-localhost" ]
       },
       ...
   ]

   For more information about secret stores, see "Configuring Secret Stores".

1. Download the password synchronization plugin.

2. Extract the .zip file contents to the DS identity store installation directory:

   unzip ~/Downloads/DS-IDM-account-change-notification-handler-7.1.zip -d /path/to/opendj-identity/

3. Configure the password synchronization plugin to use AM bearer token authentication:

   /path/to/opendj-identity/bin/dsconfig \
   create-account-status-notification-handler \
   --type openidm \
   --handler-name "OpenIDM Notification Handler" \
   --set certificate-subject-dn:"CN=openidm-localhost,O=OpenIDM Self-Signed Certificate,OU=None,L=None,ST=None,C=None" \
   --set enabled:true \
   --set attribute-type:entryUUID \
   --set attribute-type:uid \
   --set trust-manager-provider:PKCS12 \
   --set key-manager-provider:PKCS12 \
   --hostname identities.example.com \
   --port 4445 \
   --bindDn uid=admin \
   --trustAll \
   --bindPassword str0ngAdm1nPa55word \
   --set log-file:logs/pwsync \
   --set password-attribute:password \
   --set query-id:for-userName \
   --set private-key-alias:openidm-localhost \
   --set openidm-url:https://openidm-localhost:8445/openidm/managed/user \
   --set oauth2-access-token-url:http://am.example.com:8080/openam/oauth2/realms/root/access_token \
   --set oauth2-scope:"openid fr:idm:*" \
   --set oauth2-client-id:ds-password-sync-plugin \
   --set oauth2-client-secret:ds-password-sync-plugin \
   --set request-retry-attempts:5000 \
   --set update-interval:5s \
   --no-prompt
   The Openidm Account Status Notification Handler was created successfully

   Note

   Adapt the above settings to match your DS, IDM, and AM deployments.

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

   /path/to/opendj-identity/bin/stop-ds --restart

5. Configure the DS password policy to use the password synchronization plugin. The following example updates the default DS password policy:

   /path/to/opendj-identity/bin/dsconfig \
   set-password-policy-prop \
   --policy-name "Default Password Policy" \
   --set account-status-notification-handler:"OpenIDM Notification Handler" \
   --hostname identities.example.com \
   --port 4445 \
   --bindDN uid=admin \
   --bindPassword str0ngAdm1nPa55word \
   --usePkcs12TrustStore /path/to/opendj-identity/config/keystore \
   --trustStorePasswordFile /path/to/opendj-identity/config/keystore.pin \
   --no-prompt

   For details on configuring DS password policies, see Passwords in the DS Security Guide.

6. Generate an AM bearer token. For example:

   curl -k \
   --request POST \
   --user "ds-password-sync-plugin:ds-password-sync-plugin" \
   --data "grant_type=client_credentials" \
   --data "scope=openid fr:idm:*" \
   "http://am.example.com:8080/openam/oauth2/realms/root/access_token"
   {
     "access_token": "access_token",
     "scope": "openid fr:idm:*",
     "id_token": "id_token",
     "token_type": "Bearer",
     "expires_in": 3599
   }

7. Optionally, to test the AM bearer token, create a new managed user using the token as the authorization. For example:

   curl -v \
   --header "Authorization: Bearer access_token" \
   --header "accept: application/json" \
   --header "Accept-API-Version: resource=1.0" \
   --header "Content-Type: application/json" \
   --request POST "http://openidm-localhost:8081/openidm/managed/user?_action=create" \
   --data '{"userName":"jdoe", "password": "6fNcHgBF", "mail": "jdoe@example.com", "sn": "Doe", "givenName": "Jane"}'
   {
     "_id": "7884b8ab-a226-4ee5-b9b9-0718f5a19335",
     "_rev": "00000000f527116e",
     "userName": "jdoe",
     "accountStatus": "active",
     "givenName": "Jane",
     "sn": "Doe",
     "mail": "jdoe@example.com"
   }