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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/managed/user?_queryId=query-all-ids"
   {
     "result": [
       {
         "_id": "scarter",
         "_rev": "2"
       },
       {
         "_id": "bjensen",
         "_rev": "2"
       },
       {
         "_id": "tmorris",
         "_rev": "1"
       }
     ],
   ...
   }

1. Download ForgeRock Directory Services (DS) from the BackStage site and extract the zip archive.

   The LDIF data for this sample is provided in the file openidm/samples/sample2/data/Example.ldif. Import this data during your OpenDJ setup.

2. Set up OpenDJ and import the Example.ldif file for this sample:

   $ cd /path/to/opendj
   $ ./setup \
    directory-server \
    --rootUserDN "cn=Directory Manager" \
    --rootUserPassword password \
    --hostname localhost \
    --ldapPort 1389 \
    --adminConnectorPort 4444 \
    --baseDN dc=com \
    --ldifFile /path/to/openidm/samples/sample2/data/Example.ldif \
    --acceptLicense
   Validating parameters .....Done.
   Configuring Certificates .....Done.
   Configuring server .....Done.
   Importing data from /path/to/openidm/samples/sample2/data/Example.ldif ........Done.
   Starting Directory Server ............Done.
   
   To see basic server status and configuration, you can launch /path/to/opendj/bin/status

1. Reconcile the repository by running the following command:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "http://localhost:8080/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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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 Reconcile.

   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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "http://localhost:8080/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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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 \
    --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"}' \
    "http://localhost:8080/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 "Mapping Source Objects to Target Objects" 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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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. On the first mapping (LDAP to managed user), click Reconcile.

   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 "Mapping Source Objects to Target Objects" 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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "http://localhost:8080/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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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 \
    --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"]
       }
    ]' \
    "http://localhost:8080/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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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. On the first mapping (LDAP to managed user), click Reconcile.

   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 \
    --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"]
       }
    ]' \
    "http://localhost:8080/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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "http://localhost:8080/openidm/recon?_action=recon&mapping=systemLdapGroups_managedGroup&waitForCompletion=true"

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

2. The reconciliation creates managed group objects for each group that exists in OpenDJ. To list the managed groups, run the following command:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/managed/group?_queryFilter=true"

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

   {
     "result": [
       {
         "_id": "b6c4d7ce-2103-42c2-b5f2-74ca9309ad37",
         "_rev": "1",
         "dn": "cn=Contractors,ou=Groups,dc=example,dc=com",
         "description": null,
         "uniqueMember": [],
         "name": "Contractors"
       },
       {
         "_id": "2326b9ee-6975-4c19-aa3c-d228afc4ff71",
         "_rev": "1",
         "dn": "cn=openidm2,ou=Groups,dc=example,dc=com",
         "description": null,
         "uniqueMember": [
           "uid=bjensen,ou=People,dc=example,dc=com"
         ],
         "name": "openidm2"
       },
       {
         "_id": "035f6444-bce3-4931-96b7-e10b2301fe74",
         "_rev": "1",
         "dn": "cn=Employees,ou=Groups,dc=example,dc=com",
         "description": null,
         "uniqueMember": [],
         "name": "Employees"
       },
       {
         "_id": "65c8fb86-01e6-4fca-9237-e50c251f4575",
         "_rev": "1",
         "dn": "cn=Chat Users,ou=Groups,dc=example,dc=com",
         "description": null,
         "uniqueMember": [],
         "name": "Chat Users"
       },
       {
         "_id": "5c3e4965-16d7-4a8f-af73-3ab165b66cf9",
         "_rev": "1",
         "dn": "cn=openidm,ou=Groups,dc=example,dc=com",
         "description": null,
         "uniqueMember": [
           "uid=jdoe,ou=People,dc=example,dc=com"
         ],
         "name": "openidm"
       }
     ],
     ...
   }

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. On the third mapping (LDAP groups to managed groups), click Reconcile.

   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 five 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 "Configuring Outbound 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 ForgeRock Directory Services (DS) from the BackStage site and extract the zip archive.

2. Set up OpenDJ and import the Example.ldif file for this sample:

   $ cd /path/to/opendj
   $ ./setup \
    directoryserver \
    --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
   .Validating parameters .....Done.
   Configuring Certificates .....Done.
   Configuring server .....Done.
   Importing data from /path/to/openidm/samples/historicalaccountlinking/data/Example.ldif ........Done.
   Starting Directory Server ............Done.
   
   To see basic server status and configuration, you can launch /path/to/opendj/bin/status

3. Enable 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 \
    --trustAll \
    --no-prompt
   $ bin/dsconfig create-replication-domain \
    --hostname localhost \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --provider-name "Multimaster Synchronization" \
    --set base-dn:dc=example,dc=com \
    --set replication-server:localhost:8989 \
    --set server-id:3 \
    --domain-name example_com\
    --trustAll \
    --no-prompt

1. Prepare OpenIDM as described in "Preparing the Server", 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.

   The following command creates the user over REST, and assigns the user the ID joesmith:

   $ curl \
    --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"
    }' \
    "http://localhost:8080/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": []
   }

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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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 \
    --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" }
    ]' \
    "http://localhost:8080/openidm/managed/user/joesmith"
   {
     "_id": "joesmith",
     "_rev": "3",
     "userName": "joe.smith",
     ...
     "accountStatus": "inactive",
    ...
   }
   

9. Request Joe Smith's historical accounts again:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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 \
     --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" }
     ]' \
     "http://localhost:8080/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 \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request GET \
     "http://localhost:8080/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 \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request GET \
     "http://localhost:8080/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 ForgeRock Directory Services (DS) from the BackStage site and extract the zip archive.

2. Set up OpenDJ and import the Example.ldif file for this sample:

   $ cd /path/to/opendj
   $ ./setup \
    directoryserver \
    --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
   .Validating parameters .....Done.
   Configuring Certificates .....Done.
   Configuring server .....Done.
   Importing data from /path/to/openidm/samples/multiplepasswords/data/Example.ldif ........Done.
   Starting Directory Server ............Done.
   
   To see basic server status and configuration, you can launch /path/to/opendj/bin/status

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 the Server", 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 \
    --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"
    }' \
    "http://localhost:8080/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 \
    --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"
    }' \
    "http://localhost:8080/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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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 \
    --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"
    } ]' \
    "http://localhost:8080/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 \
    --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"
    } ]' \
    "http://localhost:8080/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 \
    --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"
    } ]' \
    "http://localhost:8080/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 \
    --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"
    } ]' \
    "http://localhost:8080/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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/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 \
    --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"
    } ]' \
    "http://localhost:8080/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 \
    --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"
    } ]' \
    "http://localhost:8080/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-5.0.0.jar -c ../data/scriptedsql.json
   Custom Scripted Connector Bundler for OpenIDM v5.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] Installing org/forgerock/openicf/connectors/hrdb-connector/1.4.1.0/hrdb-connector-1.4.1.0.jar
   [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"
    12703 Wed Nov 09 17:42:00 SAST 2016 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/admin/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/admin/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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "http://localhost:8080/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.

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

     $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request POST \
     "http://localhost:8080/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 \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --request GET \
      "http://localhost:8080/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"
         }
       ],
       ...
     }

     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 \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --request GET \
      "http://localhost:8080/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 ForgeRock's BackStage site.

2. Set up OpenDJ as follows. Include the --httpPort option to enable HTTP access during the setup. This example uses port 8090 so that it does not conflict with the default OpenIDM port:

   $ cd /path/to/opendj
   $ ./setup \
    directory-server \
    --rootUserDN "cn=Directory Manager" \
    --rootUserPassword password \
    --hostname localhost \
    --ldapPort 1389 \
    --adminConnectorPort 4444 \
    --httpPort 8090 \
    --addBaseEntry \
    --baseDN dc=com \
    --acceptLicense
   Validating parameters .....Done.
   Configuring Certificates .....Done.
   Configuring server .....Done.
   Creating Base Entry dc=com .....Done.
   Starting Directory Server ..............Done.
   
   To see basic server status and configuration, you can launch /path/to/opendj/bin/status

   The sample assumes the following OpenDJ 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 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

5. 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
        

