1. To add the user copy the following XML into openidm/samples/sample1/data/xmlConnectorData.xml:

   <ri:__ACCOUNT__>
       <icf:__UID__>tmorris</icf:__UID__>
       <icf:__NAME__>tmorris@example.com</icf:__NAME__>
       <ri:firstname>Toni</ri:firstname>
       <ri:lastname>Morris</ri:lastname>
       <ri:email>tmorris@example.com</ri:email>
       <ri:mobileTelephoneNumber>1234567</ri:mobileTelephoneNumber>
       <ri:roles>openidm-authorized</ri:roles>
       <icf:__DESCRIPTION__>Created By XML1</icf:__DESCRIPTION__>
    </ri:__ACCOUNT__>

2. Run reconciliation again, as described in "Running Reconciliation".

3. After reconciliation has run, query the local repository to see the new user appear in the list of all managed users:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"
   {
     "result": [
       {
         "_id": "scarter",
         "_rev": "2"
       },
       {
         "_id": "bjensen",
         "_rev": "2"
       },
       {
         "_id": "tmorris",
         "_rev": "1"
       }
     ],
   ...
   }

1. Download OpenDJ from ForgeRock's download site and extract the zip archive.

   The LDIF data for this sample is provided in the file openidm/samples/sample2/data/Example.ldif. You will need to import this data during your OpenDJ setup.

2. Install OpenDJ using the command-line setup.

   Substitute the --ldifFile argument with the path to the Example.ldif file in your OpenIDM installation:

   $ cd /path/to/opendj
   $ ./setup --cli \
   --hostname localhost \
   --ldapPort 1389 \
   --rootUserDN "cn=Directory Manager" \
   --rootUserPassword password \
   --adminConnectorPort 4444 \
   --baseDN dc=com \
   --ldifFile /path/to/openidm/samples/sample2/data/Example.ldif \
   --acceptLicense \
   --no-prompt
   ...
   Configuring Directory Server ..... Done.
   Importing LDIF file /path/to/openidm/samples/sample2/data/Example.ldif ...... Done.
   Starting Directory Server ...... Done..
   ...

1. Reconcile the repository by running the following command:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "https://localhost:8443/openidm/recon?_action=recon&mapping=systemLdapAccounts_managedUser&waitForCompletion=true"
   {
     "_id": "b1394d10-29b0-4ccf-81d8-c88948ea121c-4",
     "state": "SUCCESS"
   }
        

   The reconciliation operation creates the two users from the LDAP server in the OpenIDM repository, assigning the new objects random unique IDs.

2. To retrieve the users from the repository, query their IDs as follows:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"
   {
     "result": [
       {
         "_id": "f52df646-7108-45e1-9342-1a17f257b497",
         "_rev": "1"
       },
       {
         "_id": "f7fccf54-e76a-404c-93f0-7486d30f1dc3",
         "_rev": "1"
       }
     ],
   ...
   }

3. To retrieve individual user objects, include the ID in the URL, for example:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/user/0a5546d6-149b-4f8b-b3be-4afa8a267d45"
   {
     "_id": "f7fccf54-e76a-404c-93f0-7486d30f1dc3",
     "_rev": "1",
     "displayName": "Barbara Jensen",
     "description": "Created for OpenIDM",
     "givenName": "Barbara",
     "mail": "bjensen@example.com",
     "sn": "Jensen",
     "telephoneNumber": "1-360-229-7105",
     "userName": "bjensen",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }

1. Log in to the Admin UI at the URL https://localhost:8443/admin as the default administrative user (openidm-admin) with password openidm-admin.

   Warning

   To protect your deployment in production, change the default administrative password. To do so, navigate to the Self-Service UI at https://localhost:8443/ and click Change Password.

2. Click Configure > Mappings.

   This page shows one configured mapping, from the ldap server to the OpenIDM repository (managed/user).

   

3. Click anywhere on the mapping and click Reconcile Now.

   The reconciliation operation creates the two users from the LDAP server in the OpenIDM repository.

4. Retrieve the users in the repository. Click Manage > User.

   You should now see two users from the LDAP server, reconciled to the OpenIDM repository.

5. When you click a username, you can view the details of that user account.

1. Reconcile the repository over the REST interface by running the following command:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "https://localhost:8443/openidm/recon?_action=recon&mapping=systemLdapAccounts_managedUser&waitForCompletion=true"
   {
     "state": "SUCCESS",
     "_id": "027e25e3-7a33-4858-9080-161c2b40a6bf-2"
   }

   The reconciliation operation returns a reconciliation run ID and the status of the operation. Reconciliation creates user objects from LDAP in the OpenIDM repository, assigning the new objects random unique IDs.

2. To retrieve the users from the repository, query their IDs as follows:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"
   {
     "result": [
       {
         "_id": "d460ed00-74f9-48fb-8cc1-7829be60ddac",
         "_rev": "1"
       },
       {
         "_id": "74fe2d25-4eb1-4148-a3ae-ff80f194b3a6",
         "_rev": "1"
       }
     ],
   ...
   }

3. To retrieve individual user objects, include the ID in the URL, for example:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/user/d460ed00-74f9-48fb-8cc1-7829be60ddac"
   {
     "_id": "d460ed00-74f9-48fb-8cc1-7829be60ddac",
     "_rev": "1",
     "displayName": "Barbara Jensen",
     "description": "Created for OpenIDM",
     "givenName": "Barbara",
     "mail": "bjensen@example.com",
     "telephoneNumber": "1-360-229-7105",
     "sn": "Jensen",
     "userName": "bjensen",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }

4. Test the second mapping by creating a user in the OpenIDM repository.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
       "mail":"fdoe@example.com",
       "sn":"Doe",
       "telephoneNumber":"555-1234",
       "userName":"fdoe",
       "givenName":"Felicitas",
       "description":"Felicitas Doe",
       "displayName":"fdoe"}' \
    "https://localhost:8443/openidm/managed/user?_action=create"
   {
     "_id": "90d1f388-d8c3-4438-893c-be4e498e7a1c",
     "_rev": "1",
     "mail": "fdoe@example.com",
     "sn": "Doe",
     "telephoneNumber": "555-1234",
     "userName": "fdoe",
     "givenName": "Felicitas",
     "description": "Felicitas Doe",
     "displayName": "fdoe",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }

5. By default, implicit synchronization is enabled for mappings from the managed/user repository to any external resource. This means that when you update a managed object, any mappings defined in the sync.json file that have the managed object as the source are automatically executed to update the target system. For more information, see "Configuring the Synchronization Mapping" in the Integrator's Guide.

   Test that the implicit synchronization has been successful by querying the users in the LDAP directory over REST, as follows:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/system/ldap/account?_queryId=query-all-ids"
   {
     "result": [
       {
         "_id": "uid=jdoe,ou=People,dc=example,dc=com",
         "dn": "uid=jdoe,ou=People,dc=example,dc=com"
       },
       {
         "_id": "uid=bjensen,ou=People,dc=example,dc=com",
         "dn": "uid=bjensen,ou=People,dc=example,dc=com"
       },
       {
         "_id": "uid=fdoe,ou=People,dc=example,dc=com",
         "dn": "uid=fdoe,ou=People,dc=example,dc=com"
       }
     ],
   ...
   }

   Note the new entry for user fdoe.

6. Query the complete entry by including fdoe's ID in the URL.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/system/ldap/account/uid=fdoe,ou=People,dc=example,dc=com"
   {
     "_id": "uid=fdoe,ou=People,dc=example,dc=com",
     "mail": "fdoe@example.com",
     "employeeType": null,
     "ldapGroups": [],
     "telephoneNumber": "555-1234",
     "givenName": "Felicitas",
     "cn": "fdoe",
     "dn": "uid=fdoe,ou=People,dc=example,dc=com",
     "uid": "fdoe",
     "sn": "Doe",
     "description": "Felicitas Doe"
   }

1. Log in to the Admin UI at the URL https://localhost:8443/admin as the default administrative user (openidm-admin) with password openidm-admin.

   Warning

   To protect your deployment in production, change the default administrative password. To do so, navigate to the Self-Service UI at https://localhost:8443/ and click Change Password.

2. Click Configure > Mappings.

   This tab shows two configured mappings, one from the ldap server to the OpenIDM repository (managed/user) and one from the OpenIDM repository to the ldap server.

3. Click anywhere on the first mapping and click Reconcile Now.

   The reconciliation operation creates the two users from the LDAP server in the OpenIDM repository.

4. Retrieve the users in the repository. Click Manage > User.

5. You should see two users from the LDAP server, reconciled to the OpenIDM repository.

6. To retrieve the details of a specific user, click that username in the User List page.

7. Add a new user in the OpenIDM repository by clicking New User in the User List page.

   Complete the user details and click Save.

8. By default, implicit synchronization is enabled for mappings from the managed/user repository to any external resource. This means that when you update a managed object, any mappings defined in the sync.json file that have the managed object as the source are automatically executed to update the target system. For more information, see "Configuring the Synchronization Mapping" in the Integrator's Guide.

   To test that the implicit synchronization has been successful, look at fdoe's record, and click the Linked Systems tab. The information under this tab includes the external resource to which this user entry is mapped.

1. Reconcile the repository over the REST interface by running the following command:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "https://localhost:8443/openidm/recon?_action=recon&mapping=systemLdapAccounts_managedUser&waitForCompletion=true"
   {
     "_id": "6652c292-5309-40e5-b272-b74d67dd95c9-4",
     "state": "SUCCESS"
   }

   The reconciliation operation returns a reconciliation run ID and the status of the operation. Reconciliation creates user objects from LDAP in the OpenIDM repository, assigning the new objects random unique IDs.

2. To retrieve the users from the repository, query their IDs as follows:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"
   {
     "result": [
       {
         "_id": "b63fb9a7-99bc-4eb4-8bfd-15f14a756e5b",
         "_rev": "1"
       },
       {
         "_id": "8462fe0c-2ab2-459a-a25e-474474889c9e",
         "_rev": "1"
       }
     ],
   ...
   }

3. To retrieve individual user objects, include the ID in the URL. The following request retrieves the user object for John Doe:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/user/8462fe0c-2ab2-459a-a25e-474474889c9e"
   {
     "_id": "8462fe0c-2ab2-459a-a25e-474474889c9e",
     "_rev": "1",
     "displayName": "John Doe",
     "description": "Created for OpenIDM",
     "givenName": "John",
     "mail": "jdoe@example.com",
     "telephoneNumber": "1-415-599-1100",
     "sn": "Doe",
     "userName": "jdoe",
     "ldapGroups": [
       "cn=openidm,ou=Groups,dc=example,dc=com"
     ],
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }

   Note that John Doe's user object contains an ldapGroups property, the value of which indicates his groups on the LDAP server:

   "ldapGroups":["cn=openidm,ou=Groups,dc=example,dc=com"]

4. Update John Doe's ldapGroups property, to change his membership from the openidm group to the openidm2 group.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '[
       {
         "operation":"replace",
         "field":"/ldapGroups",
         "value": ["cn=openidm2,ou=Groups,dc=example,dc=com"]
       }
    ]' \
    "https://localhost:8443/openidm/managed/user?_action=patch&_queryId=for-userName&uid=jdoe"
   {
     "displayName": "John Doe",
     "description": "Created for OpenIDM",
     "givenName": "John",
     "mail": "jdoe@example.com",
     "telephoneNumber": "1-415-599-1100",
     "sn": "Doe",
     "userName": "jdoe",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": [],
     "_id": "8462fe0c-2ab2-459a-a25e-474474889c9e",
     "_rev": "2",
     "ldapGroups": [
       "cn=openidm2,ou=Groups,dc=example,dc=com"
     ]
   }   

   This command changes John Doe's ldapGroups property in the OpenIDM repository, from "cn=openidm,ou=Groups,dc=example,dc=com" to "cn=openidm2,ou=Groups,dc=example,dc=com". As a result of implicit synchronization, the change is propagated to the LDAP server. John Doe is removed from the first LDAP group and added to the second LDAP group in OpenDJ.

5. You can verify this change by querying John Doe's record on the LDAP server, as follows:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/system/ldap/account/uid=jdoe,ou=People,dc=example,dc=com"
   {
     "_id": "uid=jdoe,ou=People,dc=example,dc=com",
     "telephoneNumber": "1-415-599-1100",
     "description": "Created for OpenIDM",
     "sn": "Doe",
     "dn": "uid=jdoe,ou=People,dc=example,dc=com",
     "ldapGroups": [
       "cn=openidm2,ou=Groups,dc=example,dc=com"
     ],
     "uid": "jdoe",
     "cn": "John Doe",
     "givenName": "John",
     "mail": "jdoe@example.com"
   }
        

1. Log in to the Admin UI at the URL https://localhost:8443/admin as the default administrative user (openidm-admin) with password openidm-admin.

   Warning

   To protect your deployment in production, change the default administrative password. To do so, navigate to the Self-Service UI at https://localhost:8443/ and click Change Password.