6. Set up the access control that enables the OpenIDM administrator user to read the OpenDJ changelog:

   $ ./dsconfig \
    set-access-control-handler-prop \
    --hostname localhost \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --add global-aci:"(target=\"ldap:///cn=changelog\")(targetattr=\"*||+\") \
    (version 3.0; acl \"IDM can access cn=changelog\"; \
    allow (read,search,compare) \
    userdn=\"ldap:///uid=idm,ou=Administrators,dc=example,dc=com\";)" \
    --trustAll \
    --no-prompt
   
   $ ./dsconfig \
    set-access-control-handler-prop \
    --hostname localhost \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --add global-aci:"(targetcontrol=\"1.3.6.1.4.1.26027.1.5.4\") \
    (version 3.0; acl \"IDM changelog control access\"; \
    allow (read) \
    userdn=\"ldap:///uid=idm,ou=Administrators,dc=example,dc=com\";)" \
    --trustAll \
    --no-prompt

7. Enable the default Rest2ldap HTTP endpoint:

   $ ./dsconfig \
    set-http-endpoint-prop \
    --hostname localhost \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --endpoint-name /api \
    --set authorization-mechanism:"HTTP Basic" \
    --set config-directory:config/rest2ldap/endpoints/api \
    --set enabled:true \
    --no-prompt \
    --trustAll

   For more information, see To Set Up REST Access to User Data in the Directory Services Administration Guide.

8. Replace the default OpenDJ REST to LDAP configuration with the configuration for this sample:

   $ cd /path/to/opendj
   $ cp /path/to/openidm/samples/scriptedrest2dj/data/example-v1.json config/rest2ldap/endpoints/api/

9. 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
   [07/Nov/2016:14:41:40 +0200] category=PROTOCOL severity=NOTICE msgID=276 msg=Started
   listening for new connections on HTTP Connection Handler 0.0.0.0 port 8090

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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "http://localhost:8080/openidm/system/scriptedrest?_action=test"
   {
     "name": "scriptedrest",
     "enabled": true,
     "config": "config/provisioner.openicf/scriptedrest",
     "objectTypes": [
       "__ALL__",
       "account",
       "group"
     ],
     "connectorRef": {
       "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
       "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector",
       "bundleVersion": "[1.4.0.0,1.5.0.0)"
     },
     "displayName": "Scripted REST Connector",
     "ok": true
   }
   
        

3. Create a group entry on the OpenDJ server.

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
      "cn" : "group1"
    }' \
    "http://localhost:8080/openidm/system/scriptedrest/group?_action=create"
   {
     "_id": "group1",
     "cn": "group1",
     "members": null,
     "displayName": "group1",
     "lastModified": null,
     "created": "2017-01-30T11:11:30Z"
   }

4. Create a user entry on the OpenDJ server. This command creates a user with uid scarter:

   $ curl \
    --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"
    }' \
    http://localhost:8080/openidm/system/scriptedrest/account?_action=create
   {
     "_id": "scarter",
     "givenName": "Steven",
     "emailAddress": "scarter@example.com",
     "uid": "scarter",
     "groups": null,
     "familyName": "Carter",
     "displayName": "Steven.Carter",
     "created": "2017-01-30T11:12:46Z",
     "telephoneNumber": "444-444-4444"
   }

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

5. Reconcile the OpenDJ server with the OpenIDM managed user repository:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    "http://localhost:8080/openidm/recon?_action=recon&mapping=systemRestLdapUser_managedUser&waitForCompletion=true"
   {
     "_id": "bb69265a-4c57-4f52-8623-db7f206f1351-57",
     "state": "SUCCESS"
   }

   The reconciliation creates a managed user whose _id is the same as his OpenDJ uid, in this case, scarter.

6. Update Steven Carter's managed user entry, by modifying his telephone number:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request PATCH \
    --data '[
        {
            "operation" : "replace",
            "field" : "telephoneNumber",
            "value" : "555-555-5555"
        }
    ]' \
    "http://localhost:8080/openidm/managed/user/scarter"
   {
     "_id": "scarter",
     "_rev": "3",
     "userName": "scarter",
     "mail": "scarter@example.com",
     "displayName": "Steven.Carter",
     "telephoneNumber": "555-555-5555",
     "givenName": "Steven",
     "sn": "Carter",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }

7. The automatic synchronization mechanism between the managed user repository and OpenDJ propagates this change to the OpenDJ server. You can check this change by reading scarter's user entry in OpenDJ:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/system/scriptedrest/account/scarter"
   {
     "_id": "scarter",
     "givenName": "Steven",
     "emailAddress": null,
     "uid": "scarter",
     "groups": null,
     "familyName": "Carter",
     "displayName": "Steven.Carter",
     "created": "2017-01-30T11:12:46Z",
     "telephoneNumber": "555-555-5555"
   }

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

   $ curl \
    --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"}]
    }' \
    http://localhost:8080/openidm/system/scriptedrest/group/group1
   {
     "_id": "group1",
     "cn": "group1",
     "members": [
       {
         "_id": "scarter",
         "displayName": "Steven.Carter"
       }
     ],
     "displayName": "group1",
     "lastModified": "2017-01-30T11:16:00Z",
     "created": "2017-01-30T11:11:30Z"
   }

9. Read Steven Carter's user entry in OpenDJ, to verify that he is now a member of group1:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    http://localhost:8080/openidm/system/scriptedrest/account/scarter
   {
     "_id": "scarter",
     "givenName": "Steven",
     "emailAddress": null,
     "uid": "scarter",
     "groups": [
       {
         "_id": "group1"
       }
     ],
     "familyName": "Carter",
     "displayName": "Steven.Carter",
     "created": "2017-01-30T11:12:46Z",
     "telephoneNumber": "555-555-5555"
   }

10. Read the group entry to verify its members:

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request GET \
     "http://localhost:8080/openidm/system/scriptedrest/group/group1"
    {
      "_id": "group1",
      "cn": "group1",
      "members": [
        {
          "_id": "scarter",
          "displayName": "Steven.Carter"
        }
      ],
      "displayName": "group1",
      "lastModified": "2017-01-30T11:16:00Z",
      "created": "2017-01-30T11:11:30Z"
    }

11. Reconcile the OpenDJ groups with the OpenIDM managed group repository:

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request POST \
     "http://localhost:8080/openidm/recon?_action=recon&mapping=systemRestLdapGroup_managedGroup&waitForCompletion=true"
    {
      "_id": "08a85706-b191-41bd-89a6-4cd69832af4f-127",
      "state": "SUCCESS"
    }

12. Read the managed group to verify that the OpenDJ group has been added, and that its members have been reconciled to the managed group repository:

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request GET \
     "http://localhost:8080/openidm/managed/group/group1"
    {
      "_id": "group1",
      "_rev": "1",
      "members": [
        {
          "displayName": "Steven.Carter",
          "_id": "scarter"
        }
      ],
      "displayName": "group1"
    }

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

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request DELETE \
     http://localhost:8080/openidm/system/scriptedrest/account/scarter
    {
      "_id": "scarter",
      "givenName": "Steven",
      "emailAddress": null,
      "uid": "scarter",
      "groups": [
        {
          "_id": "group1"
        }
      ],
      "familyName": "Carter",
      "displayName": "Steven.Carter",
      "created": "2017-01-30T11:12:46Z",
      "telephoneNumber": "555-555-5555"
    }
    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request DELETE \
     http://localhost:8080/openidm/system/scriptedrest/group/group1
    {
      "_id": "group1",
      "cn": "group1",
      "members": null,
      "displayName": "group1",
      "lastModified": "2017-01-30T11:16:00Z",
      "created": "2017-01-30T11:11:30Z"
    }
         

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

2. Set up OpenDJ as follows. Include the --httpPort option to enable HTTP access during the setup. This example uses port 8090 so that it does not conflict with the default OpenIDM port:

   $ cd /path/to/opendj
   $ ./setup \
    directory-server \
    --rootUserDN "cn=Directory Manager" \
    --rootUserPassword password \
    --hostname localhost \
    --ldapPort 1389 \
    --adminConnectorPort 4444 \
    --httpPort 8090 \
    --addBaseEntry \
    --baseDN dc=com \
    --acceptLicense
   Validating parameters .....Done.
   Configuring Certificates .....Done.
   Configuring server .....Done.
   Creating Base Entry dc=com .....Done.
   Starting Directory Server ..............Done.
   
   To see basic server status and configuration, you can launch /path/to/opendj/bin/status

   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 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

5. 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
        

6. Set up the access control that enables the OpenIDM administrator user to read the OpenDJ changelog:

   $ ./dsconfig \
    set-access-control-handler-prop \
    --hostname localhost \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --add global-aci:"(target=\"ldap:///cn=changelog\")(targetattr=\"*||+\") \
    (version 3.0; acl \"IDM can access cn=changelog\"; \
    allow (read,search,compare) \
    userdn=\"ldap:///uid=idm,ou=Administrators,dc=example,dc=com\";)" \
    --trustAll \
    --no-prompt
   
   $ ./dsconfig \
    set-access-control-handler-prop \
    --hostname localhost \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --add global-aci:"(targetcontrol=\"1.3.6.1.4.1.26027.1.5.4\") \
    (version 3.0; acl \"IDM changelog control access\"; \
    allow (read) \
    userdn=\"ldap:///uid=idm,ou=Administrators,dc=example,dc=com\";)" \
    --trustAll \
    --no-prompt

7. Enable the default Rest2ldap HTTP endpoint:

   $ ./dsconfig \
    set-http-endpoint-prop \
    --hostname localhost \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --endpoint-name /api \
    --set authorization-mechanism:"HTTP Basic" \
    --set config-directory:config/rest2ldap/endpoints/api \
    --set enabled:true \
    --no-prompt \
    --trustAll

   For more information, see To Set Up REST Access to User Data in the Directory Services Administration Guide.

8. Replace the default OpenDJ REST to LDAP configuration with the configuration for this sample:

   $ cd /path/to/opendj
   $ cp /path/to/openidm/samples/scriptedcrest2dj/data/example-v1.json config/rest2ldap/endpoints/api/

9. 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
   [30/Jan/2017:13:28:05 +0200] category=PROTOCOL severity=NOTICE msgID=276 msg=Started
    listening for new connections on HTTP Connection Handler 0.0.0.0 port 8090

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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "http://localhost:8080/openidm/system/scriptedcrest?_action=test"
   {
     "name": "scriptedcrest",
     "enabled": true,
     "config": "config/provisioner.openicf/scriptedcrest",
     "objectTypes": [
       "groups",
       "__ALL__",
       "users"
     ],
     "connectorRef": {
       "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
       "connectorName": "org.forgerock.openicf.connectors.scriptedcrest.ScriptedCRESTConnector",
       "bundleVersion": "[1.4.0.0,1.5.0.0)"
     },
     "displayName": "Scripted CREST Connector",
     "ok": true
   }
        

3. Create a group entry on the OpenDJ server.

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
      "_id" : "group1"
    }' \
    "http://localhost:8080/openidm/system/scriptedcrest/groups?_action=create"
   {
     "_id": "group1",
     "_rev": "000000002f333c9f",
     "displayName": "group1"
   }

4. Create a user entry on the OpenDJ server.

   $ curl \
    --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"
    }' \
    "http://localhost:8080/openidm/system/scriptedcrest/users?_action=create"
   {
     "_id": "scarter",
     "_rev": "00000000105e85d3",
     "contactInformation": {
       "emailAddress": "scarter@example.com",
       "telephoneNumber": "444-444-4444"
     },
     "userName": "scarter@example.com",
     "name": {
       "givenName": "Steven",
       "familyName": "Carter"
     },
     "displayName": "Steven.Carter"
   }

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

5. Reconcile the OpenDJ server with the OpenIDM managed user repository:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    "http://localhost:8080/openidm/recon?_action=recon&mapping=systemCrestLdapUser_managedUser&waitForCompletion=true"
   {
     "_id": "f2fc8502-aeaa-4183-a9f8-2b54662d44b5-88",
     "state": "SUCCESS"
   }

   The reconciliation creates a managed user whose _id is the same as his OpenDJ _id, in this case, scarter.

6. Update Steven Carter's managed user entry, by modifying his telephone number:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request PATCH \
    --data '[
        {
            "operation" : "replace",
            "field" : "telephoneNumber",
            "value" : "555-555-5555"
        }
    ]' \
    "http://localhost:8080/openidm/managed/user/scarter"
   {
     "_id": "scarter",
     "_rev": "3",
     "userName": "scarter@example.com",
     "mail": "scarter@example.com",
     "displayName": "Steven.Carter",
     "telephoneNumber": "555-555-5555",
     "givenName": "Steven",
     "sn": "Carter",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }

7. The automatic synchronization mechanism between the managed user repository and OpenDJ propagates this change to the OpenDJ server. You can check this change by reading scarter's user entry in OpenDJ:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/system/scriptedcrest/users/scarter"
   {
     "_id": "scarter",
     "_rev": "000000006bf49bb2",
     "contactInformation": {
       "telephoneNumber": "555-555-5555"
     },
     "name": {
       "givenName": "Steven",
       "familyName": "Carter"
     },
     "displayName": "Steven.Carter"
   }

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

   $ curl \
    --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"}]
    }' \
    "http://localhost:8080/openidm/system/scriptedcrest/groups/group1"
   {
     "_id": "group1",
     "_rev": "00000000230d6f5b",
     "members": [
       {
         "displayName": "Steven.Carter",
         "_id": "scarter"
       }
     ],
     "displayName": "group1"
   }

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

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/system/scriptedcrest/users/scarter"
   {
     "_id": "scarter",
     "_rev": "000000006bf49bb2",
     "contactInformation": {
       "telephoneNumber": "555-555-5555"
     },
     "name": {
       "givenName": "Steven",
       "familyName": "Carter"
     },
     "displayName": "Steven.Carter",
     "groups": [
       {
         "_id": "group1"
       }
     ]
   }

10. Read the group entry to verify its members.

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request GET \
     "http://localhost:8080/openidm/system/scriptedcrest/groups/group1"
    {
      "_id": "group1",
      "_rev": "00000000230d6f5b",
      "members": [
        {
          "displayName": "Steven.Carter",
          "_id": "scarter"
        }
      ],
      "displayName": "group1"
    }

11. Reconcile the OpenDJ groups with the OpenIDM managed group repository:

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request POST \
     "http://localhost:8080/openidm/recon?_action=recon&mapping=systemCrestLdapGroup_managedGroup&waitForCompletion=true"
    {
      "_id": "f2fc8502-aeaa-4183-a9f8-2b54662d44b5-224",
      "state": "SUCCESS"
    }

12. Read the managed group to verify that the OpenDJ group has been and its members have been reconciled to the managed group repository:

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request GET \
     "http://localhost:8080/openidm/managed/group/group1"
    {
      "_id": "group1",
      "_rev": "1",
      "members": [
        {
          "displayName": "Steven.Carter",
          "_id": "scarter"
        }
      ],
      "displayName": "group1"
    }

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

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request DELETE \
     "http://localhost:8080/openidm/system/scriptedcrest/users/scarter"
    {
      "_id": "scarter",
      "_rev": "000000006bf49bb2",
      "contactInformation": {
        "telephoneNumber": "555-555-5555"
      },
      "name": {
        "givenName": "Steven",
        "familyName": "Carter"
      },
      "displayName": "Steven.Carter",
      "groups": [
        {
          "_id": "group1"
        }
      ]
    }
    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request DELETE \
     "http://localhost:8080/openidm/system/scriptedcrest/groups/group1"
    {
      "_id": "group1",
      "_rev": "00000000230d6f5b",
      "displayName": "group1"
    }
         