2. Click Configure > Mappings.

   This window shows two configured mappings, one from the ldap server to the OpenIDM repository (managed/user) and one from the OpenIDM repository to the ldap server.

3. Click anywhere on the first mapping and click Reconcile Now.

   The reconciliation operation creates the two users from the LDAP server in the OpenIDM repository.

4. Click Manage > User. Examine the users reconciled from the LDAP server to the internal repository.

5. Examine the two users from the LDAP server that have been reconciled to the OpenIDM repository.

6. To retrieve the details of a specific user, click that username. In this case, click on user jdoe.

   Examine the information stored for user jdoe. Click the Linked Systems tab. The Linked Resource item indicates the external resource on which John Doe's managed object is mapped, in this case, ldap account.

   In this linked resource, John Doe's ldapGroups are displayed. Currently, John Doe is a member of cn=openidm,ou=Groups,dc=example,dc=com.

7. Update John Doe's ldapGroups property to change his membership from the openidm group to the openidm2 group. Currently, you can only do this over the REST interface, as follows:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '[
       {
         "operation":"replace",
         "field":"/ldapGroups",
         "value": ["cn=openidm2,ou=Groups,dc=example,dc=com"]
       }
    ]' \
    "https://localhost:8443/openidm/managed/user?_action=patch&_queryId=for-userName&uid=jdoe"
   {
     "displayName": "John Doe",
     "description": "Created for OpenIDM",
     "givenName": "John",
     "mail": "jdoe@example.com",
     "telephoneNumber": "1-415-599-1100",
     "sn": "Doe",
     "userName": "jdoe",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": [],
     "_id": "8462fe0c-2ab2-459a-a25e-474474889c9e",
     "_rev": "2",
     "ldapGroups": [
       "cn=openidm2,ou=Groups,dc=example,dc=com"
     ]
   }   

   This command changes John Doe's ldapGroups property in the OpenIDM repository, from "cn=openidm,ou=Groups,dc=example,dc=com" to "cn=openidm2,ou=Groups,dc=example,dc=com". As a result of implicit synchronization, the change is propagated to the LDAP server. John Doe is removed from the first LDAP group and added to the second LDAP group in OpenDJ.

8. You can verify this change by reloading John Doe's user information, clicking Linked Systems, and examining the value of his ldapGroups property.

1. Reconcile the repository over the REST interface for the group mapping, systemLdapGroups_managedGroup by running the following command:

   $  curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "https://localhost:8443/openidm/recon?_action=recon&mapping=systemLdapGroups_managedGroup&waitForCompletion=true"

   The reconciliation operation returns a reconciliation run ID, and the status of the operation.

2. With the configuration of sample 2d, OpenIDM creates group objects from LDAP in OpenIDM. To list group objects by ID, run a query over the REST interface.

   $  curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/group?_queryFilter=true"

   The resulting JSON object should include content similar to the following.

    {
      "result" : [ {
         "dn" : "cn=openidm,ou=Groups,dc=example,dc=com",
         "_id" : "837df489-35d6-48d1-81a5-23792b49838a",
         "_rev" : "1",
         "description" : [ ],
         "uniqueMember" : [ "uid=jdoe,ou=People,dc=example,dc=com" ],
         "name" : [ "openidm" ]
      }, {
         "dn" : "cn=openidm2,ou=Groups,dc=example,dc=com",
         "_id" : "7575c1c7-86cf-43bc-bf1d-5c9cfc539124",
         "_rev" : "1",
         "description" : [ ],
         "uniqueMember" : [ "uid=bjensen,ou=People,dc=example,dc=com" ],
         "name" : [ "openidm2" ]
      } ],
   ...
    }

1. Log in to the Admin UI at the URL https://localhost:8443/admin as the default administrative user (openidm-admin) with password openidm-admin.

   Warning

   To protect your deployment in production, change the default administrative password. To do so, navigate to the Self-Service UI at https://localhost:8443/ and click Change Password.

2. Click Configure > Mappings.

   This page shows three configured mappings, from the ldap server accounts repository to the OpenIDM repository (managed/user), from the OpenIDM repository back to the ldap server, and from the ldap server group accounts repository to the OpenIDM managed/group repository.

3. Click anywhere on the third mapping and click Reconcile Now.

   The reconciliation operation creates the two groups from the LDAP server in the OpenIDM repository.

4. Retrieve the groups in the repository by clicking the Association tab below the mapping. Scroll down to Data Association Management.

   

   The three groups from the LDAP server (source) have been reconciled to the OpenIDM repository (target).

To configure OpenIDM to send a reconciliation summary by email, follow these steps:

1. Copy the template external.email.json file from the samples/misc directory to the conf directory of Sample 5:

   $ cd /path/to/openidm
   $ cp samples/misc/external.email.json samples/sample5/conf
        

2. Edit the external.email.json file for outbound email, as described in "Sending Email" in the Integrator's Guide.

3. Edit the reconStats.js file from the sample5/script directory. Near the start of the file, configure the OpenIDM email service to send statistics to the email addresses of your choice:

   var email = {
         //UPDATE THESE VALUES
         from : "openidm@example.com",
         to : "youremail@example.com",
         cc : "idmadmin2@example.com,idmadmin3@example.com",
         subject : "Recon stats for " + global.mappingName,
         type : "text/html"
   },
   template,
   ...  

1. Download OpenDJ from ForgeRock's download site and extract the zip archive.

2. Install OpenDJ, using either the UI or the command-line setup.

   • If you use the UI, make sure that you enable replication, and import the Example.ldif file during the install.

   • If you use the command-line setup, import the Example.ldif file during the setup, then enable replication when the server has started:

     $ cd /path/to/opendj
     $ ./setup --cli \
     --hostname localhost \
     --ldapPort 1389 \
     --rootUserDN "cn=Directory Manager" \
     --rootUserPassword password \
     --adminConnectorPort 4444 \
     --baseDN dc=com \
     --ldifFile /path/to/openidm/samples/historicalaccountlinking/data/Example.ldif \
     --acceptLicense \
     --no-prompt
     ...
     Configuring Directory Server ..... Done.
     Importing LDIF file /path/to/openidm/samples/sample2/data/Example.ldif ...... Done.
     Starting Directory Server ...... Done..
     ...

     $ bin/dsconfig create-replication-server \
     --hostname localhost \
     --port 4444 \
     -D "cn=Directory Manager" \
     -w password \
     --trustAll \
     --no-prompt \
     --provider-name "Multimaster Synchronization" \
     --set replication-port:8989 \
     --set replication-server-id:2 \
     --type generic
     $ bin/dsconfig create-replication-domain \
     --hostname localhost \
     --port 4444 \
     -D "cn=Directory Manager" \
     -w password \
     --trustAll \
     --no-prompt \
     --provider-name "Multimaster Synchronization" \
     --set base-dn:dc=example,dc=com \
     --set replication-server:localhost:8989 \
     --set server-id:3 \
     --type generic \
     --domain-name example_com

1. Prepare OpenIDM as described in "Preparing OpenIDM", then start OpenIDM with the configuration for the historical accounts sample:

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/historicalaccountlinking/
   Executing ./startup.sh...
   Using OPENIDM_HOME:   /path/to/openidm
   Using PROJECT_HOME:   /path/to/openidm/samples/historicalaccountlinking/
   Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m
   Using LOGGING_CONFIG: -Djava.util.logging.config.file=
         /path/to/openidm/samples/historicalaccountlinking//conf/logging.properties
   Using boot properties at
         /path/to/openidm/samples/historicalaccountlinking/conf/boot/boot.properties
   -> OpenIDM ready

2. Create a user, Joe Smith, in OpenIDM.

   You can create the user over the REST interface, or by using the Admin UI. The following command creates the user over REST, and assigns the user the ID joesmith:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "userName": "joe.smith",
        "givenName": "Joe",
        "sn" : "Smith",
        "password" : "Passw0rd",
        "displayName" : "Joe Smith",
        "mail" : "joe.smith@example.com",
        "_id" : "joesmith"
    }' \
    "https://localhost:8443/openidm/managed/user?_action=create"
   {
     "_id": "joesmith",
     "_rev": "1",
     "userName": "joe.smith",
     "givenName": "Joe",
     "sn": "Smith",
     "displayName": "Joe Smith",
     "mail": "joe.smith@example.com",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }
        

   Tip

   To create the user by using the Admin UI, select Manage > User > New User and enter the details of the new user.

3. Verify that the user Joe Smith was created in OpenDJ.

   Because implicit synchronization is enabled by default, any change to the managed/user repository should be propagated to OpenDJ. For more information about implicit synchronization, see "Types of Synchronization" in the Integrator's Guide.

   The following command returns all IDs in OpenDJ and shows that user joesmith was created successfully:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/system/ldap/account?_queryId=query-all-ids"
   {
     "result": [
       {
         "_id": "uid=jdoe,ou=People,dc=example,dc=com",
         "dn": "uid=jdoe,ou=People,dc=example,dc=com"
       },
       {
         "_id": "uid=bjensen,ou=People,dc=example,dc=com",
         "dn": "uid=bjensen,ou=People,dc=example,dc=com"
       },
       {
         "_id": "uid=joe.smith0,ou=People,dc=example,dc=com",
         "dn": "uid=joe.smith0,ou=People,dc=example,dc=com"
       }
     ],
   ...
   }

   Note that Joe Smith's uid in OpenDJ is appended with a 0. The onCreate script, defined in the mapping (sync.json), increments the uid each time a new OpenDJ entry is linked to the same managed user object.

4. Verify that the historical account relationship object that corresponds to this linked LDAP account was created in the OpenIDM repository.

   The following command returns all of the historicalAccounts for user joesmith:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/user/joesmith/historicalAccounts?_queryId=query-all"
   {
     "result": [
       {
         "_ref": "system/ldap/account/uid=joe.smith0,ou=People,dc=example,dc=com",
         "_refProperties": {
           "stateLastChanged": "Mon Nov 30 2015 14:45:22 GMT-0800 (PST)",
           "state": "enabled",
           "active": true,
           "linkDate": "Mon Nov 30 2015 14:45:22 GMT-0800 (PST)",
           "_id": "ff6913ce-a252-4dc9-a060-b8b56bb32bf4",
           "_rev": "1"
         }
       }
     ],
   ...
   }

   At this stage, Joe Smith has only one historical account link — the link to uid=joe.smith0,ou=People,dc=example,dc=com. Note that the relationship properties (_refProperties) show the following information about the linked accounts:

   • The date on which the accounts were linked

   • The fact that this link is currently active

   • The state of the account in OpenDJ (enabled)

5. Enable the LiveSync schedule to propagate changes made in OpenDJ to the managed user repository.

   To start LiveSync, set enabled to true in the conf/schedule-liveSync.json file:

   $ cd /path/to/openidm
   $ more  samples/historicalaccountlinking/conf/schedule-liveSync.json
   {
       "enabled" : true,
       "type" : "cron",
       "schedule" : "0/15 * * * * ?",
   ...

6. Use the manage-account command in the opendj/bin directory to disable Joe Smith's account in OpenDJ:

   $ cd /path/to/opendj
   $ bin/manage-account set-account-is-disabled \
   --port 4444 \
   --bindDN "cn=Directory Manager" \
   --bindPassword password \
   --operationValue true \
   --targetDN uid=joe.smith0,ou=people,dc=example,dc=com \
   --trustAll
   Account Is Disabled:  true

   Within 15 seconds, according to the configured schedule, LiveSync should pick up the change. OpenIDM should then adjust the state property in Joe Smith's managed user account.

7. Check Joe Smith's historical accounts again, to make sure that the state of this linked account has changed:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/user/joesmith/historicalAccounts?_queryId=query-all"
   {
     "result": [
       {
         "_ref": "system/ldap/account/uid=joe.smith0,ou=People,dc=example,dc=com",
         "_refProperties": {
           "stateLastChanged": "Mon Nov 30 2015 14:54:45 GMT-0800 (PST)",
           "state": "disabled",
           "active": true,
           "linkDate": "Mon Nov 30 2015 14:45:22 GMT-0800 (PST)",
           "_id": "ff6913ce-a252-4dc9-a060-b8b56bb32bf4",
           "_rev": "2"
         }
       }
     ],
   ...
   }

8. Now, deactivate Joe Smith's managed user account by setting his accountStatus property to inactive.

   You can deactivate the account over the REST interface, or by using the Admin UI.

   To use the Admin UI, simply select Manage > User, select Joe Smith's account and change his Status to inactive, on his Details tab.

   The following command deactivates Joe Smith's account over REST:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request PATCH \
    --data '[
         { "operation" : "replace",
           "field" : "accountStatus",
           "value" : "inactive" }
    ]' \
    "https://localhost:8443/openidm/managed/user/joesmith"
   {
     "_id": "joesmith",
     "_rev": "3",
     "userName": "joe.smith",
     ...
     "accountStatus": "inactive",
    ...
   }
   

9. Request Joe Smith's historical accounts again:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/user/joesmith/historicalAccounts?_queryId=query-all"
   {
     "result": [
       {
         "_ref": "system/ldap/account/uid=joe.smith0,ou=People,dc=example,dc=com",
         "_refProperties": {
           "stateLastChanged": "Mon Nov 30 2015 14:54:45 GMT-0800 (PST)",
           "state": "disabled",
           "active": false,
           "linkDate": "Mon Nov 30 2015 14:45:22 GMT-0800 (PST)",
           "unlinkDate": "Mon Nov 30 2015 14:58:30 GMT-0800 (PST)",
           "_id": "ff6913ce-a252-4dc9-a060-b8b56bb32bf4",
           "_rev": "3"
         }
       }
     ],
   ...
   }

10. Activate Joe Smith's managed user account by setting his accountStatus property to active. This action should create a new entry in OpenDJ (with uid=joe.smith1), and a new link from Joe Smith's managed user object to that OpenDJ entry.

    You can activate the account over the REST interface, or by using the Admin UI, as described previously.

    The following command activates Joe Smith's account over REST:

    $ curl \
     --cacert self-signed.crt \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --header "Content-Type: application/json" \
     --request PATCH \
     --data '[
          { "operation" : "replace",
            "field" : "accountStatus",
            "value" : "active" }
     ]' \
     "https://localhost:8443/openidm/managed/user/joesmith"
    {
      "_id": "joesmith",
      "_rev": "4",
      "userName": "joe.smith",
      ...
      "accountStatus": "active",
     ...
    }
    