Run the commands in this procedure from the PowerShell command line. The continuation character used in the command is the back-tick (`).

1. Install, configure, and start the .NET connector server on the machine that is running an Active Directory Domain Controller or on a workstation on which the Microsoft Active Directory PowerShell module is installed.

   For instructions on installing the .NET connector server, see "Installing the .NET Connector Server" in the Integrator's Guide.

2. Configure OpenIDM to connect to the .NET connector server.

   To do so, copy the remote connector provisioner file from the openidm\samples\provisioners directory to your project's conf\ directory, and edit the file according to your configuration.

   PS C:\ cd \path\to\openidm
   PS C:\path\to\openidm cp samples\provisioners\provisioner.openicf.connectorinfoprovider.json conf

   For instructions on editing this file, see "Configuring OpenIDM to Connect to the .NET Connector Server" in the Integrator's Guide.

3. Download the PowerShell Connector Toolkit archive (mspowershell-connector-1.4.3.0.zip) from ForgeRock's BackStage site.

   Extract the archive and move the MsPowerShell.Connector.dll to the folder in which the connector server application (connectorserver.exe) is located.

4. Copy the PowerShell scripts from the samples\powershell2AD\tools directory, to the machine on which the connector server is installed.

   PS C:\path\to\openidm>dir samples\powershell2AD\tools
   Directory: C:\path\to\openidm\samples\powershell2AD\tools
   
   Mode             LastWriteTime   Length Name
   ----             -------------   ------ ----
   
    -----     11/15/2015  01:55 PM   2813 ADAuthenticate.ps1
    -----     11/15/2015  01:55 PM  10019 ADCreate.ps1
    -----     11/15/2015  01:55 PM   2530 ADDelete.ps1
    -----     11/15/2015  01:55 PM   2617 ADResolveUsername.ps1
    -----     11/15/2015  01:55 PM   7998 ADSchema.ps1
    -----     11/15/2015  01:55 PM   3706 ADSearch.ps1
    -----     11/15/2015  01:55 PM   4827 ADSync.ps1
    -----     11/15/2015  01:55 PM   2075 ADTest.ps1
    -----     11/15/2015  01:55 PM  10044 ADUpdate.ps1
   
   PS C:\path\to\openidm>

5. Copy the sample connector configuration for the PowerShell connector from the samples\provisioners directory to your project's conf directory.

   PS C:\ cd \path\to\openidm
   PS C:\ cp samples\provisioners\provisioner.openicf-adpowershell.json conf

   The following excerpt of the sample connector configuration shows the configuration properties:

     "configurationProperties" : {
       "AuthenticateScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADAuthenticate.ps1",
       "CreateScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADCreate.ps1",
       "DeleteScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADDelete.ps1",
       "ResolveUsernameScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADResolveUsername.ps1",
       "SchemaScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADSchema.ps1",
       "SearchScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADSearch.ps1",
       "SyncScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADSync.ps1",
       "TestScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADTest.ps1",
       "UpdateScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADUpdate.ps1",
       "VariablesPrefix" : "Connector",
       "QueryFilterType" : "AdPsModule",
       "ReloadScriptOnExecution" : true,
       "UseInterpretersPool" : true,
       "SubstituteUidAndNameInQueryFilter" : true,
       "UidAttributeName" : "ObjectGUID",
       "NameAttributeName" : "DistinguishedName",
       "PsModulesToImport" : [ "ActiveDirectory" ],
       "Host" : "",
       "Port" : null,
       "Login" : "",
       "Password" : null,
       "CustomProperties" : ["baseContext = CN=Users,DC=example,DC=com" ],
       "MinInterpretersPoolSize" : 1,
       "MaxInterpretersPoolSize" : 10
     },

   The sample connector configuration assumes that the scripts are located in C:/openidm/samples/powershell2AD/tools/. If you copied your scripts to a different location, or are using a different base context for search and synchronization operations such as DC=example,DC=org, adjust your connector configuration file accordingly.

   Note that the OpenICF framework requires the path to use forward slash characters and not the backslash characters that you would expect in a Windows path.

   The host, port, login and password of the machine on which Active Directory runs do not need to be specified here. By default the Active Directory cmdlets pick up the first available Domain Controller. In addition, the scripts are executed using the credentials of the .Net connector server.

   Note

   The "ReloadScriptOnExecution" property is set to true in this sample configuration. This setting causes script files to be reloaded each time the script is invoked. Having script files reloaded each time is suitable for debugging purposes. However, this property should be set to false in production environments, as the script reloading can have a negative performance impact.

   In addition, make sure that the value of the "connectorHostRef" property in the connector configuration file matches the value that you specified in the remote connector configuration file, in step 2 of this procedure. For example:

   "connectorHostRef" : "dotnet",

1. Test the connector configuration, and whether OpenIDM is able to connect to the .NET connector server with the following request.

   PS C:\ curl `
    --header "X-OpenIDM-Username: openidm-admin" `
    --header "X-OpenIDM-Password: openidm-admin" `
    --request POST `
    "http://localhost:8080/openidm/system?_action=test"
   [
     {
       "ok": true,
       "connectorRef": {
         "bundleVersion": "[1.4.2.0,1.5.0.0)",
         "bundleName": "MsPowerShell.Connector",
         "connectorName": "Org.ForgeRock.OpenICF.Connectors.MsPowerShell.MsPowerShellConnector"
       },
       "objectTypes": [
         "__ALL__",
         "group",
         "account"
       ],
       "config": "config/provisioner.openicf/adpowershell",
       "enabled": true,
       "name": "adpowershell"
     }
   ] 

2. Query the users in your Active Directory with the following request:

   PS C:\ curl `
    --header "X-OpenIDM-Username: openidm-admin" `
    --header "X-OpenIDM-Password: openidm-admin" `
    --request GET `
    "http://localhost:8080/openidm/system/adpowershell/account?_queryId=query-all-ids"
   {
     "remainingPagedResults": -1,
     "pagedResultsCookie": null,
     "resultCount": 1257,
     "result": [
       {
         "_id": "7c41496a-9898-4074-a537-bed696b6be92",
         "distinguishedName": "CN=Administrator,CN=Users,DC=example,DC=com"
       },
       {
         "_id": "f2e08a5c-473f-4798-a2d5-d5cc27c862a9",
         "distinguishedName": "CN=Guest,CN=Users,DC=example,DC=com"
       },
       {
         "_id": "99de98a3-c125-48dd-a7c2-e21f1488ab06",
         "distinguishedName": "CN=Ben Travis,CN=Users,DC=example,DC=com"
       },
       {
         "_id": "0f7394cc-c66a-404f-ad6d-38dbb4b6526d",
         "distinguishedName": "CN=Barbara Jensen,CN=Users,DC=example,DC=com"
       },
       {
         "_id": "3e6fa858-ed3a-4b58-9325-1fca144eb7c7",
         "distinguishedName": "CN=John Doe,CN=Users,DC=example,DC=com"
       },
       {
         "_id": "6feef4a0-b121-43dc-be68-a96703a49aba",
         "distinguishedName": "CN=Steven Carter,CN=Users,DC=example,DC=com"
       },
   ...

3. To return the complete record of a specific user, include the ID of the user in the URL. The following request returns the record for Steven Carter.

   PS C:\ curl `
    --header "X-OpenIDM-Username: openidm-admin" `
    --header "X-OpenIDM-Password: openidm-admin" `
    --request GET `
    "http://localhost:8080/openidm/system/adpowershell/account/6feef4a0-b121-43dc-be68-a96703a49aba"
   {
     "_id": "6feef4a0-b121-43dc-be68-a96703a49aba",
     "postalCode": null,
     "passwordNotRequired": false,
     "cn": "Steven Carter",
     "name": "Steven Carter",
     "trustedForDelegation": false,
     "uSNChanged": "47219",
     "manager": null,
     "objectGUID": "6feef4a0-b121-43dc-be68-a96703a49aba",
     "modifyTimeStamp": "11/27/2014 3:37:16 PM",
     "employeeNumber": null,
     "sn": "Carter",
     "userAccountControl": 512,
     "passwordNeverExpires": false,
     "displayName": "Steven Carter",
     "initials": null,
     "pwdLastSet": "130615726366949784",
     "scriptPath": null,
     "badPasswordTime": "0",
     "employeeID": null,
     "badPwdCount": "0",
     "accountExpirationDate": null,
     "userPrincipalName": "steve.carter@ad0.example.com",
     "sAMAccountName": "steve.carter",
     "mail": "steven.carter@example.com",
     "logonCount": "0",
     "cannotChangePassword": false,
     "division": null,
     "streetAddress": null,
     "allowReversiblePasswordEncryption": false,
     "description": null,
     "whenChanged": "11/27/2014 3:37:16 PM",
     "title": null,
     "lastLogon": "0",
     "company": null,
     "homeDirectory": null,
     "whenCreated": "6/23/2014 2:50:48 PM",
     "givenName": "Steven",
     "telephoneNumber": "555-2518",
     "homeDrive": null,
     "uSNCreated": "20912",
     "smartcardLogonRequired": false,
     "distinguishedName": "CN=Steven Carter,CN=Users,DC=example,DC=com",
     "createTimeStamp": "6/23/2014 2:50:48 PM",
     "department": null,
     "memberOf": [
       "CN=employees,DC=example,DC=com"
     ],
     "homePhone": null
   }

4. Test whether you can authenticate as one of the users in your Active Directory. The username that you specify here can be either an ObjectGUID, UPN, sAMAccountname or CN.

   $ PS C:\ curl `
    --header "X-OpenIDM-Username: openidm-admin" `
    --header "X-OpenIDM-Password: openidm-admin" `
    --request POST `
    "http://localhost:8080/openidm/system/adpowershell/account?_action=authenticate&username=Steven+Carter&password=Passw0rd"
   {
     "_id": "6feef4a0-b121-43dc-be68-a96703a49aba"
   }

   The request returns the ObjectGUID if the authentication is successful.

5. You can return the complete record for a specific user, using the query filter syntax described in "Constructing Queries" in the Integrator's Guide.

   The following query returns the record for the guest user.

   PS C:\ curl `
    --header "X-OpenIDM-Username: openidm-admin" `
    --header "X-OpenIDM-Password: openidm-admin" `
    --request GET `
    'http://localhost:8080/openidm/system/adpowershell/account?_queryFilter=cn+eq+"guest"'
   {
     "remainingPagedResults": -1,
     "pagedResultsCookie": null,
     "resultCount": 1,
     "result": [
       {
         "_id": "f2e08a5c-473f-4798-a2d5-d5cc27c862a9",
         "postalCode": null,
         "passwordNotRequired": true,
         "cn": "Guest",
         "name": "Guest",
         "trustedForDelegation": false,
         "uSNChanged": "8197",
         "manager": null,
         "objectGUID": "f2e08a5c-473f-4798-a2d5-d5cc27c862a9",
         "modifyTimeStamp": "6/9/2014 12:35:16 PM",
         "employeeNumber": null,
         "userAccountControl": 66082,
         "whenChanged": "6/9/2014 12:35:16 PM",
         "initials": null,
         "pwdLastSet": "0",
         "scriptPath": null,
         "badPasswordTime": "0",
         "employeeID": null,
         "badPwdCount": "0",
         "accountExpirationDate": null,
         "sAMAccountName": "Guest",
         "logonCount": "0",
         "cannotChangePassword": true,
         "division": null,
         "streetAddress": null,
         "allowReversiblePasswordEncryption": false,
         "description": "Built-in account for guest access to the computer/domain",
         "userPrincipalName": null,
         "title": null,
         "lastLogon": "0",
         "company": null,
         "homeDirectory": null,
         "whenCreated": "6/9/2014 12:35:16 PM",
         "givenName": null,
         "homeDrive": null,
         "uSNCreated": "8197",
         "smartcardLogonRequired": false,
         "distinguishedName": "CN=Guest,CN=Users,DC=example,DC=com",
         "createTimeStamp": "6/9/2014 12:35:16 PM",
         "department": null,
         "memberOf": [
           "CN=Guests,CN=Builtin,DC=example,DC=com"
         ],
         "homePhone": null,
         "displayName": null,
         "passwordNeverExpires": true
       }
     ]
   }

6. Test whether you are able to create a user on the Active Directory server by sending a POST request with the create action.

   The following request creates the user Jane Doe on the Active Directory server.

   PS C:\ curl `
    --header "X-OpenIDM-Username: openidm-admin" `
    --header "X-OpenIDM-Password: openidm-admin" `
    --header "Content-Type: application/json" `
    --request POST `
    --data "{
     \"distinguishedName\" : \"CN=Jane Doe,CN=Users,DC=example,DC=com\",
     \"sn\" : \"Doe\",
     \"cn\" : \"Jane Doe\",
     \"sAMAccountName\" : \"sample\",
     \"userPrincipalName\" : \"janedoe@example.com\",
     \"__ENABLE__\" : true,
     \"__PASSWORD__\" : \"Passw0rd\",
     \"telephoneNumber\" : \"0052-611-091\"
    }" `
    "http://localhost:8080/openidm/system/adpowershell/account?_action=create"
   {
     "_id": "42725210-8dce-4fdf-b0e0-393cf0377fdf",
     "title": null,
     "uSNCreated": "47244",
     "pwdLastSet": "130615892934093041",
     "cannotChangePassword": false,
     "telephoneNumber": "0052-611-091",
     "smartcardLogonRequired": false,
     "badPwdCount": "0",
     "department": null,
     "distinguishedName": "CN=Jane Doe,CN=Users,DC=example,DC=com",
     "badPasswordTime": "0",
     "employeeID": null,
     "cn": "Jane Doe",
     "division": null,
     "description": null,
     "userPrincipalName": "janedoe@example.com",
     "passwordNeverExpires": false,
     "company": null,
     "memberOf": [],
     "givenName": null,
     "streetAddress": null,
     "sn": "Doe",
     "initials": null,
     "logonCount": "0",
     "homeDirectory": null,
     "employeeNumber": null,
     "objectGUID": "42725210-8dce-4fdf-b0e0-393cf0377fdf",
     "manager": null,
     "lastLogon": "0",
     "trustedForDelegation": false,
     "scriptPath": null,
     "allowReversiblePasswordEncryption": false,
     "modifyTimeStamp": "11/27/2014 8:14:53 PM",
     "whenCreated": "11/27/2014 8:14:52 PM",
     "whenChanged": "11/27/2014 8:14:53 PM",
     "accountExpirationDate": null,
     "name": "Jane Doe",
     "displayName": null,
     "homeDrive": null,
     "passwordNotRequired": false,
     "createTimeStamp": "11/27/2014 8:14:52 PM",
     "uSNChanged": "47248",
     "sAMAccountName": "sample",
     "userAccountControl": 512,
     "homePhone": null,
     "postalCode": null
   }
        

7. Test whether you are able to update a user object on the Active Directory server by sending a PUT request with the complete object, and including the user ID in the URL.

   The following request updates user Jane Doe's entry, including her ID in the request. The update sends the same information that was sent in the create request, but adds an employeeNumber.

   PS C:\ curl `
    --header "X-OpenIDM-Username: openidm-admin" `
    --header "X-OpenIDM-Password: openidm-admin" `
    --header "Content-Type: application/json" `
    --header "If-Match: *" `
    --request PUT `
    --data "{
     \"distinguishedName\" : \"CN=Jane Doe,CN=Users,DC=example,DC=com\",
     \"sn\" : \"Doe\",
     \"cn\" : \"Jane Doe\",
     \"sAMAccountName\" : \"sample\",
     \"userPrincipalName\" : \"janedoe@example.com\",
     \"__ENABLE__\" : true,
     \"__PASSWORD__\" : \"Passw0rd\",
     \"telephoneNumber\" : \"0052-611-091\",
     \"employeeNumber\": \"567893\"
    }" `
    "http://localhost:8080/openidm/system/adpowershell/account/42725210-8dce-4fdf-b0e0-393cf0377fdf"
   {
     "_id": "42725210-8dce-4fdf-b0e0-393cf0377fdf",
     "title": null,
     "uSNCreated": "47244",
     "pwdLastSet": "130615906375709689",
     "cannotChangePassword": false,
     "telephoneNumber": "0052-611-091",
     "smartcardLogonRequired": false,
     "badPwdCount": "0",
     "department": null,
     "distinguishedName": "CN=Jane Doe,CN=Users,DC=example,DC=com",
     "badPasswordTime": "0",
     "employeeID": null,
     "cn": "Jane Doe",
     "division": null,
     "description": null,
     "userPrincipalName": "janedoe@example.com",
     "passwordNeverExpires": false,
     "company": null,
     "memberOf": [],
     "givenName": null,
     "streetAddress": null,
     "sn": "Doe",
     "initials": null,
     "logonCount": "0",
     "homeDirectory": null,
     "employeeNumber": "567893",
     "objectGUID": "42725210-8dce-4fdf-b0e0-393cf0377fdf",
     "manager": null,
     "lastLogon": "0",
     "trustedForDelegation": false,
     "scriptPath": null,
     "allowReversiblePasswordEncryption": false,
     "modifyTimeStamp": "11/27/2014 8:37:17 PM",
     "whenCreated": "11/27/2014 8:14:52 PM",
     "whenChanged": "11/27/2014 8:37:17 PM",
     "accountExpirationDate": null,
     "name": "Jane Doe",
     "displayName": null,
     "homeDrive": null,
     "passwordNotRequired": false,
     "createTimeStamp": "11/27/2014 8:14:52 PM",
     "uSNChanged": "47253",
     "sAMAccountName": "sample",
     "userAccountControl": 512,
     "homePhone": null,
     "postalCode": null
   }     

8. Test whether you are able to delete a user object on the Active Directory server by sending a DELETE request with the user ID in the URL.

   The following request deletes user Jane Doe's entry.

   PS C:\ curl `
    --header "X-OpenIDM-Username: openidm-admin" `
    --header "X-OpenIDM-Password: openidm-admin" `
    --request DELETE `
    "http://localhost:8080/openidm/system/adpowershell/account/42725210-8dce-4fdf-b0e0-393cf0377fdf"

   The response includes the complete user object that was deleted.

   You can you attempt to query the user object to confirm that it has been deleted.

   PS C:\ curl `
    --header "X-OpenIDM-Username: openidm-admin" `
    --header "X-OpenIDM-Password: openidm-admin" `
    --request GET `
    "http://localhost:8080/openidm/system/adpowershell/account/42725210-8dce-4fdf-b0e0-393cf0377fdf"
   {
     "message": "",
     "reason": "Not Found",
     "code": 404
   }