11. Verify that a new LDAP entry for user Joe Smith was created in OpenDJ.

    The following command returns all IDs in OpenDJ and shows that two OpenDJ entries for Joe Smith uid=joe.smith0 and uid=joe.smith1.

    $ curl \
     --cacert self-signed.crt \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request GET \
     "https://localhost:8443/openidm/system/ldap/account?_queryId=query-all-ids"
    {
      "result": [
        {
          "_id": "uid=jdoe,ou=People,dc=example,dc=com",
          "dn": "uid=jdoe,ou=People,dc=example,dc=com"
        },
        {
          "_id": "uid=bjensen,ou=People,dc=example,dc=com",
          "dn": "uid=bjensen,ou=People,dc=example,dc=com"
        },
        {
          "_id": "uid=joe.smith0,ou=People,dc=example,dc=com",
          "dn": "uid=joe.smith0,ou=People,dc=example,dc=com"
        },
        {
          "_id": "uid=joe.smith1,ou=People,dc=example,dc=com",
          "dn": "uid=joe.smith1,ou=People,dc=example,dc=com"
        }
      ],
    ...
    }

12. Request Joe Smith's historical accounts again:

    $ curl \
     --cacert self-signed.crt \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request GET \
     "https://localhost:8443/openidm/managed/user/joesmith/historicalAccounts?_queryId=query-all"
    {
      "result": [
        {
          "_ref": "system/ldap/account/uid=joe.smith0,ou=People,dc=example,dc=com",
          "_refProperties": {
            "stateLastChanged": "Mon Nov 30 2015 14:54:45 GMT-0800 (PST)",
            "state": "disabled",
            "active": false,
            "linkDate": "Mon Nov 30 2015 14:45:22 GMT-0800 (PST)",
            "unlinkDate": "Mon Nov 30 2015 14:58:30 GMT-0800 (PST)",
            "_id": "ff6913ce-a252-4dc9-a060-b8b56bb32bf4",
            "_rev": "3"
          }
        },
        {
          "_ref": "system/ldap/account/uid=joe.smith1,ou=People,dc=example,dc=com",
          "_refProperties": {
            "stateLastChanged": "Mon Nov 30 2015 15:00:00 GMT-0800 (PST)",
            "state": "enabled",
            "active": true,
            "linkDate": "Mon Nov 30 2015 15:00:00 GMT-0800 (PST)",
            "_id": "08443775-7420-4994-bf86-9b29a986bfc9",
            "_rev": "1"
          }
        }
      ],
      ...
    }

    Note that Joe Smith's entry now shows two OpenDJ accounts, but that only the link to uid=joe.smith1 is enabled and active.

1. Download OpenDJ from ForgeRock's download site and extract the zip archive.

2. Install OpenDJ, using either the UI or the command-line setup.

   If you use the UI, import the Example.ldif file during the install.

   If you use the command-line setup, import the Example.ldif file during the setup as follows:

   $ cd /path/to/opendj
   $ ./setup --cli \
   --hostname localhost \
   --ldapPort 1389 \
   --rootUserDN "cn=Directory Manager" \
   --rootUserPassword password \
   --adminConnectorPort 4444 \
   --baseDN dc=com \
   --ldifFile /path/to/openidm/samples/multiplepasswords/data/Example.ldif \
   --acceptLicense \
   --no-prompt
   ...
   Configuring Directory Server ..... Done.
   Importing LDIF file /path/to/openidm/samples/multiplepasswords/data/Example.ldif ...... Done.
   Starting Directory Server ...... Done.
   ...

3. Run an ldapsearch on the LDAP directory and look at the organizational units:

   $ cd /path/to/opendj
   $ bin/ldapsearch \
   --hostname localhost \
   --port 1389 \
   --bindDN "cn=directory manager" \
   --bindPassword password \
   --baseDN "dc=example,dc=com" \
   "ou=*" \
   ou
   dn: ou=People,dc=example,dc=com
   ou: people
   
   dn: ou=Customers,dc=example,dc=com
   ou: people
   ou: Customers

   The organizational units, ou=People and ou=Customers, represent the two different target LDAP systems that our mappings point to.

1. Prepare OpenIDM as described in "Preparing OpenIDM", then start OpenIDM with the configuration for the multiple passwords sample.

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/multiplepasswords

2. Create a user in OpenIDM. Include a main password field but no additional password fields. The additional password fields (ldapPassword and ldap2Password) will be populated with the value of the main password field as a result of the script described previously.

   For the purposes of this example, we will not use the Admin UI, so that the result of each command can be clearly seen. Create the user over REST, by running the following command:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
      "userName": "jdoe",
      "givenName": "John",
      "sn" : "Doe",
      "displayName" : "John Doe",
      "mail" : "john.doe@example.com",
      "password" : "Passw0rd"
    }' \
    "https://localhost:8443/openidm/managed/user/jdoe"
   {
     "code": 403,
     "reason": "Forbidden",
     "message": "Policy validation failed",
     "detail": {
       "result": false,
       "failedPolicyRequirements": [
         {
           "policyRequirements": [
             {
               "policyRequirement": "AT_LEAST_X_CAPITAL_LETTERS",
               "params": {
                 "numCaps": 2
               }
             }
           ],
           "property": "ldapPassword"
         },
         {
           "policyRequirements": [
             {
               "policyRequirement": "AT_LEAST_X_NUMBERS",
               "params": {
                 "numNums": 2
               }
             }
           ],
           "property": "ldap2Password"
         }
       ]
     }
   }

   Notice that the create request failed with a policy validation failure on the two new password fields. Although the password met the requirement for the main password field, the user could not be created because the password did not meet the requirements of the ldapPassword and ldap2Password fields.

   You can fix this problem either by updating the password field to one that passes both of the new requirements, or by updating the individual password fields to specifically pass their individual validation requirements.

3. Now, try to create user jdoe again, this time providing individual values for each of the different password fields, that comply with the three different password policies:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
      "userName": "jdoe",
      "givenName": "John",
      "sn" : "Doe",
      "displayName" : "John Doe",
      "mail" : "john.doe@example.com",
      "password" : "Passw0rd",
      "ldapPassword" : "PPassw0rd",
      "ldap2Password" : "Passw00rd"
    }' \
    "https://localhost:8443/openidm/managed/user/jdoe"
   {
     "_id": "jdoe",
     "_rev": "1",
     "userName": "jdoe",
     "givenName": "John",
     "sn": "Doe",
     "displayName": "John Doe",
     "mail": "john.doe@example.com",
     "ldapPassword": {
       "$crypto": {
         "value": {
           "algorithm": "SHA-256",
           "data": "CpbVZlXAEFL/LUqWyq9Bcks/tLVwJ0pHrc/smLWf8UmC/0BDtEKRo1o2IjB6mNFz"
         },
         "type": "salted-hash"
       }
     },
     "ldap2Password": {
       "$crypto": {
         "value": {
           "iv": "TbJlRF+cSFeOguclh8AZVg==",
           "data": "zQ250CXfR3QJ3cBKjpCQhQ==",
           "cipher": "AES/CBC/PKCS5Padding",
           "key": "openidm-sym-default"
         },
         "type": "x-simple-encryption"
       }
     },
   ...
   }

   The user has been created with three different passwords that comply with three distinct password policies. The passwords have been hashed or encrypted, as defined in the managed.json file.

4. As a result of implicit synchronization, two separate LDAP accounts should have been created for user jdoe on our two simulated LDAP servers. For more information about implicit synchronization, see "Types of Synchronization" in the Integrator's Guide.

5. Query the IDs in the LDAP directory as follows:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/system/ldap/account?_queryId=query-all-ids"
   {
     "result" : [ {
       "_id" : "uid=jdoe,ou=People,dc=example,dc=com",
       "dn" : "uid=jdoe,ou=People,dc=example,dc=com"
     }, {
       "_id" : "uid=jdoe,ou=Customers,dc=example,dc=com",
       "dn" : "uid=jdoe,ou=Customers,dc=example,dc=com"
     } ],
   ...
   }

   Note that jdoe has two entries - one in ou=People and one in ou=Customers.

6. Now, see if you can search each LDAP server, as user jdoe, with the separate passwords that you created for each directory.

   This step will indicate that the passwords were propagated correctly to the separate LDAP servers.

   $ cd /path/to/opendj
   $ bin/ldapsearch \
   --hostname localhost \
   --port 1389 \
   --bindDN uid=jdoe,ou=People,dc=example,dc=com \
   --bindPassword PPassw0rd \
   --baseDN dc=example,dc=com \
   uid=jdoe
   dn: uid=jdoe,ou=People,dc=example,dc=com
   objectClass: organizationalPerson
   objectClass: person
   objectClass: inetOrgPerson
   objectClass: top
   uid: jdoe
   mail: john.doe@example.com
   sn: Doe
   cn: John Doe
   userPassword: {SSHA}ot11NT7zidSxXEDtNE+8qQjyfIE3CDbywKGYmQ==
   givenName: John
   
   dn: uid=jdoe,ou=Customers,dc=example,dc=com
   objectClass: organizationalPerson
   objectClass: person
   objectClass: inetOrgPerson
   objectClass: top
   uid: jdoe
   mail: john.doe@example.com
   sn: Doe
   cn: John Doe
   givenName: John
   $ bin/ldapsearch \
   --hostname localhost \
   --port 1389 \
   --bindDN uid=jdoe,ou=Customers,dc=example,dc=com \
   --bindPassword Passw00rd \
   --baseDN dc=example,dc=com \
   uid=jdoe
   dn: uid=jdoe,ou=People,dc=example,dc=com
   objectClass: organizationalPerson
   objectClass: person
   objectClass: inetOrgPerson
   objectClass: top
   uid: jdoe
   mail: john.doe@example.com
   sn: Doe
   cn: John Doe
   userPassword: {SSHA}ot11NT7zidSxXEDtNE+8qQjyfIE3CDbywKGYmQ==
   givenName: John
   
   dn: uid=jdoe,ou=Customers,dc=example,dc=com
   objectClass: organizationalPerson
   objectClass: person
   objectClass: inetOrgPerson
   objectClass: top
   uid: jdoe
   mail: john.doe@example.com
   sn: Doe
   cn: John Doe
   givenName: John

7. Patch jdoe's managed user entry to change his ldapPassword.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request PATCH \
    --data '[ {
      "operation" : "replace",
      "field" : "ldapPassword",
      "value" : "TTestw0rd"
    } ]' \
    "https://localhost:8443/openidm/managed/user/jdoe"
   {
     "_id": "jdoe",
     "_rev": "2",
     "userName": "jdoe",
     "givenName": "John",
     "sn": "Doe",
     "displayName": "John Doe",
      ...
     "ldapPassword": {
       "$crypto": {
         "value": {
           "algorithm": "SHA-256",
           "data": "Vc6hvmzXaSSdG9WroqOTg3PQVdixhpg9tD/uKT610Z/H5iC6vsoOpE0/R5FaiDUg"
         },
         "type": "salted-hash"
       }
     },
    ...
   }

8. Search the "first" LDAP server again, as user jdoe, with this new password to verify that the password change was propagated correctly to the LDAP server.

   $ cd /path/to/opendj
   $ bin/ldapsearch \
   --hostname localhost \
   --port 1389 \
   --bindDN uid=jdoe,ou=People,dc=example,dc=com \
   --bindPassword TTestw0rd \
   --baseDN dc=example,dc=com \
   uid=jdoe
   dn: uid=jdoe,ou=People,dc=example,dc=com
   objectClass: organizationalPerson
   objectClass: person
   objectClass: inetOrgPerson
   objectClass: top
   userPassword: {SSHA}pXV9/eZq6L30L/lGTsMV/39Dzjv/zHqIhWpLRw==
   uid: jdoe
   mail: john.doe@example.com
   sn: Doe
   givenName: John
   cn: John Doe
   
   dn: uid=jdoe,ou=Customers,dc=example,dc=com
   objectClass: organizationalPerson
   objectClass: person
   objectClass: inetOrgPerson
   objectClass: top
   uid: jdoe
   mail: john.doe@example.com
   sn: Doe
   cn: John Doe
   givenName: John

1. Send the following patch requests, changing the value of jdoe's ldapPassword each time:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request PATCH \
    --data '[ {
      "operation" : "replace",
      "field" : "ldapPassword",
      "value" : "TTestw0rd1"
    } ]' \
    "https://localhost:8443/openidm/managed/user/jdoe"
   {
     "_id": "jdoe",
     "_rev": "3",
     "userName": "jdoe",
     "givenName": "John",
     "sn": "Doe",
     "displayName": "John Doe",
     "mail": "john.doe@example.com",
   ...
     "ldapPassword": {
       "$crypto": {
         "value": {
           "algorithm": "SHA-256",
           "data": "uFacwvr8JsiDwlfI7I/5M+q6jTmQT8e5BaNqxLRcVR+8JxA+/fqyOc8Wo0GhzIz6"
         },
         "type": "salted-hash"
       }
     },
   }
   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request PATCH \
    --data '[ {
      "operation" : "replace",
      "field" : "ldapPassword",
      "value" : "TTestw0rd2"
    } ]' \
    "https://localhost:8443/openidm/managed/user/jdoe"
   {
     "_id": "jdoe",
     "_rev": "4",
     "userName": "jdoe",
     "givenName": "John",
     "sn": "Doe",
     "displayName": "John Doe",
     ...
     "ldapPassword": {
       "$crypto": {
         "value": {
           "algorithm": "SHA-256",
           "data": "kzxz6Nc38srk28xhaBLNX1DDtVsauKnDERoXyVy/TSYtEiMWd2KitgTn7498lZs0"
         },
         "type": "salted-hash"
       }
     }
   }
   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request PATCH \
    --data '[ {
      "operation" : "replace",
      "field" : "ldapPassword",
      "value" : "TTestw0rd3"
    } ]' \
    "https://localhost:8443/openidm/managed/user/jdoe"
   {
     "_id": "jdoe",
     "_rev": "5",
     "userName": "jdoe",
     "givenName": "John",
     "sn": "Doe",
     "displayName": "John Doe",
    ...
     "ldapPassword": {
       "$crypto": {
         "value": {
           "algorithm": "SHA-256",
           "data": "5NEEkfSsUHFOyEHa/C6yXl9x8s3Q5yaLYJgF02Lp/hPQ8DBKmwUU0U37cqFlQLQX"
         },
         "type": "salted-hash"
       }
     }
   }

   User jdoe now has a history of ldapPassword values, that contains TTestw0rd3, TTestw0rd2, TTestw0rd1, and TTestw0rd, in that order. You can see the four separate hashed values in the fieldHistory property of the user:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/user/jdoe?_fields=fieldHistory"
   {
     "_id": "jdoe",
     "_rev": "5",
     "fieldHistory": {
       ...
       "ldapPassword": [
         {
           "$crypto": {
             "value": {
               "algorithm": "SHA-256",
               "data": "k1A1udvQo2gAW/5HxFFjs+IG2p34prv36UsVP89YAVv/bALQTAUJjBhml+qrlLBx"
             },
             "type": "salted-hash"
           }
         },
         {
           "$crypto": {
             "value": {
               "algorithm": "SHA-256",
               "data": "LWHaTZYSUp6hP1RChZElfHmfFBQQV+FGtZuHJxsdA/j8sOvjyqeGxk+17IFCX/Ol"
             },
             "type": "salted-hash"
           }
         },
         {
           "$crypto": {
             "value": {
               "algorithm": "SHA-256",
               "data": "I4nR+Kkh0sO53Sy2V7SUc6Hv3eETC9d0HWopgDTBc9FqRZCV2C9ML0kXGJk8FhfV"
             },
             "type": "salted-hash"
           }
         },
         {
           "$crypto": {
             "value": {
               "algorithm": "SHA-256",
               "data": "um9iNdwU7XEVArep2X5I0wr4rRy7nacKXNuzzOc7Oa1f+lINHKwZKxaTyBwGbpX2"
             },
             "type": "salted-hash"
           }
         }
       ]
     }
   }

2. The history size for the ldapPassword policy is set to 2. To demonstrate the history policy, attempt to patch jdoe's entry with a password value that was used in his previous 2 password resets: TTestw0rd2:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request PATCH \
    --data '[ {
      "operation" : "replace",
      "field" : "ldapPassword",
      "value" : "TTestw0rd2"
    } ]' \
    "https://localhost:8443/openidm/managed/user/jdoe"
   {
     "code": 403,
     "reason": "Forbidden",
     "message": "Failed policy validation",
     "detail": {
       "result": false,
       "failedPolicyRequirements": [
         {
           "policyRequirements": [
             {
               "policyRequirement": "IS_NEW"
             }
           ],
           "property": "ldapPassword"
         }
       ]
     }
   }

   The password reset fails the IS_NEW policy requirement.

3. Now, reset jdoe's password to a value that was not used in the previous two updates:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request PATCH \
    --data '[ {
      "operation" : "replace",
      "field" : "ldapPassword",
      "value" : "TTestw0rd"
    } ]' \
    "https://localhost:8443/openidm/managed/user/jdoe"
   {
     "_id": "jdoe",
     "_rev": "5",
     "userName": "jdoe",
     "givenName": "John",
     "sn": "Doe",
     "displayName": "John Doe",
    ...
     "ldapPassword": {
       "$crypto": {
         "value": {
           "algorithm": "SHA-256",
           "data": "5NEEkfSsUHFOyEHa/C6yXl9x8s3Q5yaLYJgF02Lp/hPQ8DBKmwUU0U37cqFlQLQX"
         },
         "type": "salted-hash"
       }
     }
   }

   This time, the password reset succeeds.

1. Create a new directory named create-connector in the openidm/samples/sample3 directory and change to that new directory.

   $ mkdir /path/to/openidm/samples/sample3/create-connector
   $ cd /path/to/openidm/samples/sample3/create-connector

2. Run the custom scripted connector bundler .jar, with the configuration file for this sample (sample3/data/scriptedsql.json).

   $ java -jar ../../../tools/custom-scripted-connector-bundler-4.0.0.jar -c ../data/scriptedsql.json
   Custom Scripted Connector Bundler for OpenIDM v4.0.0
   Generating connector sources for HRDB-ScriptedSQLConnector
   

   This step generates a Maven project (pom.xml file) and a src directory that contains the packages to be bundled into the connector.