1. On the Windows host, create a directory for the PowerShell scripts.

   The sample connector configuration expects the scripts in the directory C:/openidm/samples/powershell2AzureAD/tools/. If you put them in a different location, adjust your connector configuration accordingly.

   PS C:\> mkdir -Path openidm\samples\powershell2AzureAD\azureADScripts
   
       Directory: C:\openidm\samples\powershell2AzureAD
   
   Mode                LastWriteTime     Length Name
   ----                -------------     ------ ----
   d----          5/4/2016   11:26 AM           azureADScripts
   
   PS C:\> 

2. Copy the PowerShell sample scripts from the OpenIDM instance on your UNIX/Linux host to the new directory on the remote Windows server.

   One way to do this is to run an scp client, such as pscp in your Windows terminal. The following command copies the PowerShell scripts from the OpenIDM installation to the Windows machine:

   PS C:\> cd openidm\samples\powershell2AzureAD\tools
   PS C:\> pscp -r username@openidm-host:path/to/openidm/samples/powershell2AzureAD/azureADScripts/*.ps .

   The following scripts should now be in the azureADScripts directory on your Windows system:

   PS C:\openidm\samples\powershell2AzureAD\azureADScripts> ls
   
       Directory: C:\openidm\samples\powershell2AzureAD\azureADScripts
   
   Mode                LastWriteTime     Length Name
   ----                -------------     ------ ----
   -a---         5/4/2016  11:26 AM       7258 AzureADCreate.ps1
   -a---         5/4/2016  11:26 AM       3208 AzureADDelete.ps1
   -a---         5/4/2016  11:26 AM       6952 AzureADSchema.ps1
   -a---         5/4/2016  11:26 AM       8149 AzureADSearch.ps1
   -a---         5/4/2016  11:26 AM       2465 AzureADTest.ps1
   -a---         5/4/2016  11:26 AM      10840 AzureADUpdate.ps1

   Note

   You need to set the execution policy, as Windows by default does not trust downloaded scripts. For more information, see the following article: Using the Set-ExecutionPolicy Cmdlet

   You can then run the Unblock-File cmdlet to allow OpenIDM to run the scripts on your Windows system. For more information, see the following article: Unblock-File.

3. On the Linux/UNIX machine on which OpenIDM is installed, navigate to the path/to/openidm/samples/powershell2AzureAD directory, and open the provisioner.openicf.connectorinfoprovider.json conf file.

4. Edit the remote connector server configuration file to match the settings of the remote .NET connector server.

   Change the port to 8760, and the password (key) that you configured for the .NET connector server.

   The following example assumes that the .NET connector server is running on the host 198.51.100.1, listening on the default port, and configured with a secret key of Passw0rd:

   {
      "remoteConnectorServers" :
         [
            {
               "name" : "dotnet",
               "host" : "198.51.100.1",
               "port" : 8760,
               "useSSL" : false,
               "timeout" : 0,
               "key" : "Passw0rd"
            }
         ]
   }

5. Open the sample Azure AD PowerShell connector configuration file, provisioner.openicf-azureadpowershell.json, and edit it to match your deployment. In particular, set the following properties in that file:

   "Host" : "198.51.100.1",
   "Port" : 8760,
   "Login" : "admin@example.onmicrosoft.com",
   "Password" : "Passw0rd",

   Host

   The hostname or IP address on which the .NET connector server is running.

   Port

   The port on which the .NET connector server is listening.

   Login

   The username of the administrative account you created for the Azure directory in the previous section.

   Password

   The password of the administrative account you created for the Azure directory in the previous section.

   If you have placed the PowerShell scripts in a directory other than the default (C:\openidm\samples\powershell2AzureAD\azureADScripts) you must also update those paths in the PowerShell connector configuration file.

6. Start OpenIDM with the PowerShell AzureAD sample configuration:

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

1. Test that the connector has been configured correctly and that the Azure AD resource can be reached:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "http://localhost:8080/openidm/system/azureadpowershell?_action=test"
   {
     "name": "azureadpowershell",
     "enabled": true,
     "config": "config/provisioner.openicf/azureadpowershell",
     "objectTypes": [
       "__ALL__",
       "account",
       "group"
     ],
     "connectorRef": {
       "bundleName": "MsPowerShell.Connector",
       "connectorName": "Org.ForgeRock.OpenICF.Connectors.MsPowerShell.MsPowerShellConnector",
       "bundleVersion": "[1.4.2.0,1.5.0.0)"
     },
     "displayName": "PowerShell Connector ",
     "ok": true
   }

   If you see no response from this connector test, review any changes that you made to the provisioner-openicf* files in your project's conf/ subdirectory. If you've made changes appropriate for your deployment, wait a couple of minutes and try again.

2. Query the IDs of the existing users in your Azure AD deployment:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/system/azureadpowershell/account?_queryId=query-all-ids"
   {
     "result": [ {
         "_id": "51560d42-e60e-49a8-855b-42b6eca35ca6",
         "UserPrincipalName": "admin@example.onmicrosoft.com"
       },
       {
         "_id": "5e63b42f-c93a-466f-af86-f0a8d00f2491",
         "UserPrincipalName": "scarter@example.onmicrosoft.com"
       } ],
   ...
   }

3. Use a query filter to return all details of all existing users in your Azure AD:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/system/azureadpowershell/account?_queryFilter=true"
   {
     "result": [
       {
         "_id": "51560d42-e60e-49a8-855b-42b6eca35ca6",
         "LiveId": "10033FFF96C5186D",
         "FirstName": "Barbara",
         "LastName": "Jensen",
         "UserPrincipalName": "admin@example.onmicrosoft.com",
         "AlternateEmailAddress" : [ "bjensen@example.com" ],
         "LastPasswordChangeTimestamp": "3/15/2016 11:02:19 AM",
         "DisplayName": "Barbara Jensen",
         "PasswordNeverExpires": false,
         "MobilePhone" : "+1 3602297105"
       },
       {
         "_id": "5e63b42f-c93a-466f-af86-f0a8d00f2491",
         "LiveId": "1003BFFD96A4CFBA",
         "FirstName": "Sam",
         "LastName": "Carter",
         "UserPrincipalName": "scarter@example.onmicrosoft.com"
         "AlternateEmailAddresses": [ "scarter@example.com" ],
         "LastPasswordChangeTimestamp": "3/7/2016 1:09:31 PM",
         "DisplayName": "Sam Carter",
         "PasswordNeverExpires": false,
         "MobilePhone" : "+1 3602297105"
       }
     ],
   ...}

4. Return details for a specific user account, by its _id

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/system/azureadpowershell/account/51560d42-e60e-49a8-855b-42b6eca35ca6"

5. Create a new user in Azure AD. Substitute the domain for your Azure AD deployment for example.onmicrosoft.com:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    --header "content-type: application/json" \
    --data '{
      "PasswordNeverExpires": false,
   	  "AlternateEmailAddresses": ["John.Bull@example.com"],
   	  "LastName": "Bull",
   	  "PreferredLanguage": "en-GB",
   	  "FirstName": "John",
   	  "UserPrincipalName": "Dev_John.Bull@example.onmicrosoft.com",
   	  "DisplayName": "John Bull"
    }' \
    "http://localhost:8080/openidm/system/azureadpowershell/account?_action=create"
   {
     "_id" : "d4aac947-2037-4f29-b0f5-d404fd99938c",
     "LiveId" : "10037FFE979FB2C1",
     "FirstName" : "John",
     "LastName" : "Bull",
     "UserPrincipalName" : "Dev_John.Bull@example.onmicrosoft.com",
     "AlternateEmailAddresses" : [ "John.Bull@example.com" ],
     "LastPasswordChangeTimestamp" : "5/5/2016 3:52:43 PM",
     "DisplayName" : "John Bull",
     "PasswordNeverExpires" : false,
     "PreferredLanguage" : "en-GB"
   }

   Rerun the same command. You should see the following error:

   {
     "code" : 500,
     "reason" : "Internal Server Error",
     "message" : "Operation CREATE failed with ConnectorException on system object:
         Dev_John.Bull@example.onmicrosoft.com"
   }

6. Update the user entry that you have just created with a patch request. Include the _id of the new user in the URL. Save that _id value for a later step.

   The following example updates the user's display name:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "if-match: *" \
    --header "content-type: application/json" \
    --request PATCH \
    --data '[
       {
          "operation": "replace",
          "field": "DisplayName",
          "value": "John P. Bull"
       }
    ]' \
    "http://localhost:8080/openidm/system/azureadpowershell/account/d4aac947-2037-4f29-b0f5-d404fd99938c"
   {
     "_id" : "d4aac947-2037-4f29-b0f5-d404fd99938c",
     "LiveId" : "10037FFE979FB2C1",
     "FirstName" : "John",
     "LastName" : "Bull",
     "UserPrincipalName" : "Dev_John.Bull@mikejangfr.onmicrosoft.com",
     "AlternateEmailAddresses" : [ "John.Bull@example.com" ],
     "LastPasswordChangeTimestamp" : "5/5/2016 3:52:43 PM",
     "DisplayName" : "John P. Bull",
     "PasswordNeverExpires" : false,
     "PreferredLanguage" : "en-GB"
   }

7. Now create a group:

   $ curl \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --header 'content-type: application/json' \
   --request POST \
   --data '{
         "DisplayName" : "Dev Testers group",
         "Description" : "Description of a Dev Group"
   }' \
   'http://localhost:8080/openidm/system/azureadpowershell/group?_action=create'
        {
     "_id" : "9091be74-f37e-408d-9198-2d2b5f4b4cdd",
     "Members" : [ ],
     "DisplayName" : "Dev Testers Group",
     "GroupType" : "Security",
     "Description" : "Description of a Dev Group",
     "objectId" : "9091be74-f37e-408d-9198-2d2b5f4b4cdd"
   }

8. Add your recently created user to this new group. Use the _id of that user, as the ObjectId. Use the _id of the newly created group in the endpoint:

   $ curl \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --header "Content-Type: application/json" \
   --header "If-Match: *" \
   --request PUT \
   --data '{
      "Members" : [
         {
            "ObjectId" : "d4aac947-2037-4f29-b0f5-d404fd99938c"
         }
      ]
   }' \
   "http://localhost:8080/openidm/system/azureadpowershell/group/9091be74-f37e-408d-9198-2d2b5f4b4cdd"
        {
      "_id" : "9091be74-f37e-408d-9198-2d2b5f4b4cdd",
      "Members" : [ {
         "ObjectId" : "d4aac947-2037-4f29-b0f5-d404fd99938c",
         "DisplayName" : "John P. Bull",
         "GroupMemberType" : "User",
         "EmailAddress" : "Dev_John.Bull@example.onmicrosoft.com"
      } ],
      "DisplayName" : "Testing Devs Group",
      "GroupType" : "Security",
      "Description" : "Description of a Dev Group",
      "objectId" : "9091be74-f37e-408d-9198-2d2b5f4b4cdd"
   }

9. Confirm the result, by the _id of the group:

   $ curl \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --request GET \
   "http://localhost:8080/openidm/system/azureadpowershell/group/9091be74-f37e-408d-9198-2d2b5f4b4cdd"

10. Update a label for the group. Use the same group _id:

    $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --header "If-Match: *" \
    --request PUT \
    --data '{
       "_id" : "9091be74-f37e-408d-9198-2d2b5f4b4cdd",
       "Description" : "Dev Masters Group",
       "Members" : [
          {
             "ObjectId" : "d4aac947-2037-4f29-b0f5-d404fd99938c",
             "DisplayName" : "John P. Bull",
             "GroupMemberType" : "User",
             "EmailAddress" : "Dev_John.Bull@example.onmicrosoft.com"
          }
       ],
       "DisplayName" : "Testing Devs Group",
       "GroupType" : "Security",
       "objectId" : "9091be74-f37e-408d-9198-2d2b5f4b4cdd"
    }' \
    "http://localhost:8080/openidm/system/azureadpowershell/group/9091be74-f37e-408d-9198-2d2b5f4b4cdd"

    You should see the new Description in the output.

11. Remove the user from the new group. Use the same group _id Note how the Members in the --data block, and the output, are blank:

    $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --header "If-Match: *" \
    --request PUT \
    --data '{
       "_id" : "9091be74-f37e-408d-9198-2d2b5f4b4cdd",
       "Description" : "Dev Masters Group",
       "Members" : [ ],
       "DisplayName" : "Testing Devs Group",
       "GroupType" : "Security",
       "objectId" : "9091be74-f37e-408d-9198-2d2b5f4b4cdd"
    }' \
    "http://localhost:8080/openidm/system/azureadpowershell/group/9091be74-f37e-408d-9198-2d2b5f4b4cdd"
         {
      "_id" : "9091be74-f37e-408d-9198-2d2b5f4b4cdd",
      "Members" : [ ],
      "DisplayName" : "Testing Devs Group",
      "GroupType" : "Security",
      "Description" : "Dev Masters Group",
      "objectId" : "9091be74-f37e-408d-9198-2d2b5f4b4cdd"
    }

12. Delete the user that you created earlier:

    $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request DELETE \
    "http://localhost:8080/openidm/system/azureadpowershell/account/d4aac947-2037-4f29-b0f5-d404fd99938c"

    To verify that the user was deleted, run the REST call to query-all-ids shown earlier in this section. The ID associated with that user should have been removed.

In the steps that follow, you'll run reconciliations to see what happens to that user in the OpenIDM data store.

1. Review the list of current managed users in the OpenIDM repository, filtered for the userName that starts with (sw) CEO:

   $ curl \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --request GET \
   "http://localhost:8080/openidm/managed/user?_queryFilter=userName+sw+'CEO'"

   Until you reconcile the Azure AD repository to OpenIDM, the output should be empty:

   {
      "result" : [ ],
      "resultCount" : 0,
      "pagedResultsCookie" : null,
      "totalPagedResultsPolicy" : "NONE",
      "totalPagedResults" : -1,
      "remainingPagedResults" : -1
   }

2. Run a reconciliation from Azure AD to OpenIDM:

   $ curl \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --request POST \
   "http://localhost:8080/openidm/recon?_action=recon&mapping=systemAzureadpowershellAccount_managedUser&waitForCompletion=true"
        
        {
      "_id" : "71811f1c-2ec0-47ae-ba47-d62c7094201b-1105",
      "state" : "SUCCESS"
   }

3. Now rerun the command to list of current managed users in the OpenIDM repository, filtered for the userName that starts with (sw) CEO:

   $ curl \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --request GET \
   "http://localhost:8080/openidm/managed/user?_queryFilter=userName+sw+'CEO'"
         {
      "result" : [ {
      "_id" : "3a012a60-19c2-4fb4-99cc-0bb82dc4588c",
      "_rev" : "1",
      "userName" : "CEO@example.onmicrosoft.com",
      "mail" : "CEO@example.onmicrosoft.com",
      "sn" : "Officer",
      "givenName" : "Chief",
      "accountStatus" : "active",
      "effectiveRoles" : [ ],
      "effectiveAssignments" : [ ]
      } ],
      "resultCount" : 1,
      "pagedResultsCookie" : null,
      "totalPagedResultsPolicy" : "NONE",
      "totalPagedResults" : -1,
      "remainingPagedResults" : -1
   }

4. Delete that CEO user from the Azure AD system, by the _id shown earlier when you searched that system:

   $ curl \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --request DELETE \
   "http://localhost:8080/openidm/system/azureadpowershell/account/3a012a60-19c2-4fb4-99cc-0bb82dc4588c"

   If successful, you'll see the data for the CEO user one last time.

5. Run a second reconciliation from the remote Azure AD repository to OpenIDM:

   $ curl \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --request POST \
   "http://localhost:8080/openidm/recon?_action=recon&mapping=systemAzureadpowershellAccount_managedUser&waitForCompletion=true"

6. Rerun the command to search the OpenIDM repository for a userName that starts with 'CEO' one more time, to confirm that user has been reconciled out of the OpenIDM repository:

   $ curl \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --request GET \
   "http://localhost:8080/openidm/managed/user?_queryFilter=userName+sw+'CEO'"

1. Create a BND file named activemq.bnd with the following contents:

   version=5.13.2
   Export-Package: *;version=${version}
   Bundle-Name: ActiveMQ :: Client
   Bundle-SymbolicName: org.apache.activemq
   Bundle-Version: ${version}

2. Run the following command to create the OSGi bundle archive file:

   $ java \
   -jar \
   bnd-1.50.0.jar \
   wrap \
   -properties \
   activemq.bnd \
   activemq-client-5.13.2.jar

3. Rename the activemq-client-5.13.2.bar file that appears to activemq-client-5.13.2-osgi.jar and copy it to the /path/to/openidm/bundle directory.

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 \
    --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"
      }' \
    "http://localhost:8080/openidm/managed/user?_action=create"
   {
     "_id": "837085ae-766e-417c-9b7e-c36eee4352a3",
     "_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 effectiveRoles or effectiveAssignments by default.

   Tip

   Create the user entry in the Admin UI:

   • Click Manage User > New User from the Dashboard.

2. Grant the Employee role to Felicitas's entry by sending a PATCH request to update her entry, and providing a pointer to the role ID:

   $ curl \
    --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/ad19979e-adbb-4d35-8320-6db50646b432"}
      }
    ]' \
    "http://localhost:8080/openidm/managed/user/837085ae-766e-417c-9b7e-c36eee4352a3"
   {
     "_id": "837085ae-766e-417c-9b7e-c36eee4352a3",
     "_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/ad19979e-adbb-4d35-8320-6db50646b432"
       }
     ],
     "effectiveAssignments": []
   }

   Tip

   Grant 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 granted to a user, either manually as in this example, or dynamically, through a script or condition. For more information about dynamically granted roles, see "Granting Roles Dynamically" in the Integrator's Guide.

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/managed/user?_queryFilter=/givenName+eq+'Felicitas'&_fields=_id,userName,roles,effectiveRoles"
   {
     "result" : [ {
       "_id" : "837085ae-766e-417c-9b7e-c36eee4352a3",
       "_rev" : "2",
       "userName" : "fdoe",
       "roles" : [ {
         "_ref": "managed/role/ad19979e-adbb-4d35-8320-6db50646b432",
         "_refProperties": {
           "_id": "4a42cd0b-d5d0-47e9-81e7-513aed74f6bc",
           "_rev": "1"
         } ],
       "effectiveRoles" : [ {
         "_ref" : "managed/role/ad19979e-adbb-4d35-8320-6db50646b432"
       } ]
     } ],
   ...
   }

   Note that Felicitas's roles and effectiveRoles attributes both show the reference to the Employee role ID.

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 \
    --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/b02d2531-5066-415e-bc90-31fe57e02322"}
      }
    ]' \
    "http://localhost:8080/openidm/managed/user/837085ae-766e-417c-9b7e-c36eee4352a3"
   {
     "_id": "837085ae-766e-417c-9b7e-c36eee4352a3",
     "_rev": "4",
     "mail": "fdoe@example.com",
     "sn": "Doe",
     "telephoneNumber": "555-1234",
     "userName": "fdoe",
     "givenName": "Felicitas",
     "description": "Felicitas Doe",
     "displayName": "fdoe",
     "accountStatus": "active",
     "effectiveRoles": [
       {
         "_ref": "managed/role/b02d2531-5066-415e-bc90-31fe57e02322"
       }
     ],
     "effectiveAssignments": []
   }

2. Now, try to delete the Contractor role:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request DELETE \
    "http://localhost:8080/openidm/managed/role/b02d2531-5066-415e-bc90-31fe57e02322"
   {
     "code": 409,
     "reason": "Conflict",
     "message": "Cannot delete a role that is currently granted"
   }

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

3. Remove the role from Felicitas's entry, either by using the Admin UI (as described previously), or by using a DELETE request, specifying the ID of the relationship that must be removed. Note that this is not the ID of the role. You will need to read Felicitas's roles property to obtain the relationship ID:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/managed/user?_queryFilter=/givenName+eq+'Felicitas'&_fields=_id,userName,roles,effectiveRoles"
   {
     "result" : [ {
       "_id" : "837085ae-766e-417c-9b7e-c36eee4352a3",
       "_rev" : "3",
       "userName" : "fdoe",
       "roles" : [ {
         "_ref": "managed/role/b02d2531-5066-415e-bc90-31fe57e02322",
         "_refProperties": {
           "_id": "93703eff-a7ef-4cf3-80b1-f86fa3607978",
           "_rev": "1"
         } ],
       "effectiveRoles" : [ {
         "_ref" : "managed/role/b02d2531-5066-415e-bc90-31fe57e02322"
       } ]
     } ],
   ...
   }

   In this example, the relationship ID is 93703eff-a7ef-4cf3-80b1-f86fa3607978.

   The following request removes the Contractor role from Felicitas's entry:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request DELETE \
    "http://localhost:8080/openidm/managed/user/837085ae-766e-417c-9b7e-c36eee4352a3/roles/93703eff-a7ef-4cf3-80b1-f86fa3607978"
   {
     "_ref": "managed/role/b02d2531-5066-415e-bc90-31fe57e02322",
     "_refProperties": {
       "_id": "93703eff-a7ef-4cf3-80b1-f86fa3607978",
       "_rev": "1"
     }
   }

4. Now that no users are granted the Contractor role, you can delete the role as follows:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request DELETE \
    "http://localhost:8080/openidm/managed/role/b02d2531-5066-415e-bc90-31fe57e02322"
   {
     "_id": "b02d2531-5066-415e-bc90-31fe57e02322",
     "_rev": "1",
     "name": "Contractor",
     "description": "Role granted to contract workers."
   }

   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 \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/managed/role?_queryFilter=true&_prettyPrint=true"
   {
     "result": [
       {
         "_id": "ad19979e-adbb-4d35-8320-6db50646b432",
         "_rev": "1",
         "name": "Employee",
         "description": "Role granted to workers on the payroll."
       }
     ],
     ...
   }

   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 the Server", 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 \
    --header "Content-type: application/json" \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    --data '{
      "name" : "Employee",
      "description": "Role granted to workers on the payroll."
    }' \
    "http://localhost:8080/openidm/managed/role?_action=create"
   {
     "_id" : "2902afd5-155a-49c0-9dd9-7e6bfcf1708a",
     "_rev" : "1",
     "name" : "Employee",
     "description" : "Role granted to workers on the payroll."
   }

   $ curl \
    --header "Content-type: application/json" \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    --data '{
      "name" : "Contractor",
      "description": "Role granted to contract workers."
    }' \
    "http://localhost:8080/openidm/managed/role?_action=create"
   {
     "_id": "e7f649ad-8013-4673-a52a-bdcac7483111",
     "_rev": "1",
     "name": "Contractor",
     "description": "Role granted to contract workers."
   }

   Note the IDs of these two roles because you will use them in the commands that follow.

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 \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --request POST \
      "http://localhost:8080/openidm/recon?_action=recon&mapping=systemLdapAccounts_managedUser&waitForCompletion=true"
     {
       "_id": "b5c535f8-5c1f-44dc-afa3-40d4f9984925-24",
       "state": "SUCCESS"
     }
          

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

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

2. Create the Employee and Contractor roles, and their assignments, either by using the Admin UI, or by using the REST interface, as described in the previous sample

   Note the IDs of the roles and assignments because you will use them in the commands that follow.

3. Reconcile the repository, as described in the previous sample.

1. Navigate to http://openam.example.com:8080/openam. Log into OpenAM as an administrator, with username amadmin, with the password you created during "Installing OpenAM for This Sample".

2. For the purpose of this sample, choose the default Top Level Realm.

3. Select Configure OAuth Provider.

4. Select Configure OpenID Connect. You should see the following window:

   

5. Accept the defaults. Choose the Create button in the Configure OpenID Connect window.

6. You'll see a window with the following message:

   OAuth2 Configured for the given realm
   
   Successfully configured OAuth2 for realm /.
   A policy was created on the realm for the authorization end point. The policy name
         is: OAuth2ProviderPolicy

   Select OK.

1. Navigate to http://openam.example.com:8080/openam/. Log into OpenAM as an administrator, with username amadmin, and the password you created during "Installing OpenAM for This Sample".

2. Choose the default Top Level Realm.

3. Choose Services > OAuth2 Provider.

4. Navigate to the Advanced tab, and enable Allow Clients to Skip Consent. For more information, see Allowing Clients to Skip Consent in the Access Management OAuth 2.0 Guide.

   Select Save Changes.

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 validation rules in this workflow require a managed user's manager entry to exist before that user can be created. You must therefore run three consecutive reconciliation operations:

   • The first reconciliation creates the superadmin user. This user has no manager entry, so is unaffected by the validation rules. Creation fails for the remaining users, because their manager does not yet exist.

   • The second reconciliation creates the 12 users who have the superadmin user as their manager. Creation fails for the remaining users, because they require the 12 manager users to exist before they can be created.

   • The third reconciliation creates the remaining 10 users, bringing the total number of users to 23.

   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. Run reconciliation twice more to create all the users in the repository.

4. Query the managed users that were created by the three reconciliation operations.

   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,
     ...
   }
        

   Your managed user repository should now contain 23 users. The default password of all the newly created users is Passw0rd.

5. 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).