3. In addition to the generated packages, you must add the scripts required to perform operations on your resource. The scripts to access the resource illustrated in this sample are provided in the sample3/tools directory. Copy these scripts into the generated resources/script/hrdb/ directory, so that they can be bundled with the connector.

   $ cp ../tools/* src/main/resources/script/hrdb/

   You can customize these scripts before you bundle them, to suit the requirements of your deployment. For more information about writing Groovy scripts to interact with a resource, see the OpenICF Developer's Guide.

4. Use the Maven build tool to build the custom connector, with the configuration and scripts that you provided in the previous steps.

   To run this command, you must be in the create-connector directory, in which your Maven project (pom.xml) is located.

   $ mvn install
   [INFO] Scanning for projects...
   Downloading: http://maven.forgerock.org/repo/releases/org/forgerock/openicf/connectors/
      connectors-parent/1.5.0.0/connectors-parent-1.5.0.0.pom
   Downloaded: http://maven.forgerock.org/repo/releases/org/forgerock/openicf/connectors/
    connectors-parent/1.5.0.0/connectors-parent-1.5.0.0.pom (21 KB at 9.2 KB/sec)
   [INFO]
   [INFO] ------------------------------------------------------------------------
   [INFO] Building  1.4.1.0
   [INFO] ------------------------------------------------------------------------
   ...
   [INFO] Writing OBR metadata
   [INFO] ------------------------------------------------------------------------
   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time: 48.313 s
   [INFO] Finished at: 2015-12-10T14:03:02+02:00
   [INFO] Final Memory: 37M/320M
   [INFO] ------------------------------------------------------------------------

   This step generates a connector .jar file (hrdb-connector-1.4.1.0.jar) in the target directory. This connector .jar will be used in the rest of this sample.

5. Copy the new connector .jar file to the openidm/connectors directory, so that it can be picked up by OpenIDM.

   $ cd /path/to/openim/samples/sample3
   $ cp create-connector/target/hrdb-connector-1.4.1.0.jar ../../connectors/

   You now have a custom-built connector that includes all the required files for it to be displayed in the OpenIDM Admin UI. The bundled connector also includes the scripts and provisioner configuration that enable it to be used with OpenIDM.

6. Extract the connector configuration file (provisioner.openicf-hrdb.json) from the bundled connector into your sample's conf directory.

   $ jar -xvf ../../connectors/hrdb-connector-1.4.1.0.jar conf/provisioner.openicf-hrdb.json
    inflated: conf/provisioner.openicf-hrdb.json
         

7. The generated connector configuration file includes no system actions by default.

   Edit the value of the "systemActions" property in the connector configuration file, to call a custom script (tools/ResetDatabaseScript.groovy) over the REST interface. This script will reset the hrdb database and populate it with sample data.

   The edited excerpt of the conf/provisioner.openicf-hrdb.json file should appear as follows:

   "systemActions": [
     {
       "scriptId": "ResetDatabase",
       "actions": [
         {
           "systemType": ".*HRDBConnector",
           "actionType": "Groovy",
           "actionFile": "tools\/ResetDatabaseScript.groovy"
         }
       ]
     }
   ],

   Currently, only Groovy scripts are supported for these types of actions.

8. Finally, add the generated HTML template file to the UI extensions folder, to enable the new connector to be viewed and configured in the Admin UI.

   Inside the connector jar, locate the file that contains the string 1.4.html.

   $ cd /path/to/openidm
   $ jar -tvf connectors/hrdb-connector-1.4.1.0.jar | grep "1.4.html"
    12775 Thu Dec 10 14:00:22 SAST 2015 ui/org.forgerock.openicf.connectors.hrdb.HRDBConnector_1.4.html

   Create a new extension directory for the connector template.

   $ mkdir -p ui/admin/extension/templates/connector

   Extract the HTML template file that you found in the preceding step and then move it into that directory

   $ jar -xvf connectors/hrdb-connector-1.4.1.0.jar ui/org.forgerock.openicf.connectors.hrdb.HRDBConnector_1.4.html
   inflated: ui/org.forgerock.openicf.connectors.hrdb.HRDBConnector_1.4.html
   $ mv ui/org.forgerock.openicf.connectors.hrdb.HRDBConnector_1.4.html ui/admin/extension/templates/connector
   

1. Start OpenIDM with the configuration for sample 3.

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/sample3
   Executing ./startup.sh...
   Using OPENIDM_HOME:   /path/to/openidm
   Using PROJECT_HOME:   /path/to/openidm/samples/sample3/
   Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m
   Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/samples/sample3//conf/logging.properties
   Using boot properties at /path/to/openidm/samples/sample3/conf/boot/boot.properties
   -> OpenIDM ready

2. Run the custom script described in the previous section to reset the database and populate it with sample data.

   You can run the script again, at any point, to reset the database.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "https://localhost:8443/openidm/system/hrdb?_action=script&scriptId=ResetDatabase"
   {
     "actions": [
       {
         "result": "Database reset successful."
       }
     ]
   }

   The hrdb database should now be populated with sample data.

   You can review the contents of the database as follows:

   $ mysql -u root -p
   Enter password:
   ...
   mysql > use hrdb;
   Reading table information for completion of table and column names
   You can turn off this feature to get a quicker startup with -A
   
   Database changed
   mysql > select * from users;
        
   +----+--------+--------------+-----------+----------+---------------+--------...
   | id | uid    | password     | firstname | lastname | fullname      | email  ...
   +----+--------+------------------------------------------+-----------+-------...
   |  1 | bob    | e38ad2149... | Bob       | Fleming  | Bob Fleming   | Bob.Fle...
   |  2 | rowley | 2aa60a8ff... | Rowley    | Birkin   | Rowley Birkin | Rowley....
   |  3 | louis  | 1119cfd37... | Louis     | Balfour  | Louis Balfour | Louis.B...
   |  4 | john   | a1d7584da... | John      | Smith    | John Smith    | John.Sm...
   |  5 | jdoe   | edba955d0... | John      | Doe      | John Doe      | John.Do...
   +----+--------+------------------------------------------+-----------+-------...
   5 rows in set (0.00 sec)
        

   Note

   The passwords in the output shown above are hashed to the SHA-1 standard, as they cannot be read into OpenIDM as clear text. The SHA-1 Hash function is used for compatibility reasons. Use a more secure algorithm in a production database.

1. The mapping configuration file (sync.json) for this sample includes the mapping systemHrdb_managedUser, which synchronizes users from the source hrdb database with the target OpenIDM repository.

   You can test this part of the sample by using the curl command-line utility, or the OpenIDM Administration UI.

   • To reconcile the repository by using the Administration UI:

     1. Log in to the Admin UI at the URL https://localhost:8443/admin as the default administrative user (openidm-admin) with password openidm-admin.

        Warning

        To protect your deployment in production, change the default administrative password. To do so, select Self-Service from the dropdown list at the top right of the screen and click Change Password.

        Return to the Admin View to continue with the sample. (Select Admin View from the top right dropdown list.)

     2. Select Configure > Mappings.

        The Mappings page shows two configured mappings, one from the hrdb database to the OpenIDM repository (managed/user), and one in the opposite direction.

     3. Click the first mapping (systemHrdb_managedUser) and click Reconcile Now.

   • To reconcile the repository by using the command-line, launch the reconciliation operation with the following command:

     $ curl \
     --cacert self-signed.crt \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request POST \
     "https://localhost:8443/openidm/recon?_action=recon&mapping=systemHrdb_managedUser&waitForCompletion=true"
     {
       "state": "SUCCESS",
       "_id": "f3c618aa-cc3b-49ed-9a3a-00b012db2513"
     }

   The reconciliation operation creates the five users from the MySQL database in the OpenIDM repository.

2. Retrieve the list of users from the repository.

   • To retrieve the users in the repository from the Admin UI:

     1. Select Manage > User to display the User List.

        The five users from the hrdb database have been reconciled to the OpenIDM repository.

     2. To retrieve the details of a specific user, click that user entry.

   • To retrieve the users from the repository by using the command-line, query the IDs in the repository as follows:

     $ curl \
      --cacert self-signed.crt \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --request GET \
      "https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"
     {
       "result": [
         {
           "_id": "9d7c304a-fd89-4b58-bd6a-99b2a6a94691",
           "_rev": "1"
         },
         {
           "_id": "53479e98-5460-421c-9e81-0f3a7cc45881",
           "_rev": "1"
         },
         {
           "_id": "4103b904-c7d6-45c2-a9ca-8e563a975fa8",
           "_rev": "1"
         },
         {
           "_id": "1ea17866-aaed-4c51-b3a8-5fa8eb600e04",
           "_rev": "1"
         },
         {
           "_id": "074588a6-64f8-4cce-bb2f-33490aab90ae",
           "_rev": "1"
         }
       ],
       "resultCount": 5,
       "pagedResultsCookie": null,
       "totalPagedResultsPolicy": "NONE",
       "totalPagedResults": -1,
       "remainingPagedResults": -1
     }

     To retrieve a complete user record, query the userName of the individual user entry. The following query returns the record for the user Rowley Birkin:

     $ curl \
      --cacert self-signed.crt \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --request GET \
      "https://localhost:8443/openidm/managed/user/?_queryId=for-userName&uid=rowley"
     {
       "result": [
         {
           "_id": "53479e98-5460-421c-9e81-0f3a7cc45881",
           "_rev": "1",
           "mail": "Rowley.Birkin@example.com",
           "userName": "rowley",
           "sn": "Birkin",
           "organization": "SALES",
           "givenName": "Rowley",
           "cars": [
             {
               "year": "2013",
               "make": "BMW",
               "model": "328ci"
             },
             {
               "year": "2010",
               "make": "Lexus",
               "model": "ES300"
             }
           ],
           "accountStatus": "active",
     ...
      }    

   Regardless of how you have retrieved Rowley Birkin's entry, note the cars property in this user's entry. This property demonstrates a complex object, stored in JSON format in the user entry, as a list that contains multiple objects. In the MySQL database, the car table joins to the users table through a cars.users_id column. The Groovy scripts read this data from MySQL and repackage it in a way that OpenIDM can understand. With support for complex objects, the data is passed through to OpenIDM as a list of car objects. Data is synchronized from OpenIDM to MySQL in the same way. Complex objects can also be nested to any depth.

   Group membership (not demonstrated here) is maintained with a traditional "join table" in MySQL (groups_users). OpenIDM does not maintain group membership in this way, so the Groovy scripts do the work to translate membership between the two resources.

1. Download and extract the OpenDJ zip archive from https://forgerock.org/downloads/.

2. Install OpenDJ using the command-line setup, as follows:

   $ cd /path/to/opendj
   $ ./setup --cli \
     --hostname localhost \
     --ldapPort 1389 \
     --rootUserDN "cn=Directory Manager" \
     --rootUserPassword password \
     --adminConnectorPort 4444 \
     --addBaseEntry \
     --baseDN dc=com \
     --acceptLicense \
     --no-prompt
   ...
   Configuring Directory Server ..... Done.
   Creating Base Entry dc=com ..... Done.
   Starting Directory Server ....... Done.
   ...
        

   The sample assumes the following configuration:

   • The server is installed on the localhost.

   • The server listens for LDAP connections on port 1389.

   • The administration connector port is 4444.

   • The root user DN is cn=Directory Manager.

   • The root user password is password.

3. Configure the OpenDJ server for replication.

   To enable LiveSync, this server must be configured for replication, even if it does not actually participate in a replication topology. The following commands configure the server for replication.

   $ cd /path/to/opendj/bin
   $ ./dsconfig create-replication-server \
     --hostname localhost \
     --port 4444 \
     --bindDN "cn=Directory Manager" \
     --bindPassword password \
     --provider-name "Multimaster Synchronization" \
     --set replication-port:8989 \
     --set replication-server-id:2 \
     --type generic \
     --trustAll \
     --no-prompt
   
   $ ./dsconfig create-replication-domain \
     --hostname localhost \
     --port 4444 \
     --bindDN "cn=Directory Manager" \
     --bindPassword password \
     --provider-name "Multimaster Synchronization" \
     --domain-name example_com \
     --set base-dn:dc=example,dc=com \
     --set replication-server:localhost:8989 \
     --set server-id:3 \
     --type generic \
     --trustAll \
     --no-prompt
        

4. Enable HTTP access to the OpenDJ directory server as follows:

   $ ./dsconfig set-connection-handler-prop \
    --hostname localhost \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --handler-name "HTTP Connection Handler" \
    --set enabled:true \
    --set listen-port:8090 \
    --no-prompt \
    --trustAll
        

5. Enable the OpenDJ HTTP access log.

   $ ./dsconfig set-log-publisher-prop \
    --hostname localhost \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --publisher-name "File-Based HTTP Access Logger" \
    --set enabled:true \
    --no-prompt \
    --trustAll

6. Import the LDIF data required for the sample.

   $ ./ldapmodify \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --hostname localhost \
    --port 1389 \
    --filename /path/to/openidm/samples/scriptedrest2dj/data/ldap.ldif
   Processing ADD request for dc=example,dc=com
   ADD operation successful for DN dc=example,dc=com
   Processing ADD request for ou=Administrators,dc=example,dc=com
   ADD operation successful for DN ou=Administrators,dc=example,dc=com
   Processing ADD request for uid=idm,ou=Administrators,dc=example,dc=com
   ADD operation successful for DN uid=idm,ou=Administrators,dc=example,dc=com
   Processing ADD request for ou=People,dc=example,dc=com
   ADD operation successful for DN ou=People,dc=example,dc=com
   Processing ADD request for ou=Groups,dc=example,dc=com
   ADD operation successful for DN ou=Groups,dc=example,dc=com
        

7. To configure the mapping between JSON resources and LDAP entries, copy the the configuration file for the HTTP connection handler (scriptedrest2dj/data/http-config.json) to OpenDJ's configuration directory.

   $ cd /path/to/opendj
   $ cp /path/to/openidm/samples/scriptedrest2dj/data/http-config.json config/

8. Restart OpenDJ for the configuration change to take effect.

   $ cd /path/to/opendj/bin
   $ ./stop-ds --restart
   Stopping Server...
   The Directory Server has started successfully

1. Start OpenIDM with the configuration for the ScriptedREST sample.

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/scriptedrest2dj/

2. Check the connector configuration is correct by obtaining the status of the connector, over REST.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "https://localhost:8443/openidm/system/scriptedrest?_action=test"
   {
     "ok": true,
     "connectorRef": {
       "bundleVersion": "[1.4.0.0,2.0.0.0)",
       "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
       "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector"
     },
     "objectTypes": [
       "group",
       "account"
     ],
     "config": "config/provisioner.openicf/scriptedrest",
     "enabled": true,
     "name": "scriptedrest"
   }
        

3. Create a group entry on the OpenDJ server.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
      "_id" : "group1"
    }' \
    "https://localhost:8443/openidm/system/scriptedrest/group?_action=create"
   {
       "_id": "group1",
       "cn": "group1",
       "members": null,
       "lastModified": null,
       "created": "2014-09-24T17:34:27Z",
       "displayName": "group1"
   }

4. Create a user entry on the OpenDJ server.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
      "givenName" : "Steven",
      "familyName" : "Carter",
      "emailAddress" : "scarter@example.com",
      "telephoneNumber" : "444-444-4444",
      "password" : "Passw0rd",
      "displayName" : "Steven.Carter",
      "uid" : "scarter"
    }' \
    https://localhost:8443/openidm/system/scriptedrest/account?_action=create
   {
       "_id": "scarter",
       "displayName": "Steven.Carter",
       "uid": "scarter",
       "groups": null,
       "familyName": "Carter",
       "emailAddress": "steven.carter@example.com",
       "givenName": "Steven",
       "created": "2014-09-24T17:35:46Z",
       "telephoneNumber": "444-444-4444"
   }

   Notice that at this stage, the user is not a member of any group.

5. Update Steven Carter's entry, by modifying his telephone number.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --header "If-Match: *" \
    --request PUT \
    --data '{
      "givenName" : "Steven",
      "familyName" : "Carter",
      "emailAddress" : "scarter@example.com",
      "telephoneNumber" : "555-555-5555",
      "password" : "Passw0rd",
      "displayName" : "Steven.Carter",
      "uid" : "scarter"
    }' \
    https://localhost:8443/openidm/system/scriptedrest/account/scarter
   {
       "_id": "scarter",
       "displayName": "Steven.Carter",
       "uid": "scarter",
       "groups": null,
       "familyName": "Carter",
       "emailAddress": "steven.carter@example.com",
       "givenName": "Steven",
       "created": "2014-09-24T17:35:46Z",
       "telephoneNumber": "555-555-5555"
   }

6. Add Steven Carter to the group you created previously, by updating the group entry.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --header "If-Match: *" \
    --request PUT \
    --data '{
    "_id" : "group1",
    "members" : [{"_id" : "scarter"}]
    }' \
    https://localhost:8443/openidm/system/scriptedrest/group/group1
   {
       "_id": "group1",
       "cn": "group1",
       "members": [
           {
               "displayName": "Steven.Carter",
               "_id": "scarter"
           }
       ],
       "lastModified": "2014-09-24T17:31:42Z",
       "created": "2014-09-24T17:27:37Z",
       "displayName": "group1"
   }

7. Read Steven Carter's entry, to verify that he is now a member of group1.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    https://localhost:8443/openidm/system/scriptedrest/account/scarter
   {
       "_id": "scarter",
       "displayName": "Steven.Carter",
       "uid": "scarter",
       "groups": [
           {
               "_id": "group1"
           }
       ],
       "familyName": "Carter",
       "emailAddress": "steven.carter@example.com",
       "givenName": "Steven",
       "created": "2014-09-24T17:31:04Z",
       "telephoneNumber": "555-555-5555"
   }

8. Read the group entry to verify its members.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    https://localhost:8443/openidm/system/scriptedrest/group/group1
   {
       "_id": "group1",
       "cn": "group1",
       "members": [
           {
               "displayName": "Steven.Carter",
               "_id": "scarter"
               }
       ],
       "lastModified": "2014-09-24T17:31:42Z",
       "created": "2014-09-24T17:27:37Z",
       "displayName": "group1"
   }

9. Delete the user and group entries, returning the OpenDJ server to its initial state.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request DELETE \
    https://localhost:8443/openidm/system/scriptedrest/account/scarter
   {
       "_id": "scarter"
   }
   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request DELETE \
    https://localhost:8443/openidm/system/scriptedrest/group/group1
   {
       "_id": "group1"
   }
        

1. Download and extract the OpenDJ zip archive from https://forgerock.org/downloads/.

2. Install OpenDJ using the command-line setup, as follows:

   $ cd /path/to/opendj
   $ ./setup --cli \
     --hostname localhost \
     --ldapPort 1389 \
     --rootUserDN "cn=Directory Manager" \
     --rootUserPassword password \
     --adminConnectorPort 4444 \
     --addBaseEntry \
     --baseDN dc=com \
     --acceptLicense \
     --no-prompt
   ...
   Configuring Directory Server ..... Done.
   Creating Base Entry dc=com ..... Done.
   Starting Directory Server ....... Done.
   ...
        

   The sample assumes the following configuration:

   • The server is installed on the localhost.

   • The server listens for LDAP connections on port 1389.

   • The administration connector port is 4444.

   • The root user DN is cn=Directory Manager.

   • The root user password is password.

3. Configure the OpenDJ server for replication.

   To enable liveSync, this server must be configured for replication, even if it does not actually participate in a replication topology. The following commands configure the server for replication.

   $ cd /path/to/opendj/bin
   $ ./dsconfig create-replication-server \
     --hostname localhost \
     --port 4444 \
     --bindDN "cn=Directory Manager" \
     --bindPassword password \
     --provider-name "Multimaster Synchronization" \
     --set replication-port:8989 \
     --set replication-server-id:2 \
     --type generic \
     --trustAll \
     --no-prompt
   
   $ ./dsconfig create-replication-domain \
     --hostname localhost \
     --port 4444 \
     --bindDN "cn=Directory Manager" \
     --bindPassword password \
     --provider-name "Multimaster Synchronization" \
     --domain-name example_com \
     --set base-dn:dc=example,dc=com \
     --set replication-server:localhost:8989 \
     --set server-id:3 \
     --type generic \
     --trustAll \
     --no-prompt
        

4. Enable HTTP access to the OpenDJ directory server as follows:

   $ ./dsconfig set-connection-handler-prop \
    --hostname localhost \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --handler-name "HTTP Connection Handler" \
    --set enabled:true \
    --set listen-port:8090 \
    --no-prompt \
    --trustAll
        

5. Enable the OpenDJ HTTP access log.

   $ ./dsconfig set-log-publisher-prop \
    --hostname localhost \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --publisher-name "File-Based HTTP Access Logger" \
    --set enabled:true \
    --no-prompt \
    --trustAll

6. Import the LDIF data required for the sample.

   $ ./ldapmodify \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --hostname localhost \
    --port 1389 \
    --filename /path/to/openidm/samples/scriptedcrest2dj/data/ldap.ldif
   Processing ADD request for dc=example,dc=com
   ADD operation successful for DN dc=example,dc=com
   Processing ADD request for ou=Administrators,dc=example,dc=com
   ADD operation successful for DN ou=Administrators,dc=example,dc=com
   Processing ADD request for uid=idm,ou=Administrators,dc=example,dc=com
   ADD operation successful for DN uid=idm,ou=Administrators,dc=example,dc=com
   Processing ADD request for ou=People,dc=example,dc=com
   ADD operation successful for DN ou=People,dc=example,dc=com
   Processing ADD request for ou=Groups,dc=example,dc=com
   ADD operation successful for DN ou=Groups,dc=example,dc=com
        

7. To configure the mapping between JSON resources and LDAP entries, copy the the configuration file for the HTTP connection handler (scriptedcrest2dj/data/http-config.json) to OpenDJ's configuration directory.

   $ cd /path/to/opendj
   $ cp /path/to/openidm/samples/scriptedcrest2dj/data/http-config.json config/

8. Restart OpenDJ for the configuration change to take effect.

   $ cd /path/to/opendj/bin
   $ ./stop-ds --restart
   Stopping Server...
   The Directory Server has started successfully

1. Start OpenIDM with the configuration for the ScriptedCREST sample.

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/scriptedcrest2dj/

2. Check the connector configuration is correct by obtaining the status of the connector, over REST.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "https://localhost:8443/openidm/system/scriptedcrest?_action=test"
   {
     "ok": true,
     "connectorRef": {
       "bundleVersion": "[1.4.0.0,2.0.0.0)",
       "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
       "connectorName": "org.forgerock.openicf.connectors.scriptedcrest.ScriptedCRESTConnector"
     },
     "objectTypes": [
       "groups",
       "users"
     ],
     "config": "config/provisioner.openicf/scriptedcrest",
     "enabled": true,
     "name": "scriptedcrest"
   }
        

3. Create a group entry on the OpenDJ server.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
      "_id" : "group1"
    }' \
    "https://localhost:8443/openidm/system/scriptedcrest/groups?_action=create"
   {
     "_rev": "0000000028f53bdf",
     "_id": "group1",
     "displayName": "group1",
     "meta": {
       "created": "2014-10-17T07:43:13Z"
     }
   }

4. Create a user entry on the OpenDJ server.

   $ curl \
    --cacert self-signed.crt \
    --header "Content-Type: application/json" \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    --data '{
        "name": {
            "familyName": "Carter",
            "givenName" : "Steven"
        },
        "contactInformation": {
            "emailAddress" : "scarter@example.com",
            "telephoneNumber" : "444-444-4444"
        },
        "password" : "TestPassw0rd",
        "displayName" : "Steven.Carter",
        "_id" : "scarter"
    }' \
    "https://localhost:8443/openidm/system/scriptedcrest/users?_action=create"
   {
     "_rev": "00000000d84482de",
     "meta": {
       "created": "2014-10-17T08:07:46Z"
     },
     "userName": "scarter@example.com",
     "contactInformation": {
       "emailAddress": "scarter@example.com",
       "telephoneNumber": "444-444-4444"
     },
     "name": {
       "givenName": "Steven",
       "familyName": "Carter"
     },
     "displayName": "Steven.Carter",
     "_id": "scarter"
   }

   Notice that at this stage, the user is not a member of any group.

5. Update Steven Carter's entry, by modifying his telephone number.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --header "If-Match: *" \
    --request PUT \
    --data '{
        "name": {
            "familyName": "Carter",
            "givenName" : "Steven"
        },
        "contactInformation": {
            "emailAddress" : "scarter@example.com",
            "telephoneNumber" : "555-555-5555"
        },
        "password" : "TestPassw0rd",
        "displayName" : "Steven.Carter",
        "_id" : "scarter"
    }' \
    "https://localhost:8443/openidm/system/scriptedcrest/users/scarter"
   {
     "_rev": "00000000eb8ba31c",
     "meta": {
       "created": "2014-10-17T08:07:46Z",
       "lastModified": "2014-10-17T08:25:05Z"
     },
     "userName": "scarter@example.com",
     "contactInformation": {
       "emailAddress": "scarter@example.com",
       "telephoneNumber": "555-555-5555"
     },
     "name": {
       "givenName": "Steven",
       "familyName": "Carter"
     },
     "displayName": "Steven.Carter",
     "_id": "scarter"
   }

6. Add Steven Carter to the group you created previously, by updating the members of the group entry.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --header "If-Match: *" \
    --request PUT \
    --data '{
    "_id" : "group1",
    "members" : [{"_id" : "scarter"}]
    }' \
    "https://localhost:8443/openidm/system/scriptedcrest/groups/group1"
   {
     "_rev": "0000000011ed6ea1",
     "members": [
       {
         "displayName": "Steven.Carter",
         "_id": "scarter"
       }
     ],
     "_id": "group1",
     "displayName": "group1",
     "meta": {
       "created": "2014-10-17T07:43:13Z",
       "lastModified": "2014-10-17T08:26:41Z"
     }
   }

7. Read Steven Carter's entry, to verify that he is now a member of group1.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/system/scriptedcrest/users/scarter"
   {
     "_rev": "00000000eb8ba31c",
     "groups": [
       {
         "_id": "group1"
       }
     ],
     "meta": {
       "created": "2014-10-17T08:07:46Z",
       "lastModified": "2014-10-17T08:25:05Z"
     },
     "userName": "scarter@example.com",
     "contactInformation": {
       "emailAddress": "scarter@example.com",
       "telephoneNumber": "555-555-5555"
     },
     "name": {
       "givenName": "Steven",
       "familyName": "Carter"
     },
     "displayName": "Steven.Carter",
     "_id": "scarter"
   }

8. Read the group entry to verify its members.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/system/scriptedcrest/groups/group1"
   {
     "_rev": "0000000011ed6ea1",
     "members": [
       {
         "displayName": "Steven.Carter",
         "_id": "scarter"
       }
     ],
     "_id": "group1",
     "displayName": "group1",
     "meta": {
       "created": "2014-10-17T07:43:13Z",
       "lastModified": "2014-10-17T08:26:41Z"
     }
   }

9. Delete the user and group entries, returning the OpenDJ server to its initial state.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request DELETE \
    "https://localhost:8443/openidm/system/scriptedcrest/users/scarter"
   {
       "_id": "scarter"
   }
   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request DELETE \
    "https://localhost:8443/openidm/system/scriptedcrest/groups/group1"
   {
       "_id": "group1"
   }
        

To create the Employee role by using the REST interface:

• Add the role to the

  $ curl \
   --cacert self-signed.crt \
   --header "Content-type: application/json" \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --header "If-None-Match: *" \
   --request PUT \
   --data '{
     "name" : "Employee",
     "description": "Role assigned to workers on the payroll."
   }' \
   "https://localhost:8443/openidm/managed/role/Employee"
  {
    "_id": "Employee",
    "_rev": "1",
    "name": "Employee",
    "description": "Role assigned to workers on the payroll."
  }

  In this case the role's identifier will be "Employee", as shown in the preceding response. These samples use PUT requests with a specified identifier for ease of reference. In a production environment, you should create objects with a POST request, that allows the system to generate an unmutable identifier, to avoid conflicts and referential integrity issues.

To create the Contractor role by using the Admin UI:

1. Point your browser to the Admin UI URL (for example https://localhost:8443/admin/).

2. On the Dashboard, click Manage Role > New Role.

3. Enter a name for the role (Contractor) and a description.

4. Click Save.

   The managed role has been created, but currently has no assignments. These will be added in the second roles sample.

   Note

   The Admin UI creates managed objects with an unmutable, system-generated identifier. You will see this in the next section, in which you read or query the role object.

1. Create the user entry over REST, as follows:

   $ curl
    --cacert self-signed.crt \
    --header "Content-type: application/json" \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    --data '{
      "mail":"fdoe@example.com",
      "sn":"Doe",
      "telephoneNumber":"555-1234",
      "userName":"fdoe",
      "givenName":"Felicitas",
      "description":"Felicitas Doe",
      "displayName":"fdoe"
      }' \
    "https://localhost:8443/openidm/managed/user?_action=create"
   {
     "_id": "b284f6b2-9607-4a24-9b8e-fcc6cb46a0d4",
     "_rev": "1",
     "mail": "fdoe@example.com",
     "sn": "Doe",
     "telephoneNumber": "555-1234",
     "userName": "fdoe",
     "givenName": "Felicitas",
     "description": "Felicitas Doe",
     "displayName": "fdoe",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }

   Note that Felicitas has no provisioning roles by default

   Tip

   Create the user entry in the Admin UI:

   • Click Manage User > New User from the Dashboard.

2. Assign the Employee role to Felicitas's entry by sending a PATCH request to update the entry, and providing a pointer to the managed role.

   $ curl \
    --cacert self-signed.crt \
    --header "Content-type: application/json" \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request PATCH \
    --data '[
      {
        "operation" : "add",
        "field" : "/roles/-",
        "value" : {"_ref": "managed/role/Employee"}
      }
    ]' \
    "https://localhost:8443/openidm/managed/user/b284f6b2-9607-4a24-9b8e-fcc6cb46a0d4"
   {
     "_id": "b284f6b2-9607-4a24-9b8e-fcc6cb46a0d4",
     "_rev": "2",
     "mail": "fdoe@example.com",
     "sn": "Doe",
     "telephoneNumber": "555-1234",
     "userName": "fdoe",
     "givenName": "Felicitas",
     "description": "Felicitas Doe",
     "displayName": "fdoe",
     "accountStatus": "active",
     "effectiveRoles": [
       {
         "_ref": "managed/role/Employee"
       }
     ],
     "effectiveAssignments": [],
     "roles": [
       {
         "_ref": "managed/role/Employee",
         "_refProperties": {
           "_id": "25ac5587-a3fd-430a-8ad8-04d33bfbfc61",
           "_rev": "1"
         }
       }
     ]
   }

   Tip

   Assign the role in the Admin UI:

   1. Select Manage > User and click on fdoe's entry.

   2. Click Provisioning Roles, select the Employee role and click Add Role.

   OR

   1. Select Manage > Role and click on the Employee Role.

   2. Select the Role Members tab, click Add Role Members, browse for fdoe's entry, and click Add.

3. Now, query Felicitas's entry to return her roles and effectiveRoles.

   The effectiveRoles property is a virtual property whose value is calculated based on the roles that have been assigned to a user, either directly as in this example, or indirectly, through a script. For more information about indirectly assigned roles, see "Adding Support for Dynamic Assignments" in the Integrator's Guide.

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/user?_queryFilter=/givenName+eq+'Felicitas'&_fields=_id,userName,roles,effectiveRoles"
   
   {
     "result": [
       {
         "_id": "b284f6b2-9607-4a24-9b8e-fcc6cb46a0d4",
         "_rev": "2",
         "userName": "fdoe",
         "roles": [
           {
             "_ref": "managed/role/Employee",
             "_refProperties": {
               "_id": "25ac5587-a3fd-430a-8ad8-04d33bfbfc61",
               "_rev": "1"
             }
           }
         ],
         "effectiveRoles": [
           {
             "_ref": "managed/role/Employee"
           }
         ]
       }
     ],
     "resultCount": 1,
     "pagedResultsCookie": null,
     "totalPagedResultsPolicy": "NONE",
     "totalPagedResults": -1,
     "remainingPagedResults": -1
   }
        

   Note that Felicitas's "roles" and "effectiveRoles" attributes both show the "Employee" role.

1. Assign the Contractor role to Felicitas, either by using the Admin UI, as described previously, or over the REST interface. If you use the REST interface, you will need to remember the system-generated identifier that was output when you queried the roles.

   $ curl \
    --cacert self-signed.crt \
    --header "Content-type: application/json" \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request PATCH \
    --data '[
      {
        "operation" : "add",
        "field" : "/roles/-",
        "value" : {"_ref": "managed/role/b114e270-77d9-4620-9141-aa829a05ddd6"}
      }
    ]' \
    "https://localhost:8443/openidm/managed/user/b284f6b2-9607-4a24-9b8e-fcc6cb46a0d4"
   {
     "_id": "b284f6b2-9607-4a24-9b8e-fcc6cb46a0d4",
     "_rev": "5",
     "mail": "fdoe@example.com",
     "sn": "Doe",
     "telephoneNumber": "555-1234",
     "userName": "fdoe",
     "givenName": "Felicitas",
     "description": "Felicitas Doe",
     "displayName": "fdoe",
     "accountStatus": "active",
     "effectiveRoles": [
       {
         "_ref": "managed/role/b114e270-77d9-4620-9141-aa829a05ddd6"
       }
     ],
     "effectiveAssignments": []
   }

2. Now, try to delete the Contractor role:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request DELETE \
    "https://localhost:8443/openidm/managed/role/b114e270-77d9-4620-9141-aa829a05ddd6"
   {
     "code": 409,
     "reason": "Conflict",
     "message": "Cannot delete a role that is currently assigned"
   }

   As you can see from the previous output, it is not possible to delete a role that is assigned to a user.

3. Remove the role from Felicitas's entry, either by using the Admin UI (as described previously), or by using the following PATCH remove operation:

   $ curl \
    --cacert self-signed.crt \
    --header "Content-type: application/json" \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request PATCH \
    --data '[
      {
        "operation" : "remove",
        "field" : "/roles/0"
      }
    ]' \
    "https://localhost:8443/openidm/managed/user/b284f6b2-9607-4a24-9b8e-fcc6cb46a0d4"
   {
     "_id": "b284f6b2-9607-4a24-9b8e-fcc6cb46a0d4",
     "_rev": "6",
     "mail": "fdoe@example.com",
     "sn": "Doe",
     "telephoneNumber": "555-1234",
     "userName": "fdoe",
     "givenName": "Felicitas",
     "description": "Felicitas Doe",
     "displayName": "fdoe",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }

4. Now that no users have the Contractor role assigned to their entries, you can delete the Contractor role, as follows:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request DELETE \
    "https://localhost:8443/openidm/managed/role/b114e270-77d9-4620-9141-aa829a05ddd6"
   {
     "_id": "b114e270-77d9-4620-9141-aa829a05ddd6",
     "_rev": "1",
     "name": "Contractor",
     "description": "Role for contractor workers.",
     "assignments": []
   }

   The DELETE operation returns the complete role entry.

   Tip

   Delete the Contractor role by using the Admin UI:

   1. Select Manage > Role.

   2. Select the Contractor role and click Delete Selected.

5. Verify that the Contractor role has been deleted by querying the list of managed role objects:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/role?_queryFilter=true&_prettyPrint=true"
   {
     "result" : [ {
       "_id" : "Employee",
       "_rev" : "1",
       "name" : "Employee",
       "description" : "Role assigned to workers on the payroll.",
       "assignments" : [ ]
     } ],
     "resultCount" : 1,
     "pagedResultsCookie" : null,
     "totalPagedResultsPolicy" : "NONE",
     "totalPagedResults" : -1,
     "remainingPagedResults" : -1
   }

   Note that only the Employee role remains.

   Tip

   List the remaining role objects in the Admin UI by clicking Manage > Role.

1. Prepare OpenIDM as described in "Preparing OpenIDM", then start OpenIDM with the configuration for the Provisioning sample.

   $ cd /path/to/openidm

   $ startup.sh -p samples/roles/provrole

2. Create the Employee and Contractor roles, either by using the Admin UI (as described in the previous sample), or by running the following commands:

   $ curl \
    --cacert self-signed.crt \
    --header "Content-type: application/json" \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "If-None-Match: *" \
    --request PUT \
    --data '{
      "name" : "Employee",
      "description": "Role assigned to workers on the payroll."
    }' \
    "https://localhost:8443/openidm/managed/role/Employee"
   {
     "_id": "Employee",
     "_rev": "1",
     "name": "Employee",
     "description": "Role assigned to workers on the payroll."
   }

   $ curl \
    --cacert self-signed.crt \
    --header "Content-type: application/json" \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "If-None-Match: *" \
    --request PUT \
    --data '{
      "name" : "Contractor",
      "description": "Role assigned to contract workers."
    }' \
    "https://localhost:8443/openidm/managed/role/Contractor"
   {
     "_id": "Contractor",
     "_rev": "1",
     "name": "Contractor",
     "description": "Role assigned to contract workers."
   }

3. Reconcile the repository.

   The sync.json configuration file for this sample includes two mappings: systemLdapAccounts_managedUser, which synchronizes users from the source LDAP server with the target OpenIDM repository; and managedUser_systemLdapAccounts, which synchronizes changes from the OpenIDM repository with the LDAP server.

   Run a reconciliation operation for the first mapping, either by using the Admin UI, or over the REST interface:

   • To use the Admin UI, select Configure > Mapping, click on the first mapping (System/Ldap/Account --> Managed User) and click Reconcile Now.

   • To use the REST interface, run the following command:

     $ curl \
      --cacert self-signed.crt \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --request POST \
      "https://localhost:8443/openidm/recon?_action=recon&mapping=systemLdapAccounts_managedUser&waitForCompletion=true"
     {
       "_id": "b5c535f8-5c1f-44dc-afa3-40d4f9984925-24",
       "state": "SUCCESS"
     }
          

1. Start OpenIDM with the configuration for the provisioning sample.

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/workflow

2. Log in to the Admin UI (https://localhost:8443/admin) with the default username (openidm-admin and password (openidm-admin).

3. Configure the outbound email service.

   An email configuration is required to send a password-reset email to the user, at the end of the sample.

   Select Configure > System Preferences > Email and provide connection information for your preferred email host.

   Gmail is configured by default but you must still supply credentials to use Gmail.

4. Reconcile the role data, and the user data.

   1. Select Configure > Mappings.

   2. Click the first mapping (systemRolesFileRole_managedRole) and click Reconcile Now.

      This reconciliation operation creates two roles in the managed repository (employee and manager). You can check the result of the reconciliation by selecting Manage > Role.

   3. Go back to the Mappings page (Configure > Mappings), select the second mapping (systemXmlfileAccounts_managedUser) and click Reconcile Now.

      This reconciliation operation creates the top-level managers (users who do not have their own manager property) in the managed user repository. In this sample, there is only one top-level manager (manager1).

   4. Click Reconcile Now a second time.

      This reconciliation operation creates the employees of the managers that were created by the previous reconciliation. In this sample, there is only one employee (employee1).

      Check that the manager and employee entries were created correctly by selecting Manage > User. You should have two users — manager1 and user1.

5. Verify the relationships between your new user and role objects:

   1. Click on user1. Note that the Manager field shows manager1 for this user.

   2. On the Authorization Roles tab, note that user1 has two roles — employee and openidm-authorized.

   3. Click Back to User List then click on manager1. Note that the Manager field is empty for this user.

   4. On the Authorization Roles tab, note that manager1 has two roles — manager and openidm-authorized.

6. Verify the available workflows:

   1. Select Manage > Processes > Definitions.

   2. Click the Contractor onboarding process and look at the sequence diagram for this workflow.

7. Log out of the Admin UI by selecting Log Out from the top right dropdown menu.

1. Log in to the Self-Service UI (https://localhost:8443/) as the user you created in the previous section (user1), with password Welcome1.

   The user Dashboard is displayed:

   

2. Initiate the provisioning workflow as user1:

   1. Under Processes, click the Details link next to the Contractor onboarding process and complete the form for the sample user you will be creating.

      Use an email address that you have access to because you will need the email that is sent to this address to complete the workflow.

      In the Provision to XML field, select Yes.

      This selection enables implicit synchronization from the managed user repository to the XML file.

      

      Note that user1 does not provide the password for this user. This is to ensure that only the actual contractor can log in with this account

   2. Click Start to initiate the process.

   3. Log out of the Self-Service UI.

3. Approve the workflow task as manager1:

   1. Log in to the Self-Service UI as manager1, with password Welcome1.

   2. Under My Group's Tasks, locate the Approve Contractor task and select Assign to Me.

   3. Approve Contractor is now listed under My Tasks.

      Click the Details link.

   4. Check the form content. (It is the same content that you provided as user1, along with a Decision field.)

      Select Accept and click Complete to finish the task.

   5. Log out of the Self-Service UI.

4. Verify that the contractor has been created in the XML file:

   Open openidm/samples/workflow/data/xmlConnectorData.xml and note the addition of the new contractor entry. Note that there is no value for <icf:__PASSWORD__/>. Note that user1 is the contractor's manager.

   The following excerpt of the xmlConnectorData.xml shows a new user entry for bjensen, after the implicit synchronization to the XML file:

   <ri:__ACCOUNT__>
   ...
       <ri:roles>openidm-authorized</ri:roles>
       <ri:firstname>Barbara</ri:firstname>
       <ri:manager>user1</ri:manager>
       <icf:__UID__>a02536cf-84b2-4d5c-a3ae-480f5e0899e9</icf:__UID__>
       <icf:__NAME__>bjensen</icf:__NAME__>
       <ri:email>bjensen@example.com</ri:email>
       <icf:__PASSWORD__/>
       <ri:lastname>Jensen</ri:lastname>
   </ri:__ACCOUNT__>

5. Complete the password reset process:

   1. Check the inbox for the email address that you provided when you completed the initial form.

      You should have received an email with the subject "Reset your password".

   2. Open the password reset email and click Password reset link.

      The link takes you to the Self-Service UI, with the option to Reset Your Password.

   3. Enter a new password and confirmation password, submit the form.

      The password that you enter here must comply with the default password policy for managed users, described in "Enforcing Password Policy" in the Integrator's Guide.

   4. Click Return to Login Page and log in with the username that you provided when you completed the initial form, and the new password you have just set.

      Notice the Welcome message under Notifications.

6. Verify that the password reset has been propagated to the XML file:

   Open openidm/samples/workflow/data/xmlConnectorData.xml and note that the password for the contractor has been added to their entry.

1. Start OpenIDM with the configuration for use case 1.

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/usecase/usecase1

2. Run reconciliation to populate the managed user repository with the users from the OpenDJ server.

   The easiest way to run reconciliation is from the Admin UI:

   1. Log in to the Admin UI (https://localhost:8443/admin) as the administrative user (openidm-admin) with password openidm-admin.

   2. Select Configure > Mappings.

   3. Click on the only configured mapping (systemHRAccounts_managedUser) and click Reconcile Now.

   To run reconciliation from the command line, use the following command:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "https://localhost:8443/openidm/recon?_action=recon&mapping=systemHRAccounts_managedUser"
   {
    "_id": "376b3290-24f0-47a9-8a9e-bba025536c39",
    "state": "ACTIVE"
    }

3. Query the managed users that were created by the reconciliation process.

   In the Admin UI, select Manage > User and note the new entries in the User List.

   Alternatively, run the following command to view the managed user entries over REST:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"
   {
     "result": [
       {
         "_id": "user.7",
         "_rev": "1"
       },
       {
         "_id": "user.3",
         "_rev": "1"
       },
       {
         "_id": "user.4",
         "_rev": "1"
       },
    ...
       {
         "_id": "systemadmin",
         "_rev": "1"
       },
       {
         "_id": "hradmin",
         "_rev": "1"
       },
       {
         "_id": "superadmin",
         "_rev": "1"
       }
     ],
     "resultCount": 23,
     ...
   }
        

   The reconciliation process created 23 users. The default password of all the newly created users is Passw0rd.

4. Shut down OpenIDM before you proceed with the next use case.

   $ cd /path/to/openidm
   $ ./shutdown.sh
        

1. Start OpenIDM with the configuration for use case 2.

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/usecase/usecase2
        

2. Configure the outbound email service.

   Log in to the Admin UI (https://localhost:8443/admin/) as the default administrative user (openidm-admin with password openidm-admin).

   Select Configure > System Preferences > Email and provide connection information for your preferred email host.

   Gmail is configured by default but you must still supply credentials to use Gmail.

3. Log out of the Admin UI.

4. Change the notification email parameters in the workflow definition file. To edit the workflow definition file:

   1. Copy the workflow archive (.bar) file (newUserCreate.bar) to a temporary location, such as a /tmp directory:

      $ cd /path/to/openidm/samples/usecase/usecase2/workflow
      $ cp newUserCreate.bar /tmp/

   2. Unzip the temporary workflow .bar file.

      This step extracts the workflow definition file (newUserCreate.bpmn20.xml) and two xhtml templates required by the workflow:

      $ unzip /tmp/newUserCreate.bar
      Archive:  newUserCreate.bar
        inflating: nUCDecideApprovalForm.xhtml
        inflating: nUCStartForm.xhtml
        inflating: newUserCreate.bpmn20.xml

   3. Edit the extracted workflow definition file (newUserCreate.bpmn20.xml). The email parameters are towards the end of this file:

      $ cd /tmp
      $ grep emailParams newUserCreate.bpmn20.xml
      emailParams = [from : 'usecasetest@forgerock.com', to : 'notification@example.com',
      ...

      Change the from and to parameters to reflect valid email addresses.

   4. Zip up the amended workflow definition file, and the xhtml templates into a workflow .bar file.

      $ zip newUserCreate.bar newUserCreate.bpmn20.xml nUCDecideApprovalForm.xhtml nUCStartForm.xhtml
      updating: nUCDecideApprovalForm.xhtml (deflated 82%)
      updating: nUCStartForm.xhtml (deflated 82%)
      updating: newUserCreate.bpmn20.xml (deflated 85%)

   5. Copy the new .bar file to the workflow directory, overwriting the existing .bar file.

      $ cp /tmp/newUserCreate.bar /path/to/openidm/samples/usecase/usecase2/workflow

1. Start OpenIDM with the configuration for use case 2 (if you have not already done so when you configured the email service).

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/usecase/usecase2
        

2. Log in to the Self-Service UI (https://localhost:8443) as user.1 with password Passw0rd.

   In this sample, any user who logs into the Self-Service UI can view the new User Onboarding Process workflow.

3. Click Details next to User Onboarding Process link and complete the fields for a sample new user.

   Department. Specifies one of four departments that the new user will belong to (Human Resources, Production Planning, Sales & Distribution, or Treasury & Payments). The value you select here determines the manager of the new user, to which the request will be sent for approval. (See the previous table of users for a list of the managers of each department.)

   User Type. Governs user access to specific accounts. If the User Type is Employee, the new user will have access to an account named Business. This access is represented as an attribute of the managed user entry in the OpenIDM repository, as follows: accounts : ["Business"]. If the User Type is Contractor, the new user will have no accounts associated with its managed user entry in OpenIDM.

   Send Email Notification. Indicates whether an email should be sent to alert the manager of the new required approval. The email details used here are defined when you configure email notification, as described in "Configuring Email Notification". If you select not to send an email notification, the notification is simply added to the OpenIDM repository, and appears when the manager logs into the UI.

4. Click Start to initiate the onboarding workflow.

   This action sends the new user request to the corresponding management users (the department manager, as well as the superadmin user, who is an overall manager).

5. Log out of the UI, and log back in as the management user of the department that you selected when you completed the new user form. For example, if you selected Human Resources, log in as user.0, which simulates the management user for the HR department. All users have the password Passw0rd.

   Notice that the management user now has an Onboarding Approval task in the queue of tasks assigned to that user's group.

   

6. Select Assign to Me from list next to the Onboarding Approval task.

   This action claims the task for user.0, removes it from the group queue, and places it in the list of pending tasks for user.0.

7. Select Details next to the Onboarding Approval task under My Tasks.

   The complete new user request is displayed for the manager's approval. As the manager, you can add any information that was missing from the original request.

   In addition, you can specify the following information for the new user.

   • Start Date. Completing this field results in the user being created, with a startDate added to that user's managed user entry. The status of the user is inactive. This field is optional, and is used by the task scanner to trigger the Sunrise workflow.

   • End Date. Completing this field results in the user being created, with an endDate added to that user's managed user entry. The field is optional, and is used by the task scanner to trigger the Sunset workflow.

   • Decision. Selecting Reject here terminates the workflow and sends a notification to the user who initiated the workflow. Selecting Accept creates the managed user entry in OpenIDM. The password of the new user is Passw0rd.

     Two notifications are created when the request is accepted - one for the user who initiated the workflow, and one for the newly created user. The notifications are visible in the UI after login. If you selected email notification, one email is sent to the user that you defined when you configured email notification, as described in "Configuring Email Notification".

8. At the bottom of the form, there is an option either to Requeue the request or to Complete it. Click Complete.

   If you click Requeue here, the task is removed from the list of that user's tasks, and returned to the list of tasks pending for that group. The task can then be claimed by any member of that group.

   When the new user request has been approved, the user is created in the OpenIDM repository. If you did not include a Start Date in the manager approval, you should now be able to log into the UI with the details of the new user. If you included a Start Date, you need to complete the sunrise workflow before the user account is active (which will enable you to log in as this user).

If a sunrise date is specified for the new user, the user is created in the repository, with an inactive account status.

• To trigger the sunrise workflow (which activates the account), enable the sunrise task scanning schedule. The schedule is disabled by default.

  Modify the schedule configuration file (schedule-taskscan_sunrise.json), setting the enabled property to true.

  $ cd /path/to/openidm
  $ grep "enabled" samples/usecase/usecase2/conf/schedule-taskscan_sunrise.json
  "enabled" : true,

  The scan runs every minute, and checks the repository for users that have a sunrise date that is anything up to one day after the current date. When the scan is triggered, it locates the newly created user and starts the sunrise workflow on this user. The workflow takes the following actions:

  • Changes the account status of the user to active.

    You can check that this part of the workflow has completed by looking at the user's account in the Admin UI:

    1. Log in to the Admin UI as openidm-admin with password openidm-admin, then select Manage > User.

    2. Click on the account of the new user that was created in the previous section and note their Status.

       The following image shows the status for the new user jdoe, who was created by the previous workflow:

       

  • Generates a notification for the new user, which is visible when the user logs into the Self-Service UI.

  

If a sunset date is set for the new user, you can trigger the sunset workflow to deactivate the user account when the end of his work period is reached.

1. To trigger the sunset workflow, enable the sunset task scanning schedule. The schedule is disabled by default.

   Modify the schedule configuration file (schedule-taskscan_sunset.json), setting the enabled property to true.

   $ cd /path/to/openidm
   $ grep "enabled" samples/usecase/usecase2/conf/schedule-taskscan_sunset.json
        
   "enabled" : true,

   The scan runs every minute, and checks the repository for users that have a sunset date that is anything up to one day after the current date. When the scan is triggered, it locates users whose contracts are about to end, and starts the sunset workflow on these users. When the workflow is initiated, it assigns a task to the manager of the affected user. In our example, the task is assigned to user.0.

2. When the sunset schedule has been enabled, log in to the Self-Service UI as user.0 (with password Passw0rd). If the user's sunset date is within one day of the current date, a Contract Termination task becomes available under the manager's My Group's Tasks section.

   Select the contract termination task and click Details.

3. In the Decision field, select either Accept termination or Modify date, then click Complete.

   When you accept the termination, the user's account status is set to inactive and the HR administrative user receives a notification to that effect, the next time that user logs into the UI. The deactivated user is no longer able to log into the UI.

   If you select to modify the date, the sunset date of that user is changed to the value that you specify in the End Date field on that form. The management user receives a UI notification that the employee's contract has been extended.

4. Shut down OpenIDM before you proceed with the next use case.

   $ cd /path/to/openidm
   $ ./shutdown.sh
        

1. Start OpenIDM with the configuration for use case 3, if you have not already started the server to configure email notification.

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/usecase/usecase3
        

2. Log into the Self-Service UI as user.1 with password Passw0rd.

   user.1 belongs to the HR department and, in this workflow, is requesting access to a Project system.

3. Click Details next to the Access request process and click Start to start the workflow.

   A User Access Request appears in the list of tasks for user.1.

4. Click Details next to the User Access Request task.

   The resulting form indicates the various systems to which the user may request access.

   Access to Business system. This field reflects the current value of the accounts property for that user in the repository. If the value includes Business this field is True.

   Access to Project system. Set this field to True to request Project access for user.1.

   Send Email Notification. Set to True to send an email to alert the manager of the new access request. The email details used here are defined when you configure email notification, as described in "Configuring Email Notification". If you select not to send an email notification, the notification appears when the manager logs into the UI.

   Select either Cancel, to terminate the process, or Request, to start a user task, assigned to the manager of the user who is requesting access (user.0 in this example), and select Complete.

5. Log out of the Self-Service UI and log back in as the manager (user.0 with password Passw0rd).

6. Under My Group's Tasks, locate the User Access Request Approval task and select Assign to me.

   Note that the User Access Request Approval task has moved under My Tasks.

7. Click Details next to the User Access Request Approval task.

8. The details of the access request are displayed. The manager is able to modify the access rights. Select Accept or Reject to approve or deny the request.

   Rejecting the request results in a notification being sent to the user who made the request. If you have enabled email notification, a single email is sent to the account that you specified when you configured email notification.

   Accepting the request initiates a second approval task, assigned to the systemadmin user.

   

   Click Complete to complete the task.

9. Log out of the UI and log in as the systemadmin user (with password Passw0rd).

   This user now has one User Access Request Approval task in his queue.

10. Select the task and click Details.

    This task interface is similar to that of the task that was assigned to the manager.

    Rejecting the request results in a notification being sent to the user who made the request.

    Accepting the request updates the managed/user record in OpenIDM, to reflect the approved access changes.

    If you have enabled email notification, a single email is sent to the account defined when you configured the external email service ("Configuring Email Notification"), indicating whether the request has been accepted or rejected.

1. Before you start with this use case, rename the mapping file to sync.json.

   $ cd /path/to/openidm/samples/usecase/usecase4/conf
   $ mv syncManagedBusiness.json sync.json

2. Start OpenIDM with the configuration for use case 4.

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/usecase/usecase4
        

3. Reconcile the managed user repository with the CSV file, either by using the Admin UI or over the command line.

   To use the Admin UI, log in to the Admin UI (https://localhost:8443/admin/) as openidm-admin with password openidm-admin. Select Configure > Mappings, click on the mapping recon_managedUser_systemBusiness and click Reconcile Now.

   To use the command line, run the following command:

   $ curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "https://localhost:8443/openidm/recon?_action=recon&mapping=recon_managedUser_systemBusiness"

   When the reconciliation operation finds the ambiguous entry (user.3) and the orphan entry (user.50) in the CSV file, two asynchronous workflows are launched (manualMatch and orphanAccountReport), as indicated in the mapping file, described previously.

4. Log in to the Self-Service UI (https://localhost:8443) as the systemadmin user, with password Passw0rd.

5. Next to the Manual Linking Task in the My Tasks list, click Details.

   The Possible targets field presents a list of target entries to which the ambiguous record can be linked. In this example, user.3 - Atrc, Aaron and user.33 - Atrc, Aaron are the two candidate users found in the target object set by the correlation query. When you select one of these values, the workflow manually links the managed user (user.3) to the selected user.

   Click complete to finish the manual account linking task.

   If you select Ignore, here, no action is taken (no link is created), and the workflow terminates.

6. Next to the Orphan Account Task in the My Tasks list, click Details.

   The Link to field enables you to enter an existing managed user ID to which this orphan account should be linked. For the purposes of this example, enter user.5.

   In the Decision field, select Link to link the orphan account to the ID that you entered in the previous step. Click Complete to complete the task.

   Selecting Delete here deletes the user from the target object set (the CSV file in this case) and terminates the workflow.

7. Shut down OpenIDM before you proceed with the next use case.

   $ cd /path/to/openidm
   $ ./shutdown.sh

1. Set up outbound email, as described in "Configuring Email Notification".

2. Enable email notification in the script file that starts the workflow (samples/usecase/usecase6/script/passwordchange.js). For example:

   $ cd /path/to/openidm
   $ more samples/usecase/usecase6/script/passwordchange.js
   
   /*global  objectID*/
   
   (function () {
       var params = {
    "userId" : objectID,
    "emailEnabled" : "true",
    "_key": "passwordChangeReminder"
   };
        

3. Make sure that all managed users have a valid email address as the value of their mail attribute.

1. Enable the task scanning schedule by setting enabled to true in the schedule configuration file (schedule-taskscan_passwordchange.json).

   $ cd /path/to/openidm
   $ more samples/usecase/usecase6/conf/schedule-taskscan_passwordchange.json
   {
       "enabled" : true,
   ...
   
        

2. Start OpenIDM with the configuration for use case 6.

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/usecase/usecase6

3. Log in to the Self-Service UI as any of the users listed in the introduction to this section (for example, user.4, with password Passw0rd).

   You will see a password expiration notice.

   If you ignore the change for five minutes, you will see a second warning, that the password is about to expire.

   If you ignore that second warning for another two minutes, the user's account is deactivated.

4. (Optional) To avoid the second notification, or the account deactivation, you can change the user password through the UI, as follows:

   1. Log in to the UI as the user whose password you want to change and click Change Password at the top right of the page.

   2. Enter a new password that conforms to the requirements of the password policy.

   3. Enter the old password (in this case Passw0rd).