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

2. Set up DS 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/sync-with-ldap/data/Example.ldif \
    --acceptLicense
   Validating parameters .....Done.
   Configuring Certificates .....Done.
   Configuring server .....Done.
   Importing data from /path/to/openidm/samples/sync-with-ldap/data/Example.ldif ........Done.
   Starting Directory Server ............Done.
   
   To see basic server status and configuration, you can launch /path/to/opendj/bin/status

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

1. Copy the external.email.json file from the samples/example-configurations/conf/ directory to the conf/ directory of this sample:

   $ cd /path/to/openidm
   $ cp samples/example-configurations/conf/external.email.json samples/sync-two-external-resources/conf
       

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

3. In the samples/sync-two-external-resources/script directory, edit the reconStats.js script to reflect the correct email details.

   Near the start of the file, locate the var email variable and update the values as required:

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

No external configuration is required for this sample. Before you start, prepare IDM as described in "Preparing IDM".

1. Start the server with the configuration of this sample:

   $ cd /path/to/openidm
        $ ./startup.sh -p samples/sync-two-external-resources

2. Examine the data files.

   The CSV files that simulate the two LDAP resources are located in the openidm/samples/sync-two-external-resources/data/ directory. Look at the contents of these files. Initially, the csvConnectorLDAPData.csv file contains one user and the csvConnectorADData.csv file contains no users.

3. Run a reconciliation operation to synchronize the contents of the simulated LDAP resource with the IDM repository.

   You can run the reconciliation in the Admin UI (Configure > Mappings, click systemLdapAccounts_managedUser, then click Reconcile) or over the command-line as follows:

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

   The reconciliation creates a managed user in the IDM repository. You do not need to run a second reconciliation to synchronize the AD resource. Implicit synchronization propagates any change made to managed users in the repository to the simulated AD resource.

   For more information about implicit synchronization, see "Types of Synchronization" in the Integrator's Guide.

4. Review the contents of the simulated AD resource (csvConnectorADData.csv):

   $ more openidm/samples/sync-two-external-resources/data/csvConnectorADData.csv
   "uid", "username", "password",        "firstname", "description", "email",              "lastname"
   "1",             , "initial_Passw0rd","Barbara",                , "bjensen@example.com","Jensen"

   This file should now contain the same user that was present in the csvConnectorLDAPData.csv file.

   Alternatively, you can list users in the AD resource with the following command:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/system/ad/account?_queryId=query-all-ids"
      {
     "result": [
       {
         "_id": "1",
         "name": "1"
       }
     ],
     ...
   }
       

5. Use the _id of the user to read the complete user record from the AD resource:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/system/ad/account/1"
   {
     "_id": "1",
     "firstname": "Barbara",
     "lastname": "Jensen",
     "email": [
       "bjensen@example.com"
     ],
     "name": "1"
   }

6. To verify that the sample is working, repeat the process.

   Set up a second user in the csvConnectorLDAPData.csv file. The following example shows how that file might appear with a second user (scarter):

   "uid","username","password",     "firstname","description",   "email",              "lastname"
   "1",  "bjensen", "TestPassw0rd2","Barbara",  "Created By CSV","bjensen@example.com","Jensen"
   "2",  "scarter", "Passw0rd",     "Steve",    "Created By CSV","scarter@example.com","Carter"

7. Rerun the reconciliation and query REST commands shown previously.

   The reconciliation operation creates the new user from the simulated LDAP resource in the IDM repository. An implicit synchronization operation then creates that user in the AD resource.

8. If you configured the reconciliation email summary at the beginning of this sample, you should have received an email that lists the details of the reconciliation operations.

1. Start IDM with the configuration for this sample:

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

2. The sample is configured to assign new workflow tasks to an admin account named async.admin. You will need to create this account:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
    "userName": "async.admin",
    "givenName": "async",
    "sn" : "admin",
    "password" : "Passw0rd",
    "displayName" : "async admin",
    "mail" : "async.admin@example.com",
    "authzRoles": [
       {"_ref": "repo/internal/role/openidm-admin"},
       {"_ref": "repo/internal/role/openidm-authorized"}
    ],
    "_id" : "asyncadmin"
    }' \
    "http://localhost:8080/openidm/managed/user?_action=create"
   {
     "_id":"asyncadmin",
     "_rev":"00000000e8f502db",
     "userName":"async.admin",
     "givenName":"async",
     "sn":"admin",
     "displayName":"async admin",
     "mail":"async.admin@example.com",
     "accountStatus":"active",
     "effectiveRoles":[],
     "effectiveAssignments":[]
   }

3. Run reconciliation over the REST interface:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "http://localhost:8080/openidm/recon?_action=recon&mapping=systemCsvfileAccounts_managedUser"
   {
     "_id": "98d7f3c5-684e-4ef0-b4f9-f2e816a339cf-32",
     "state": "ACTIVE"
   }

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

   This reconciliation launches a workflow that generates an approval process for each ABSENT user. The approval processes must be approved by an administrator before the workflow can continue.

4. Review the approval tasks launched by the reconciliation.

   • To review the tasks in the Admin UI, log into the Admin UI at https://localhost:8443/admin/ using an administrator account (either openidm-admin or async.admin will work) and select Manage > Tasks.

     You should see two task instances launched by the Managed User Approval Workflow.

   • To view the approval tasks over REST run the following command:

     $ curl \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --request GET \
      "http://localhost:8080/openidm/workflow/taskinstance?_queryId=query-all-ids"

     The request returns two task instances, each with a process ID (_id) and a process definition ID.

     {
        "result": [
           {
              "_id": "33",
              "_rev": "1",
              "activityInstanceVariables": {},
              "cachedElContext": null,
              "category": null,
              "createTime": "2018-01-22T13:10:15.538Z",
              "delegationState": null,
              "delegationStateString": null,
              "deleted": false,
              "description": null,
              "dueDate": null,
              "eventName": null,
              "executionId": "5",
              "name": "Evaluate request",
              "owner": null,
              "parentTaskId": null,
              "priority": 50,
              "processDefinitionId": "managedUserApproval:1:4",
              "processInstanceId": "5",
              "processVariables": {},
              "queryVariables": null,
              "revisionNext": 2,
              "suspended": false,
              "suspensionState": 1,
              "taskDefinitionKey": "evaluateRequest",
              "taskLocalVariables": {},
              "tenantId": "",
              "assignee": "async.admin"
           }, {
              "_id": "34",
              "_rev": "1",
              "activityInstanceVariables": {},
              "cachedElContext": null,
              "category": null,
              "createTime": "2018-01-22T13:10:15.538Z",
              "delegationState": null,
              "delegationStateString": null,
              "deleted": false,
              "description": null,
              "dueDate": null,
              "eventName": null,
              "executionId": "6",
              "name": "Evaluate request",
              "owner": null,
              "parentTaskId": null,
              "priority": 50,
              "processDefinitionId": "managedUserApproval:1:4",
              "processInstanceId": "6",
              "processVariables": {},
              "queryVariables": null,
              "revisionNext": 2,
              "suspended": false,
              "suspensionState": 1,
              "taskDefinitionKey": "evaluateRequest",
              "taskLocalVariables": {},
              "tenantId": "",
              "assignee": "async.admin"
           }
        ],
       ...
     }

5. Complete each approval task.

   • To complete the approval tasks using the UI, log into the Self-Service UI at https://localhost:8443/#login/ as user async.admin with password Passw0rd.

     You should see two Evaluate request tasks under My Tasks on the Dashboard.

     For each task, click Details, select Yes, and click Complete.

   • Alternatively, approve the requests over REST, by setting requestApproved to true for each task instance, and using the complete action. Specify the _id of each task in the URL.

     For example, to approve the first request:

     $ curl \
      --header "X-OpenIDM-Username: async.admin" \
      --header "X-OpenIDM-Password: Passw0rd" \
      --header "Content-Type: application/json" \
      --request POST \
      --data '{"requestApproved": "true"}' \
      "http://localhost:8080/openidm/workflow/taskinstance/33?_action=complete"
     {
       "Task action performed": "complete"
     }

     Repeat this command for each task ID.

6. When the requests have been approved, select Manage > User in the Admin UI to see the new users in the repository, or query the managed users over REST 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": "asyncadmin",
          "_rev": "00000000e8f502db"
       }, {
          "_id": "scarter",
          "_rev": "000000007e120780"
       }, {
          "_id": "bjensen",
          "_rev": "00000000d9390751"
       }
     ],
    ...
   }

1. Log in to the Google Apps Developers Console (at https://console.developers.google.com/start) and update your project or create a new project for IDM.

2. Enable the following APIs for your IDM project:

   • Admin SDK API

   • Enterprise License Manager API

3. Set up an OAuth2 Client ID.

   The Google Apps connector uses OAuth2 to authorize the connection to the Google service. Set up an OAuth2 Client ID as follows:

   1. In the Google Apps Developers Console, select Credentials > New Credentials > OAuth Client ID.

   2. Click Configure Consent Screen and enter a Product Name.

      This is the name that will be shown for all applications registered in this project.

      For the purposes of this example, we use the Product Name OpenIDM.

      Click Save.

   3. Select Credentials > OAuth Client ID > Web application.

      Under Authorized redirect URIs, enter the callback URL (the URL at which your clients will access your application). The default IDM callback URL is https://localhost:8443/admin/oauth.html. Click Create to set up the callback URL.

      Click Create again to set up the client ID.

      This step generates an OAuth Client ID and Client, similar to the following:

      

      Copy and paste these values into a text file as you will need them when you configure the Google Apps connector.

1. To configure the connector, start IDM with the Google Apps sample configuration:

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

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

   This URL reflects the host on which IDM is installed and corresponds to the callback URL that you specified in the previous section. The URL must be included in the list of Authorized redirect URIs for your project.

3. Select Configure > Connectors and click on the Google Apps connector.

4. On the Details tab, set the Enabled field to True.

5. Enter the Oauth2 Client ID and Client Secret that you obtained in the previous section.

6. Click Save Connector Changes.

7. You are redirected to Google's Login page.

   When you have logged in, Google requests that you allow access from your project, in this case, IDM.

   

   Click Allow.

   If you click Deny here, you will need to return to the Connector Configuration > Details tab in the Admin UI and save your changes again.

   When you allow access, you are redirected to the Connectors page in the Admin UI, where the Google Apps Connector should now be Active.

   

1. Create a user entry on your Google resource, over REST.

   When you create resources for Google, note that the equals (=) character cannot be used in any attribute value.

   The following command creates an entry for user Sam Carter:

   $  curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
     "__NAME__": "samcarter@example.com",
     "__PASSWORD__"  : "password",
     "givenName" : "Sam",
     "familyName": "Carter",
     "agreedToTerms": true,
     "changePasswordAtNextLogin" : false
    }' \
    "http://localhost:8080/openidm/system/google/__ACCOUNT__?_action=create"
   {
     "_id": "103567435255251233551",
     "_rev": "\"iwpzoDgSq9BJw-XzORg0bILYPVc/LWHPMXXG8M0cjQAPITM95Y636cM\"",
     "orgUnitPath": "/",
     "isAdmin": false,
     "fullName": "Sam Carter",
     "customerId": "C02rsqddz",
     "relations": null,
     "nonEditableAliases": null,
     "suspensionReason": null,
     "includeInGlobalAddressList": true,
     "givenName": "Sam",
     "addresses": null,
     "isDelegatedAdmin": false,
     "changePasswordAtNextLogin": false,
     "isMailboxSetup": true,
     "__NAME__": "samcarter@example.com",
     "agreedToTerms": true,
     "externalIds": null,
     "ipWhitelisted": false,
     "aliases": null,
     "lastLoginTime": [
       "1970-01-01T00:00:00.000Z"
     ],
     "organizations": null,
     "suspended": false,
     "deletionTime": null,
     "familyName": "Carter",
     "ims": null,
     "creationTime": [
       "2016-02-02T12:52:30.000Z"
     ],
     "thumbnailPhotoUrl": null,
     "emails": [
       {
         "address": "samcarter@example.com",
         "primary": true
       }
     ],
     "phones": null
   }

   Note the ID of the new user (103567435255251233551 in this example). You will need this ID for the update commands in this section.

2. Reconcile the Google resource with the managed user repository.

   This step should create the new user, Sam Carter (and any other users in your Google resource) in the managed user repository.

   To run reconciliation follow these steps:

   1. In the Admin UI, select Configure > Mappings.

   2. Click on the sourceGoogle__ACCOUNT___managedUser mapping, and click Reconcile.

   3. Select Manage > User and verify that the user Sam Carter has been created in the repository.

3. Update Sam Carter's phone number in your Google resource by sending a PUT request with the updated data, and specifying the user _id in the request:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request PUT \
    --header "If-Match : *" \
    --data '{
     "__NAME__": "samcarter@example.com",
     "__PASSWORD__"  : "password",
     "givenName" : "Sam",
     "familyName": "Carter",
     "agreedToTerms": true,
     "changePasswordAtNextLogin" : false,
     "phones" :
      [
       {
        "value": "1234567890",
        "type": "home"
       },
       {
        "value": "0987654321",
        "type":"work"
       }
      ]
     }' \
    "http://localhost:8080/openidm/system/google/__ACCOUNT__/103567435255251233551"
   {
     "_id": "103567435255251233551",
     "_rev": "\"iwpzoDgSq9BJw-XzORg0bILYPVc/vfSJgHt-STUUto4lM_4ESO9izR4\"",
   ...
    "emails": [
       {
         "address": "samcarter@example.com",
         "primary": true
       }
     ],
     "phones": [
       {
         "value": "1234567890",
         "type": "home"
       },
       {
         "value": "0987654321",
         "type": "work"
       }
     ]
   }
   

4. Read Sam Carter's entry from your Google resource by including his _id in the URL:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/system/google/__ACCOUNT__/103567435255251233551"
   {
     "_id": "103567435255251233551",
     "__NAME__": "samcarter@example.com",
   ...
    "phones": [
       {
         "value": "1234567890",
         "type": "home"
       },
       {
         "value": "0987654321",
         "type": "work"
       }
     ]
   }

5. Create a group entry on your Google resource:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
     "__NAME__": "testGroup@example.com",
     "__DESCRIPTION__": "Group used for google-connector sample.",
     "name": "TestGroup"
    }' \
    "http://localhost:8080/openidm/system/google/__GROUP__?_action=create"
    
   {
     "_id": "00meukdy40gpg98",
     "_rev": "\"iwpzoDgSq9BJw-XzORg0bILYPVc/LLhHx2plMJPKeY1-h6eX_OVDi4c\"",
     "adminCreated": true,
     "__NAME__": "testgroup@example.com",
     "aliases": null,
     "nonEditableAliases": null,
     "__DESCRIPTION__": "Group used for google-connector sample.",
     "name": "TestGroup",
     "directMembersCount": 0
   }

6. Add Sam Carter to the test group you have just created. Include the Member endpoint, and Sam Carter's _id in the URL. Specify the _id of the group you created as the value of the groupKey in the JSON payload:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
     "groupKey" : "00meukdy40gpg98",
     "role": "MEMBER",
     "__NAME__": "samcarter@example.com",
     "email": "samcarter@example.com",
     "type": "MEMBER"
    }' \
    "http://localhost:8080/openidm/system/google/Member/103567435255251233551"
   {
     "_id": "00meukdy40gpg98/samcarter@example.com",
     "_rev": "\"iwpzoDgSq9BJw-XzORg0bILYPVc/CPNpkRnowkGWRvNQvUK9ev6gQ90\"",
     "__NAME__": "00meukdy40gpg98/samcarter@example.com",
     "role": "MEMBER",
     "email": "samcarter@example.com",
     "type": "USER",
     "groupKey": "103567435255251233551"
   }

7. Read the group entry by specifying the group _id in the request URL. Notice that the group has one member ("directMembersCount": 1).

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/system/google/__GROUP__/00meukdy40gpg98"
    
   {
     "_id": "00meukdy40gpg98",
     "_rev": "\"iwpzoDgSq9BJw-XzORg0bILYPVc/chUdq5m5_cycV2G4sdl7ZKAF75A\"",
     "adminCreated": true,
     "__NAME__": "testgroup@example.com",
     "aliases": null,
     "nonEditableAliases": [
       "testGroup@example.test-google-a.com"
     ],
     "__DESCRIPTION__": "Group used for google-connector sample.",
     "name": "TestGroup",
     "directMembersCount": 1
   }

8. Delete the group entry.

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request DELETE \
    "http://localhost:8080/openidm/system/google/__GROUP__/00meukdy40gpg98"
   {
     "_id": "00meukdy40gpg98",
     "_rev": "\"iwpzoDgSq9BJw-XzORg0bILYPVc/chUdq5m5_cycV2G4sdl7ZKAF75A\"",
     "adminCreated": true,
     "__NAME__": "testgroup@example.com",
     "aliases": null,
     "nonEditableAliases": [
       "testGroup@example.com.test-google-a.com"
     ],
     "__DESCRIPTION__": "Group used for google-connector sample.",
     "name": "TestGroup",
     "directMembersCount": 1
   }

   The delete request returns the complete group object.

9. Delete Sam Carter, to return your Google resource to its original state.

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request DELETE \
    "http://localhost:8080/openidm/system/google/__ACCOUNT__/103567435255251233551"
   {
     "_id": "103567435255251233551",
     "_rev": "\"iwpzoDgSq9BJw-XzORg0bILYPVc/ah6xBLujMAHieSWSisPa1CV6T3Q\"",
     "orgUnitPath": "/",
     "isAdmin": false,
     "fullName": "Sam Carter",
     "customerId": "C02rsqddz",
     "relations": null,
     "nonEditableAliases": [
       "samcarter@example.com.test-google-a.com"
     ],
     "suspensionReason": null,
     "includeInGlobalAddressList": true,
     "givenName": "Sam",
     "addresses": null,
     "isDelegatedAdmin": false,
     "changePasswordAtNextLogin": false,
     "isMailboxSetup": true,
     "__NAME__": "samcarter@example.com",
     "agreedToTerms": true,
     "externalIds": null,
     "ipWhitelisted": false,
     "aliases": null,
     "lastLoginTime": [
       "1970-01-01T00:00:00.000Z"
     ],
     "organizations": null,
     "suspended": false,
     "deletionTime": null,
     "familyName": "Carter",
     "ims": null,
     "creationTime": [
       "2016-02-02T12:52:30.000Z"
     ],
     "thumbnailPhotoUrl": null,
     "emails": [
       {
         "address": "samcarter@example.com",
         "primary": true
       }
     ],
     "phones": [
       {
         "value": "1234567890",
         "type": "home"
       },
       {
         "value": "0987654321",
         "type": "work"
       }
     ]
   }

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.

   The Resources tab shows the Salesforce connector, which is currently disabled.

2. Enable the Salesforce connector by completing the authentication details as follows. You will need the Consumer Key and Consumer Secret that you obtained in the previous section.

   • Select the Salesforce connector and select Enable to enable the connector.

   • Under Base Connector Details select Sandbox (for the purposes of testing the sample) and enter the Connector Key and Secret that you obtained in the previous section.

   • You can leave the remaining default configuration. Click Save to update the connector configuration.

   • The connector now attempts to access your Salesforce organization.

     Enter your Salesforce login credentials.

     On the permission request screen click Allow, to enable IDM to access your Salesforce Connected App.

     Note

     In the current IDM release, an issue is occasionally seen where the system appears to time out while retrieving the refresh token from Salesforce, at this stage. If this happens, refresh your browser and attempt the connector setup again.

     On the Resources tab, your Salesforce Connector should now be Active.

3. To test reconciliation, select Configure > Mappings.

   There are two configured mappings, one from Salesforce to the IDM repository (managed/user) and one from the repository to Salesforce.

4. Select Reconcile on the first mapping.

   The reconciliation operation creates the users that were present in your Salesforce organization in the IDM repository.

5. Retrieve the users in the repository by selecting Manage > User.

   The repository should now contain all the users from your Salesforce organization.

6. To test the second mapping (from IDM to Salesforce), update any user in the repository.

   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, check the updated user record in Salesforce.

Before you start, you will need the Consumer Key and Consumer Secret that you obtained in the previous section.

1. Obtain the refresh token from salesforce.com by pointing your browser to the following URL:

   SALESFORCE_URL/services/oauth2/authorize?response_type=code&client_id=CONSUMER_KEY&redirect_uri=REDIRECT_URI&scope=id+api+refresh_token

   Where:

   • SALESFORCE_URL is one of the following:

     • https://login.salesforce.com

     • https://test.salesforce.com

     • A custom Salesforce MyDomain URL, such as:

       https://ic-example-com--SUP1.cs21.my.salesforce.com

   • CONSUMER_KEY is the Consumer Key associated with the Connected App that you created within your Salesforce organization.

   • REDIRECT_URI corresponds to the IDM /admin/oauth.html page. This URI must match the Redirect URI specified within your Salesforce Connect App configuration, for example:

     https://localhost:8443/admin/oauth.html

     or

     http://localhost:8080/admin/oauth.html

2. You are redirected to Salesforce, and prompted to give this application access to your Salesforce account. When you have given consent, you should receive a response URL that looks similar to the following:

   https://localhost:8443/admin/index.html#connectors/edit//&code=aPrxJZTK7Rs03PU634VK8Jn9o_U3ZY1ERxM7IiklF...

   The &code part of this URL is an authorization code, that you need for the following step.

   Caution

   Note that this authorization code expires after 10 minutes. If you do not complete the OAuth flow within that time, you will need to start this process again.

3. Copy the authorization code from the response URL and use it as the value of the code parameter in the following REST call. The consumer-key, redirect-uri, and SALESFORCE_URL must match what you used in the first step of this procedure:

   $  curl \
    --verbose \
    --data "grant_type=authorization_code" \
    --data "client_id=consumer-key" \
    --data "client_secret=consumer-secret" \
    --data "redirect_uri=https://localhost:8443/admin/oauth.html" \
    --data "code=access-token-code" \
    "SALESFORCE_URL/services/oauth2/token"
   {
     "access_token": "00DS0000003K4fU!AQMAQOzEU.8tCjg8Wk79yKPKCtrtaszX5jrHtoT4NBpJ8x2NFZGjg3PNuc0TWq0EgiGS_mVkfg5f4pVN5...",
     "signature": "2uREX1lseXdg3Vng/2+Hrlo/KHOWYoim+poj74wKFtw=",
     "refresh_token": "5Aep861KIwKdekr90I4iHdtDgWwRoG7O_6uHrgJ.yVtMS0UaGxRqE6WFM77W7wCV4muVMgdqKjuWI2i5S6sjN2X",
     "token_type": "Bearer",
     "instance_url": "https://example-com.cs1.my.salesforce.com",
     "scope": "id api refresh_token",
     "issued_at": "1417182949781",
     "id": "https://login.salesforce.com/id/00DS0000003K4fUMAS/00530000009hWLcAAM"
   }

   The output includes an access_token and a refresh_token. You will need the refresh_token in the following step.

4. Edit the configurationProperties in your Salesforce connector configuration file (openidm/samples/sync-with-salesforce/conf/provisioner.salesforce-salesforce.json) to include your Consumer Key (clientID), Consumer Secret (clientSecret), refresh token, and your Salesforce login URL.

   In addition, set the instanceUrl to the value returned in the previous step, and set the enabled property to true.

   The relevant excerpts of the provisioner.salesforce-salesforce.json file are as follows:

   {
       "name" : "salesforce",
       "enabled" : true,
   ...
       "configurationProperties" : {
           "connectTimeout" : 120000,
           "loginUrl" : https://login.salesforce.com/services/oauth2/token,
           "idleCheckInterval" : 10000,
           "refreshToken" : "5Aep861KIwKdekr90I4iHdtDgWwRoG7O_6uHrgJ.yVtMS0UaGxRqE6WFM...",
           "clientSecret" : "4850xxxxxxxxxxxxx425",
           "clientId" : "3MVG98dostKihXN7Is8Q0g5q1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxP...",
           "instanceUrl" : "https://example-com.cs1.my.salesforce.com",
           "version" : 29
       }
   ... 

5. Check that your connector configuration is correct by testing 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?_action=test"
   [
     {
       "ok": true,
       "connectorRef": {
         "bundleVersion": "6.0.0",
         "systemType": "provisioner.salesforce",
         "displayName": "Salesforce Connector",
         "bundleName": "org.forgerock.openidm.salesforce",
         "connectorName": "org.forgerock.openidm.salesforce.Salesforce"
       },
       "objectTypes": [
         "User",
         "PermissionSet",
         "PermissionSetAssignment",
         "Profile",
         "PermissionSetLicenseAssign",
         "Organization",
         "PermissionSetLicense",
         "Group",
         "GroupMember"
       ],
       "config": "config/provisioner.salesforce/salesforce",
       "enabled": true,
       "name": "salesforce"
     }
   ]
        

The mapping configuration file (sync.json) for this sample includes two mappings, sourceSalesforceUser_managedUser, which synchronizes users from the Salesforce with the IDM repository, and managedUser_sourceSalesforceUser, which synchronizes changes from the repository to Salesforce.

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=sourceSalesforceUser_managedUser&waitForCompletion=true"
   {
     "state": "SUCCESS",
     "_id": "8a6281ef-6faf-43dd-af5c-3a842b38c468"
   }

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

2. Retrieve the managed users in the repository:

   $ 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": "180c6686-b098-460a-a246-4e03fa0b8eb2",
         "_rev": "00000000cfe1fccf"
       },
       {
         "_id": "d0c25a0c-f7e6-4249-9c81-e546728f5bdd",
         "_rev": "000000000828e760"
       },
       {
         "_id": "25181ab3-0d40-4f80-96d6-d620eef7b6da",
         "_rev": "0000000038b6e342"
       }
     ],
     "resultCount": 3,
     "pagedResultsCookie": null,
     "totalPagedResultsPolicy": "NONE",
     "totalPagedResults": -1,
     "remainingPagedResults": -1
   }

   The output shows that the users in the Salesforce data store have been created in the repository.

1. Start IDM with the configuration for the Kerberos sample:

   $ cd /path/to/openidm

   $ startup.sh -p samples/sync-with-kerberos

2. Test that your connector configuration is correct and that IDM can reach your Kerberos server, with the following command:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "http://localhost:8080/openidm/system?_action=test"
   [
     {
       "name": "kerberos",
       "enabled": true,
       "config": "config/provisioner.openicf/kerberos",
       "objectTypes": [
         "__ALL__",
         "account"
       ],
       "connectorRef": {
         "bundleName": "org.forgerock.openicf.connectors.kerberos-connector",
         "connectorName": "org.forgerock.openicf.connectors.kerberos.KerberosConnector",
         "bundleVersion": "[1.4.0.0,1.6.0.0)"
       },
       "displayName": "Kerberos Connector",
       "ok": true
     }
   ]

   If the command returns "ok": true, as in the preceding output, your configuration is correct and you can continue with the sample.

3. Retrieve a list of the existing user principals in the Kerberos database:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/system/kerberos/account?_queryId=query-all-ids"
   {
     "result": [
       {
         "_id": "K/M@EXAMPLE.COM",
         "principal": "K/M@EXAMPLE.COM"
       },
       {
         "_id": "kadmin/admin@EXAMPLE.COM",
         "principal": "kadmin/admin@EXAMPLE.COM"
       },
       {
         "_id": "kadmin/changepw@EXAMPLE.COM",
         "principal": "kadmin/changepw@EXAMPLE.COM"
       },
       {
         "_id": "kadmin/krb1.example.com@EXAMPLE.COM",
         "principal": "kadmin/krb1.example.com@EXAMPLE.COM"
       },
       {
         "_id": "kiprop/krb1.example.com@EXAMPLE.COM",
         "principal": "kiprop/krb1.example.com@EXAMPLE.COM"
       },
       {
         "_id": "krbtgt/EXAMPLE.COM@EXAMPLE.COM",
         "principal": "krbtgt/EXAMPLE.COM@EXAMPLE.COM"
       },
       {
         "_id": "openidm/admin@EXAMPLE.COM",
         "principal": "openidm/admin@EXAMPLE.COM"
       }
     ],
     ...
   }

4. Create two new managed users, either over REST or by using the Admin UI.

   The following command creates users bjensen and scarter over REST. To create similar users by using the Admin UI, select Managed > User and click New User:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-type: application/json" \
    --request POST \
    --data '{
     "userName": "bjensen",
     "givenName": "Barbara",
     "sn" : "Jensen",
     "password" : "Passw0rd",
     "displayName" : "Barbara Jensen",
     "mail" : "bjensen@example.com"
    }' \
    "http://localhost:8080/openidm/managed/user?_action=create"
   {
     "_id": "ce3d9b8f-1d15-4950-82c1-f87596aadcb6",
     "_rev": "00000000792afa08",
     "userName": "bjensen",
     "givenName": "Barbara",
     "sn": "Jensen",
     "displayName": "Barbara Jensen",
     "mail": "bjensen@example.com",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }
   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-type: application/json" \
    --request POST \
    --data '{
     "userName": "scarter",
     "givenName": "Steven",
     "sn" : "Carter",
     "password" : "Passw0rd",
     "displayName" : "Steven Carter",
     "mail" : "scarter@example.com"
    }' \
    "http://localhost:8080/openidm/managed/user?_action=create"
   {
     "_id": "a204ca60-b0fc-42f8-bf93-65bb30131361",
     "_rev": "000000004121fb7e",
     "userName": "scarter",
     "givenName": "Steven",
     "sn": "Carter",
     "displayName": "Steven Carter",
     "mail": "scarter@example.com",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }

5. Run a reconciliation operation between the managed user repository and the Kerberos database to create the new users bjensen and scarter in Kerberos. You can run the reconciliation over REST, or using the Admin UI.

   The following command creates runs the reconciliation over REST:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "http://localhost:8080/openidm/recon?_action=recon&mapping=managedUser_systemKerberos"
   {
     "_id": "862ab9ba-d1d9-4058-b6bc-a23a94b68776-234",
     "state": "ACTIVE"
   }

   To run the reconciliation by using the Admin UI, select Configure > Mappings, click on the managedUser_systemKerberos mapping, and click Reconcile.

6. Retrieve the list of Kerberos user principals again. You should now see bjensen and scarter in this list:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/system/kerberos/account?_queryId=query-all-ids"
   {
     "result": [
       {
         "_id": "bjensen@EXAMPLE.COM",
         "principal": "bjensen@EXAMPLE.COM"
       },
       {
         "_id": "scarter@EXAMPLE.COM",
         "principal": "scarter@EXAMPLE.COM"
       },
       ...
       {
         "_id": "openidm/admin@EXAMPLE.COM",
         "principal": "openidm/admin@EXAMPLE.COM"
       }
     ],
     ...
   }

7. Retrieve bjensen's complete user principal from the Kerberos server:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/system/kerberos/account/bjensen@EXAMPLE.COM"
   {
     "_id": "bjensen@EXAMPLE.COM",
     "lastFailedAuthentication": "[never]",
     "passwordExpiration": "[none]",
     "lastSuccessfulAuthentication": "[never]",
     "maximumTicketLife": "0 days 10:00:00",
     "lastModified": "Tue May 24 04:05:45 EDT 2016 (openidm/admin@EXAMPLE.COM)",
     "policy": "user [does not exist]",
     "expirationDate": "[never]",
     "failedPasswordAttempts": "0",
     "maximumRenewableLife": "7 days 00:00:00",
     "principal": "bjensen@EXAMPLE.COM",
     "lastPasswordChange": "Tue May 24 04:05:45 EDT 2016"
   }

   Note the default values for properties such as maximumRenewableLife. These values are set in your connector configuration. For more information, see "Configuring the Kerberos Connector" in the Connector Reference.

   To perform this step in the Admin UI, select Manage > User, click bjensen's entry, and click the Linked Systems tab to display her corresponding entry on the Kerberos server.

8. Delete the managed user bjensen by specifying her managed object ID in the DELETE request.

   First, obtain her ID by querying for her userName:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/managed/user?_queryFilter=userName+eq+'bjensen'"
   {
     "result": [
       {
         "_id": "ce3d9b8f-1d15-4950-82c1-f87596aadcb6",
         "_rev": "00000000a92657c7",
         "userName": "bjensen",
         "givenName": "Barbara",
         "sn": "Jensen",
         "displayName": "Barbara Jensen",
         "mail": "bjensen@example.com",
         "accountStatus": "active",
         "effectiveRoles": [],
         "effectiveAssignments": []
       }
     ],
     ...
   }

   Now delete the user with ID ce3d9b8f-1d15-4950-82c1-f87596aadcb6. This ID will obviously be different in your example.

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request DELETE \
    "http://localhost:8080/openidm/managed/user/ce3d9b8f-1d15-4950-82c1-f87596aadcb6"
   {
     "_id": "ce3d9b8f-1d15-4950-82c1-f87596aadcb6",
     "_rev": "00000000a92657c7",
     "userName": "bjensen",
     "givenName": "Barbara",
     "sn": "Jensen",
     "displayName": "Barbara Jensen",
     "mail": "bjensen@example.com",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }

   To delete bjensen's managed user entry by using the Admin UI, select Manage > User, click on bjensen's entry, select the checkbox next to her entry, and click Delete Selected.

9. Reconcile the managed user repository and the Kerberos database again:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "http://localhost:8080/openidm/recon?_action=recon&mapping=managedUser_systemKerberos"
   {
     "_id": "862ab9ba-d1d9-4058-b6bc-a23a94b68776-584",
     "state": "ACTIVE"
   }

10. Retrieve the list of Kerberos user principals again. The Kerberos principal for bjensen should have been been removed from the list:

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request GET \
     "http://localhost:8080/openidm/system/kerberos/account?_queryId=query-all-ids"
    {
      "result": [
        {
          "_id": "K/M@EXAMPLE.COM",
          "principal": "K/M@EXAMPLE.COM"
        },
        {
          "_id": "kadmin/admin@EXAMPLE.COM",
          "principal": "kadmin/admin@EXAMPLE.COM"
        },
        {
          "_id": "kadmin/changepw@EXAMPLE.COM",
          "principal": "kadmin/changepw@EXAMPLE.COM"
        },
        {
          "_id": "kadmin/krb1.example.com@EXAMPLE.COM",
          "principal": "kadmin/krb1.example.com@EXAMPLE.COM"
        },
        {
          "_id": "kiprop/krb1.example.com@EXAMPLE.COM",
          "principal": "kiprop/krb1.example.com@EXAMPLE.COM"
        },
        {
          "_id": "krbtgt/EXAMPLE.COM@EXAMPLE.COM",
          "principal": "krbtgt/EXAMPLE.COM@EXAMPLE.COM"
        },
        {
          "_id": "scarter@EXAMPLE.COM",
          "principal": "scarter@EXAMPLE.COM"
        },
        {
          "_id": "openidm/admin@EXAMPLE.COM",
          "principal": "openidm/admin@EXAMPLE.COM"
        }
      ],
      ...
    }

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

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

   $ cd /path/to/opendj
   $ ./setup \
    directory-server \
    --hostname localhost \
    --ldapPort 1389 \
    --rootUserDN "cn=Directory Manager" \
    --rootUserPassword password \
    --adminConnectorPort 4444 \
    --baseDN dc=com \
    --ldifFile /path/to/openidm/samples/multiple-passwords/data/Example.ldif \
    --acceptLicense
   Validating parameters .....Done.
   Configuring Certificates .....Done.
   Configuring server .....Done.
   Importing data from /path/to/openidm/samples/multiple-passwords/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 IDM as described in "Preparing IDM", then start the server with the configuration for the multiple passwords sample:

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

2. Create a user in IDM. 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": "000000001298f6a6",
     "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": {
           "cipher": "AES/CBC/PKCS5Padding",
           "salt": "FQXojsuDX3JYeQguIykRDQ==",
           "data": "2oHsVDZmNfrIUtVN7LKB/A==",
           "iv": "hUK2gOWIhv6g+5Ykms46xg==",
           "key": "openidm-sym-default",
           "mac": "hAMNkwcxb7Ka/hrWRmogyw=="
         },
         "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": "3bbf1f43-e120-4d34-a4c9-05bd02be23bd",
       "dn" : "uid=jdoe,ou=People,dc=example,dc=com"
     }, {
       "_id": "d6c73ea1-fd05-4b80-8625-c50303755c91",
       "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: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   mail: john.doe@example.com
   sn: Doe
   cn: John Doe
   givenName: John
   userPassword: {SSHA512}qr8cljBrAHF/rEOGQe71EvCJzuUbLmWnA7tOfN0t3FaQjJVK2Ys5M...
   uid: jdoe
   
   dn: uid=jdoe,ou=Customers,dc=example,dc=com
   objectClass: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   mail: john.doe@example.com
   sn: Doe
   cn: John Doe
   givenName: John
   uid: jdoe
   $ 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: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   mail: john.doe@example.com
   sn: Doe
   cn: John Doe
   givenName: John
   uid: jdoe
   
   dn: uid=jdoe,ou=Customers,dc=example,dc=com
   objectClass: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   mail: john.doe@example.com
   sn: Doe
   cn: John Doe
   givenName: John
   userPassword: {SSHA512}PVtdOxRfBL8mG5duCE7RopCW5eA4NWJudZsW9WhNFpqC58M9koA9...
   uid: jdoe

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": "000000001298f6a6",
     "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: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   mail: john.doe@example.com
   sn: Doe
   cn: John Doe
   userPassword: {SSHA512}Fc1DATM62kIz5DZNJOUStBfvAlHl2QJtMwd8+bhCupUUoLhtIXr4D...
   givenName: John
   uid: jdoe
   
   dn: uid=jdoe,ou=Customers,dc=example,dc=com
   objectClass: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   mail: john.doe@example.com
   sn: Doe
   cn: John Doe
   givenName: John
   uid: jdoe

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": "00000000a92657c7",
     "userName": "jdoe",
     "givenName": "John",
     "sn": "Doe",
     "displayName": "John Doe",
     "mail": "john.doe@example.com",
   ...
     "ldapPassword": {
       "$crypto": {
         "value": {
           "algorithm": "SHA-256",
           "data": "N7WR9d+JsJDe2Atr5dc1bIVlhT+SaA+vKV1v2tUR2A13mpu/cTIQWiIBMpE/JilO"
         },
         "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": "00000000dc6160c8",
     "userName": "jdoe",
     "givenName": "John",
     "sn": "Doe",
     "displayName": "John Doe",
     ...
     "ldapPassword": {
       "$crypto": {
         "value": {
           "algorithm": "SHA-256",
           "data": "6ukaCgcNzGjG9++SoHnIPYlSV4JZ2MBtHt5YepONl/oSNGQ3SQh7YozSO1PA+HAC"
         },
         "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": "00000000a92657c7",
     "userName": "jdoe",
     "givenName": "John",
     "sn": "Doe",
     "displayName": "John Doe",
    ...
     "ldapPassword": {
       "$crypto": {
         "value": {
           "algorithm": "SHA-256",
           "data": "zJUQB7xMoLWwJPZZli99iktMIL+L2rh2wo0ueODekQ/bKobk8JCAOvudFinSmX1T"
         },
         "type": "salted-hash"
       }
     }
   }

   User jdoe now has a history of ldapPassword values, that contains TTestw0rd3, TTestw0rd2, TTestw0rd1, and TTestw0rd, in that order.

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 ldapPassword 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": "00000000792afa08",
     "userName": "jdoe",
     "givenName": "John",
     "sn": "Doe",
     "displayName": "John Doe",
    ...
     "ldapPassword": {
       "$crypto": {
         "value": {
           "algorithm": "SHA-256",
           "data": "qAeh50kePULpYVkaUM8hgdDV/SeVDJorehoXQgmyK5jKEClB02PWZm0ny6eC/eLp"
         },
         "type": "salted-hash"
       }
     }
   }

   This time, the password reset succeeds.

1. Prepare IDM as described in "Preparing IDM", then start the server with the configuration for the Multi-Account Linking sample:

   $ cd /path/to/openidm

   $ ./startup.sh -p samples/multi-account-linking

2. Create the managed users.

   For the purpose of this sample, create managed user entries for John Doe and Barbara Jensen. To create these users from the Admin UI, navigate to https://localhost:8443/admin and click Manage > User > New User.

   Alternatively, use the following REST calls to create these managed user entries:

   $ curl \
   --header "Content-Type: application/json" \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --request POST \
   --data '{
     "displayName" : "Barbara Jensen",
     "description" : "Created for OpenIDM",
     "givenName" : "Barbara",
     "mail" : "bjensen@example.com",
     "telephoneNumber" : "1-360-229-7105",
     "sn" : "Jensen",
     "userName" : "bjensen",
     "accountStatus" : "active"
   }' \
   "http://localhost:8080/openidm/managed/user?_action=create"
   {
     "_id": "580f1441-ff8e-434b-9605-90e10a6fbdf6",
     "_rev": "00000000792afa08",
     "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": []
   }

   $ curl \
   --header "Content-Type: application/json" \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --request POST \
   --data '{
     "displayName" : "John Doe",
     "description" : "Created for OpenIDM",
     "givenName" : "John",
     "mail" : "jdoe@example.com",
     "telephoneNumber" : "1-415-599-1100",
     "sn" : "Doe",
     "userName" : "jdoe",
     "accountStatus" : "active"
   }' \
   "http://localhost:8080/openidm/managed/user?_action=create"
   {
     "_id": "02632173-e413-4af1-8495-f749d5880226",
     "_rev": "000000001298f6a6",
     "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": []
   }

   In the output, you will see an _id associated with each user, for example, 580f1441-ff8e-434b-9605-90e10a6fbdf6. Make a note of these _ids because you will need them when you assign roles to the managed users.

3. Set up the managed roles.

   This sample uses two managed roles, Agent, and Insured, to distinguish between the two user types described previously. To set up these roles in the Admin UI, navigate to https://localhost:8443/admin and click Manage > Role > New Role.

   Alternatively, use the following REST calls to set up the two managed roles:

   $ curl \
   --header "Content-Type: application/json" \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --request POST \
   --data '{
     "name" : "Agent",
     "description" : "Role assigned to insurance agents."
   }' \
   "http://localhost:8080/openidm/managed/role?_action=create"
   {
     "_id": "1b58ec8d-fae2-4b28-a5cf-b63567e4cf3f",
     "_rev": "000000005b3d5ebd",
     "name": "Agent",
     "description": "Role assigned to insurance agents."
   }

   $ curl \
   --header "Content-Type: application/json" \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --request POST \
   --data '{
     "name" : "Insured",
     "description" : "Role assigned to insured customers."
   }' \
   "http://localhost:8080/openidm/managed/role?_action=create"
   {
     "_id": "617368f2-fa4e-44a2-a25a-f0a86e16ef00",
     "_rev": "000000002b845f24",
     "name": "Insured",
     "description": "Role assigned to insured customers."
   }

   Take note of the _id of each managed role. You will need these IDs to assign the roles to your managed users.

4. Grant the managed roles to the users.

   This step assumes that user jdoe is both an Agent and an Insured customer and that user bjensen is just an Insured customer of Example.com.

   To grant the roles, you need the _id for each user and the _id of each role, that you obtained when you created the users and roles.

   The following command grants the Agent role to jdoe:

   $ 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/1b58ec8d-fae2-4b28-a5cf-b63567e4cf3f"
         }
       }
     ]' \
   "http://localhost:8080/openidm/managed/user/02632173-e413-4af1-8495-f749d5880226"
   {
     "_id": "02632173-e413-4af1-8495-f749d5880226",
     "_rev": "00000000dc6160c8",
     "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": [
       {
         "_ref": "managed/role/1b58ec8d-fae2-4b28-a5cf-b63567e4cf3f"
       }
     ],
     "effectiveAssignments": []
   }

   The following command grants the Insured role to user bjensen:

   $ 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/617368f2-fa4e-44a2-a25a-f0a86e16ef00"
         }
       }
     ]' \
   "http://localhost:8080/openidm/managed/user/580f1441-ff8e-434b-9605-90e10a6fbdf6"
   {
     "_id": "580f1441-ff8e-434b-9605-90e10a6fbdf6",
     "_rev": "000000004cab60c8",
     "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": [
       {
         "_ref": "managed/role/617368f2-fa4e-44a2-a25a-f0a86e16ef00"
       }
     ],
     "effectiveAssignments": []
   }

   The following command grants the Insured role to jdoe, because he is both an insured customer and an agent:

   $ 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/617368f2-fa4e-44a2-a25a-f0a86e16ef00"
         }
       }
     ]' \
   "http://localhost:8080/openidm/managed/user/02632173-e413-4af1-8495-f749d5880226"
   {
     "_id": "02632173-e413-4af1-8495-f749d5880226",
     "_rev": "00000000a92657c7",
     "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": [
       {
         "_ref": "managed/role/1b58ec8d-fae2-4b28-a5cf-b63567e4cf3f"
       },
       {
         "_ref": "managed/role/617368f2-fa4e-44a2-a25a-f0a86e16ef00"
       }
     ],
     "effectiveAssignments": []
   }

   Note from the output that jdoe now has two managed roles (and thus, two values for his effectiveRoles property.

5. Create the managed assignments.

   Assignments specify what a role actually does on a target system. A single account frequently has different functions on a system. For example, while agents might be members of the Contractor group, insured customers might be part of a Chat Users group (possibly for access to customer service). The following commands create two managed assignments that will be attached to the agent and insured roles. Note the _id of each assignment because you will need these when you attach the assignment to its corresponding role.

   The following command creates an ldapAgent assignment. Users who have this assignment will have their ldapGroups property in DS set to cn=Contractors,ou=Groups,dc=example,dc=com. The assignment is associated with the agent link qualifier:

   $ curl \
    --header "Content-Type: application/json" \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    --data '{
      "name" : "ldapAgent",
      "description" : "LDAP Agent Assignment",
      "mapping" : "managedUser_systemLdapAccounts",
      "attributes": [
        {
          "name": "ldapGroups",
          "value": [
            "cn=Contractors,ou=Groups,dc=example,dc=com"
          ],
          "assignmentOperation" : "mergeWithTarget",
          "unassignmentOperation" : "removeFromTarget"
        }
      ],
      "linkQualifiers": ["agent"]
    }' \
    "http://localhost:8080/openidm/managed/assignment?_action=create"
   {
     "_id": "cc0dbcdc-64a4-4f5b-aade-648fc012e2b5",
     "_rev": "00000000c7554e13",
     "name": "ldapAgent",
     "description": "LDAP Agent Assignment",
     "mapping": "managedUser_systemLdapAccounts",
     "attributes": [
       {
         "name": "ldapGroups",
         "value": [
           "cn=Contractors,ou=Groups,dc=example,dc=com"
         ],
         "assignmentOperation": "mergeWithTarget",
         "unassignmentOperation": "removeFromTarget"
       }
     ],
     "linkQualifiers": [
       "agent"
     ]
   }

   The following command creates an ldapCustomer assignment. Users who have this assignment will have their ldapGroups property in DS set to cn=Chat Users,ou=Groups,dc=example,dc=com. The assignment is associated with the insured link qualifier:

   $ curl \
     --header "Content-Type: application/json" \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request POST \
     --data '{
       "name" : "ldapCustomer",
       "description" : "LDAP Customer Assignment",
       "mapping" : "managedUser_systemLdapAccounts",
       "attributes": [
         {
           "name": "ldapGroups",
           "value": [
             "cn=Chat Users,ou=Groups,dc=example,dc=com"
           ],
           "assignmentOperation" : "mergeWithTarget",
           "unassignmentOperation" : "removeFromTarget"
         }
       ],
       "linkQualifiers": ["insured"]
     }' \
   "http://localhost:8080/openidm/managed/assignment?_action=create"
   {
     "_id": "56b1f300-7156-4110-9b23-2052c16dd2aa",
     "_rev": "000000000cde398e",
     "name": "ldapCustomer",
     "description": "LDAP Customer Assignment",
     "mapping": "managedUser_systemLdapAccounts",
     "attributes": [
       {
         "name": "ldapGroups",
         "value": [
           "cn=Chat Users,ou=Groups,dc=example,dc=com"
         ],
         "assignmentOperation": "mergeWithTarget",
         "unassignmentOperation": "removeFromTarget"
       }
     ],
     "linkQualifiers": [
       "insured"
     ]
   }

6. Add the assignments to their respective roles.

   Add the ldapCustomer assignment to the Insured customer role:

   $ curl \
   --header "Content-type: application/json" \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --request PATCH \
   --data '[
       {
         "operation" : "add",
         "field" : "/assignments/-",
         "value" : {
           "_ref" : "managed/assignment/56b1f300-7156-4110-9b23-2052c16dd2aa"
         }
       }
     ]' \
   "http://localhost:8080/openidm/managed/role/617368f2-fa4e-44a2-a25a-f0a86e16ef00"
   {
     "_id": "617368f2-fa4e-44a2-a25a-f0a86e16ef00",
     "_rev": "0000000050c62938",
     "name": "Insured",
     "description": "Role assigned to insured customers."
   }

7. Add the ldapAgent assignment to the Agent role:

   $ curl \
   --header "Content-type: application/json" \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --request PATCH \
   --data '[
       {
         "operation" : "add",
         "field" : "/assignments/-",
         "value" : {
           "_ref" : "managed/assignment/cc0dbcdc-64a4-4f5b-aade-648fc012e2b5"
         }
       }
     ]' \
   "http://localhost:8080/openidm/managed/role/1b58ec8d-fae2-4b28-a5cf-b63567e4cf3f"

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

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

   $ cd /path/to/opendj
   $ ./setup \
    directory-server \
    --hostname localhost \
    --ldapPort 1389 \
    --rootUserDN "cn=Directory Manager" \
    --rootUserPassword password \
    --adminConnectorPort 4444 \
    --baseDN dc=com \
    --ldifFile /path/to/openidm/samples/historical-account-linking/data/Example.ldif \
    --acceptLicense
   .Validating parameters .....Done.
   Configuring Certificates .....Done.
   Configuring server .....Done.
   Importing data from /path/to/openidm/samples/historical-account-linking/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
   The Replication Server was created successfully

   $ ./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
   The Replication Domain was created successfully

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

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

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

   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": "00000000b8ea3183",
     "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 DS.

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

   The following command returns all IDs in DS 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": "0da50512-79bb-3461-bd04-241ee4c785bf",
         "dn": "uid=jdoe,ou=People,dc=example,dc=com"
       },
       {
         "_id": "887732e8-3db2-31bb-b329-20cd6fcecc05",
         "dn": "uid=bjensen,ou=People,dc=example,dc=com"
       },
       {
         "_id": "0fa26f3f-55c1-4e0f-993b-dec7b9bc26d3",
         "dn": "uid=joe.smith0,ou=People,dc=example,dc=com"
       }
     ],
     ...
   }

   Note that Joe Smith's uid in DS is appended with a 0. The onCreate script, defined in the mapping (sync.json), increments the uid each time a new DS 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 IDM 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": [
       {
         "_id": "2fe2f801-fbde-4c61-9b30-485e67ad08cc",
         "_rev": "000000002ec6cd4f",
         "_ref": "system/ldap/account/0fa26f3f-55c1-4e0f-993b-dec7b9bc26d3",
         "_refResourceCollection": "system/ldap/account",
         "_refResourceId": "0fa26f3f-55c1-4e0f-993b-dec7b9bc26d3",
         "_refProperties": {
           "active": true,
           "stateLastChanged": "Mon Feb 26 2018 12:09:46 GMT+0200 (SAST)",
           "state": "enabled",
           "linkDate": "Mon Feb 26 2018 12:09:46 GMT+0200 (SAST)",
           "_id": "2fe2f801-fbde-4c61-9b30-485e67ad08cc",
           "_rev": "000000002ec6cd4f"
         }
       }
     ],
   ...
   }

   At this stage, Joe Smith has only one historical account link — the link to system/ldap/account/0fa26f3f-55c1-4e0f-993b-dec7b9bc26d3, which corresponds to the DN "dn": "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 DS (enabled)

5. Enable the liveSync schedule to propagate changes made in DS 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/historical-account-linking/conf/schedule-liveSync.json
   {
       "enabled" : true,
       "type" : "simple",
       "repeatInterval" : 15000,
   ...

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

   $ 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. IDM 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": [
       {
         "_id": "2fe2f801-fbde-4c61-9b30-485e67ad08cc",
         "_rev": "00000000b535e3e6",
         "_ref": "system/ldap/account/0fa26f3f-55c1-4e0f-993b-dec7b9bc26d3",
         "_refResourceCollection": "system/ldap/account",
         "_refResourceId": "0fa26f3f-55c1-4e0f-993b-dec7b9bc26d3",
         "_refProperties": {
           "active": true,
           "stateLastChanged": "Mon Feb 26 2018 12:22:22 GMT+0200 (SAST)",
           "state": "disabled",
           "linkDate": "Mon Feb 26 2018 12:09:46 GMT+0200 (SAST)",
           "_id": "2fe2f801-fbde-4c61-9b30-485e67ad08cc",
           "_rev": "00000000b535e3e6"
         }
       }
     ],
   ...
   }

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": "00000000579f3324",
     "userName": "joe.smith",
     "givenName": "Joe",
     "sn": "Smith",
     "displayName": "Joe Smith",
     "mail": "joe.smith@example.com",
     "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": [
       {
         "_id": "2fe2f801-fbde-4c61-9b30-485e67ad08cc",
         "_rev": "00000000f00cf26e",
         "_ref": "system/ldap/account/0fa26f3f-55c1-4e0f-993b-dec7b9bc26d3",
         "_refResourceCollection": "system/ldap/account",
         "_refResourceId": "0fa26f3f-55c1-4e0f-993b-dec7b9bc26d3",
         "_refProperties": {
           "active": false,
           "stateLastChanged": "Mon Feb 26 2018 12:22:22 GMT+0200 (SAST)",
           "state": "disabled",
           "linkDate": "Mon Feb 26 2018 12:09:46 GMT+0200 (SAST)",
           "unlinkDate": "Mon Feb 26 2018 12:29:35 GMT+0200 (SAST)",
           "_id": "2fe2f801-fbde-4c61-9b30-485e67ad08cc",
           "_rev": "00000000f00cf26e"
         }
       }
     ],
   ...
   }

10. Activate Joe Smith's managed user account by setting his accountStatus property to active. This action should create a new entry in DS (with uid=joe.smith1), and a new link from Joe Smith's managed user object to that DS 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": "00000000c2cb3095",
      "userName": "joe.smith",
      "givenName": "Joe",
      "sn": "Smith",
      "displayName": "Joe Smith",
      "mail": "joe.smith@example.com",
      "accountStatus": "active",
     ...
    }
    

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

    The following command returns all IDs in DS and shows that two entries now exist 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": "0da50512-79bb-3461-bd04-241ee4c785bf",
          "dn": "uid=jdoe,ou=People,dc=example,dc=com"
        },
        {
          "_id": "887732e8-3db2-31bb-b329-20cd6fcecc05",
          "dn": "uid=bjensen,ou=People,dc=example,dc=com"
        },
        {
          "_id": "0fa26f3f-55c1-4e0f-993b-dec7b9bc26d3",
          "dn": "uid=joe.smith0,ou=People,dc=example,dc=com"
        },
        {
          "_id": "30ca4ec1-9561-49d8-8199-ed52e66a66f2",
          "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": [
        {
          "_id": "2fe2f801-fbde-4c61-9b30-485e67ad08cc",
          "_rev": "00000000f00cf26e",
          "_ref": "system/ldap/account/0fa26f3f-55c1-4e0f-993b-dec7b9bc26d3",
          "_refResourceCollection": "system/ldap/account",
          "_refResourceId": "0fa26f3f-55c1-4e0f-993b-dec7b9bc26d3",
          "_refProperties": {
            "active": false,
            "stateLastChanged": "Mon Feb 26 2018 12:22:22 GMT+0200 (SAST)",
            "state": "disabled",
            "linkDate": "Mon Feb 26 2018 12:09:46 GMT+0200 (SAST)",
            "unlinkDate": "Mon Feb 26 2018 12:29:35 GMT+0200 (SAST)",
            "_id": "2fe2f801-fbde-4c61-9b30-485e67ad08cc",
            "_rev": "00000000f00cf26e"
          }
        },
        {
          "_id": "dd8f895d-4b6e-4425-b92a-1963e1720987",
          "_rev": "000000008770cc38",
          "_ref": "system/ldap/account/30ca4ec1-9561-49d8-8199-ed52e66a66f2",
          "_refResourceCollection": "system/ldap/account",
          "_refResourceId": "30ca4ec1-9561-49d8-8199-ed52e66a66f2",
          "_refProperties": {
            "active": true,
            "stateLastChanged": "Mon Feb 26 2018 12:30:40 GMT+0200 (SAST)",
            "state": "enabled",
            "linkDate": "Mon Feb 26 2018 12:30:40 GMT+0200 (SAST)",
            "_id": "dd8f895d-4b6e-4425-b92a-1963e1720987",
            "_rev": "000000008770cc38"
          }
        }
      ],
      ...
    }

    Note that Joe Smith's entry now shows two DS accounts, but that only the link to uid=joe.smith1 ("_ref": "system/ldap/account/30ca4ec1-9561-49d8-8199-ed52e66a66f2",) is enabled and active.

1. Start IDM with the configuration for the provisioning sample:

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/provisioning-with-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 > Email Settings and provide the connection information for your 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. Choose the first mapping (systemRolesFileRole_managedRole) and select Reconcile.

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

   3. Go back to the Mappings page (Configure > Mappings), choose the second mapping (systemCsvfileAccounts_managedUser) and select Reconcile.

      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. Select Reconcile 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).

      Verify 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. Select user1. Note that the Manager field shows manager1 for this user.

   2. On the Authorization Roles tab, note that user1 has two roles—a Basic minimum user role and an employee role.

   3. Navigate back to the User List and select manager1. Note that the Manager field is empty for this user.

   4. On the Authorization Roles tab, note that manager1 has two roles—a Basic minimum user role and a manager role.

6. Verify the available workflows:

   1. Select Manage > Processes > Definitions.

   2. Select 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 drop-down 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. Scroll down to Processes and select Details next to the Contractor onboarding process.

      Complete the form for the sample user you will be creating. You can use any sample data here but use an email address to which you have access because you will need the email that is sent to this address to complete the workflow.

      In the Provision to CSV field, select Yes.

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

      

      Note that user1 does not provide a password for this user. A password reset request is sent to the email address provided on this form to ensure that only the actual contractor can log in with this account.

   2. Select 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.

      Select Details next to the task name.

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

      Select Accept, then Complete to finish the task.

   5. Log out of the Self-Service UI.

4. Verify that the contractor has been created in the HR data source (hr.csv):

   $ more /path/to/openidm/samples/provisioning-with-workflow/data/hr.csv
   
   "username","firstname","lastname","manager", "department","jobTitle",     ...,"password",...
   "user1",   "Ordinary", "Employee","manager1","dep1",      "job1",         ...,"Welcome1",...
   "manager1","Big",      "Manager", "",        "dep1",      "Manager",      ...,"Welcome1",...
   "bjensen", "Barbara",  "Jensen",  "user1",   "Payroll",   "Payroll clerk",...,,,...

   Note the addition of the new contractor entry, in this case, bjensen. Note also that there is no value for the password field, and that user1 is the manager of the new contractor.

5. Complete the password reset process:

   1. Verify the inbox of the email account that you provided when you completed the initial form.

      You should have received two emails — one with the subject "Your account has been created" and one 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. Select 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 HR data source:

   Open /path/to/openidm/samples/provisioning-with-workflow/data/hr.csv and note that the password for the contractor has been added to their entry.

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

2. Set up DS 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 IDM 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 DS 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 DS 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 \
     --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 \
     --trustAll \
     --no-prompt
       

4. Enable the DS 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/scripted-rest-with-dj/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 IDM administrator user to read the DS 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 DS Administration Guide.

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

   $ cd /path/to/opendj
   $ cp /path/to/openidm/samples/scripted-rest-with-dj/data/example-v1.json config/rest2ldap/endpoints/api/

9. Restart DS for the configuration change to take effect.

   $ cd /path/to/opendj/bin
   $ ./stop-ds --restart
   Stopping Server...
   ...
   The Directory Server has started successfully
   [07/Feb/2018:12:12:23 +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 IDM with the configuration for the ScriptedREST sample:

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/scripted-rest-with-dj/

2. Check that the scripted REST connector can reach the DS instance by obtaining the connector status 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",
     "connectorRef": {
       "bundleVersion": "[1.5.0.0,1.6.0.0)",
       "bundleName": "org.forgerock.openicf.connectors.scriptedrest-connector",
       "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector"
     },
     "displayName": "Scripted REST Connector",
     "objectTypes": [
       "__ALL__",
       "account",
       "group"
     ],
     "ok": true
   }
       

3. Create a group entry on the DS 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",
     "displayName": "group1",
     "created": "2018-02-07T10:14:12Z",
     "members": null,
     "cn": "group1"
   }

4. Create a user entry on the DS 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",
     "familyName": "Carter",
     "givenName": "Steven",
     "created": "2018-02-07T10:14:31Z",
     "uid": "scarter",
     "groups": null,
     "emailAddress": "scarter@example.com",
     "displayName": "Steven.Carter",
     "telephoneNumber": "444-444-4444"
   }

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

5. Reconcile the DS server with the 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": "ee7534bd-ccfd-4f6a-bdc3-49caa6d2043c-547",
     "state": "SUCCESS"
   }

6. The reconciliation creates a managed user with a server-assigned ID. To retrieve the ID, run the following query:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-Type: application/json" \
    --request GET \
    "http://localhost:8080/openidm/managed/user?_queryId=query-all-ids"
   {
     "result": [
       {
         "_id": "4657a420-6608-410e-baa7-f64668cc500c",
         "_rev": "000000007995f006"
       }
     ],
     ...
   }

7. To initialize liveSync set the sync token by running one liveSync operation over REST:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    "http://localhost:8080/openidm/system/scriptedrest/account?_action=liveSync"
   {
     "connectorData": {
       "nativeType": "string",
       "syncToken": "9"
     },
     "_rev": "00000000109353c9",
     "_id": "SYSTEMSCRIPTEDRESTACCOUNT"
   }

8. Update Steven Carter's managed user entry, by modifying his telephone number. Specify the user ID that you retrieved previously:

   $ 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/4657a420-6608-410e-baa7-f64668cc500c"
   {
     "_id": "4657a420-6608-410e-baa7-f64668cc500c",
     "_rev": "0000000096edf021",
     "userName": "scarter",
     "mail": "scarter@example.com",
     "displayName": "Steven.Carter",
     "telephoneNumber": "555-555-5555",
     "givenName": "Steven",
     "sn": "Carter",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }

9. The implicit synchronization mechanism between the managed user repository and DS propagates the change to DS. You can check this change by reading scarter's user entry in DS and noting the changed telephoneNumber:

   $ 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",
     "familyName": "Carter",
     "givenName": "Steven",
     "created": "2018-02-07T10:14:31Z",
     "uid": "scarter",
     "groups": null,
     "emailAddress": "scarter@example.com",
     "displayName": "Steven.Carter",
     "telephoneNumber": "555-555-5555"
   }

10. Now, update Steven Carter's entry on the DS server, by modifying his givenName:

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --header "Content-Type: application/json" \
     --request PATCH \
     --data '[
        {
            "operation" : "replace",
            "field" : "givenName",
            "value" : "Steve"
        }
     ]' \
     "http://localhost:8080/openidm/system/scriptedrest/account/scarter"
        {
      "_id": "scarter",
      "familyName": "Carter",
      "givenName": "Steve",
      "created": "2018-02-07T10:14:31Z",
      "uid": "scarter",
      "groups": null,
      "emailAddress": "scarter@example.com",
      "displayName": "Steven.Carter",
      "telephoneNumber": "555-555-5555"
    }
        

11. To propagate the change made on DS back to the managed user entry, launch a liveSync operation, either by defining a schedule, or directly over REST. The following command launches liveSync over REST:

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request POST \
     "http://localhost:8080/openidm/system/scriptedrest/account?_action=liveSync"
        {
      "connectorData": {
        "nativeType": "string",
        "syncToken": "9"
      },
      "_rev": "000000000a585336",
      "_id": "SYSTEMSCRIPTEDRESTACCOUNT"
    }

12. Verify that the changes were propagated by reading scarter's managed user entry and noting the changed givenName:

    $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/managed/user/4657a420-6608-410e-baa7-f64668cc500c"
    {
      "_id": "4657a420-6608-410e-baa7-f64668cc500c",
      "_rev": "000000007937efb7",
      "userName": "scarter",
      "mail": "scarter@example.com",
      "displayName": "Steven.Carter",
      "telephoneNumber": "555-555-5555",
      "givenName": "Steve",
      "sn": "Carter",
      "accountStatus": "active",
      "effectiveRoles": [],
      "effectiveAssignments": []
    }
        

13. Add user scarter 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",
      "displayName": "group1",
      "created": "2018-02-07T10:14:12Z",
      "members": [
        {
          "_id": "scarter",
          "displayName": "Steven.Carter"
        }
      ],
      "cn": "group1",
      "lastModified": "2018-02-07T10:20:22Z"
    }

14. Read Steven Carter's user entry in DS, 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",
      "familyName": "Carter",
      "givenName": "Steve",
      "created": "2018-02-07T10:14:31Z",
      "uid": "scarter",
      "groups": [
        {
          "_id": "group1"
        }
      ],
      "emailAddress": "scarter@example.com",
      "displayName": "Steven.Carter",
      "telephoneNumber": "555-555-5555"
    }

15. 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",
      "displayName": "group1",
      "created": "2018-02-07T10:14:12Z",
      "members": [
        {
          "_id": "scarter",
          "displayName": "Steven.Carter"
        }
      ],
      "cn": "group1",
      "lastModified": "2018-02-07T10:20:22Z"
    }

16. Reconcile the DS groups with the 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": "ee7534bd-ccfd-4f6a-bdc3-49caa6d2043c-1477",
      "state": "SUCCESS"
    }

17. The reconciliation creates a managed group with a server-assigned ID. To retrieve the group ID, run the following query:

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --header "Content-Type: application/json" \
     --request GET \
     "http://localhost:8080/openidm/managed/group?_queryId=query-all-ids"
    {
      "result": [
        {
          "_id": "67b5ec50-d5a6-4bfa-bb19-17965447ad00",
          "_rev": "00000000b0e95e9b"
        }
      ],
      ...
    }

18. Read the managed group to verify that the DS group has been added, and that its members have been reconciled to the managed group repository. Specify the ID that you retrieved in the previous step:

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request GET \
     "http://localhost:8080/openidm/managed/group/67b5ec50-d5a6-4bfa-bb19-17965447ad00"
    {
      "_id": "67b5ec50-d5a6-4bfa-bb19-17965447ad00",
      "_rev": "00000000b0e95e9b",
      "members": [
        {
          "_id": "scarter",
          "displayName": "Steven.Carter"
        }
      ],
      "displayName": "group1"
    }

19. Delete the DS user and group entries, returning the DS 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",
      "familyName": "Carter",
      "givenName": "Steve",
      "created": "2018-02-07T10:14:31Z",
      "uid": "scarter",
      "groups": [
        {
          "_id": "group1"
        }
      ],
      "emailAddress": "scarter@example.com",
      "displayName": "Steven.Carter",
      "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",
      "displayName": "group1",
      "created": "2018-02-07T10:14:12Z",
      "members": null,
      "cn": "group1",
      "lastModified": "2018-02-07T10:20:22Z"
    }
        

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 IDM to connect to the .NET connector server.

   To do so, copy the remote connector server configuration 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 IDM to Connect to the .NET Connector Server" in the Integrator's Guide.

3. Download the PowerShell Connector Toolkit archive (mspowershell-connector-1.4.5.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 and the ADSISearch module from the samples\scripted-powershell-with-ad\tools directory, to the machine on which the connector server is installed.

   PS C:\path\to\openidm>dir samples\scripted-powershell-with-ad\tools
   Directory: C:\path\to\openidm\samples\scripted-powershell-with-ad\tools
   
   Mode                LastWriteTime         Length Name
   ----                -------------         ------ ----
   -a----         4/3/2018   3:26 AM           4279 ADAuthenticate.ps1
   -a----         4/3/2018   3:26 AM           9055 ADCreate.ps1
   -a----         4/3/2018   3:26 AM           3717 ADDelete.ps1
   -a----         4/3/2018   3:26 AM          10756 ADSchema.ps1
   -a----         4/3/2018   3:26 AM           4625 ADSearch.ps1
   -a----         4/3/2018   3:26 AM           8064 ADSISearch.psm1
   -a----         4/3/2018   3:26 AM           5918 ADSync.ps1
   -a----         4/3/2018   3:26 AM           2408 ADTest.ps1
   -a----         4/3/2018   3:26 AM          18406 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/scripted-powershell-with-ad/tools/ADAuthenticate.ps1",
       "CreateScriptFileName" : "C:/openidm/samples/scripted-powershell-with-ad/tools/ADCreate.ps1",
       "DeleteScriptFileName" : "C:/openidm/samples/scripted-powershell-with-ad/tools/ADDelete.ps1",
       "SchemaScriptFileName" : "C:/openidm/samples/scripted-powershell-with-ad/tools/ADSchema.ps1",
       "SearchScriptFileName" : "C:/openidm/samples/scripted-powershell-with-ad/tools/ADSearch.ps1",
       "SyncScriptFileName" : "C:/openidm/samples/scripted-powershell-with-ad/tools/ADSync.ps1",
       "TestScriptFileName" : "C:/openidm/samples/scripted-powershell-with-ad/tools/ADTest.ps1",
       "UpdateScriptFileName" : "C:/openidm/samples/scripted-powershell-with-ad/tools/ADUpdate.ps1",
       "VariablesPrefix" : "Connector",
       "QueryFilterType" : "Ldap",
       "ReloadScriptOnExecution" : true,
       "UseInterpretersPool" : true,
       "SubstituteUidAndNameInQueryFilter" : true,
       "UidAttributeName" : "ObjectGUID",
       "NameAttributeName" : "DistinguishedName",
       "PsModulesToImport" : [
           "ActiveDirectory",
           "C:/openidm/samples/scripted-powershell-with-ad/tools/ADSISearch.psm1"
       ],
       "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/scripted-powershell-with-ad/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 IDM 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 that 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" `
    --header "Content-Type: application/json" `
    --request POST `
    --data '{
        \"username\" : \"Steven Carter\",
        \"password\" : \"Passw0rd\"
        } `
    "http://localhost:8080/openidm/system/adpowershell/account?_action=authenticate"
   {
     "_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 that you can 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 that you can 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\",
     \"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/scripted-powershell-with-azure-ad/tools/. If you put them in a different location, adjust your connector configuration accordingly.

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

2. Copy the PowerShell sample scripts from the IDM 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 IDM installation to the Windows machine:

   PS C:\> cd openidm\samples\scripted-powershell-with-azure-ad\tools
   PS C:\> pscp -r username@openidm-host:path/to/openidm/samples/scripted-powershell-with-azure-ad/azureADScripts/*.ps .

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

   PS C:\openidm\samples\scripted-powershell-with-azure-ad\azureADScripts> ls
   
       Directory: C:\openidm\samples\scripted-powershell-with-azure-ad\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 IDM 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 IDM is installed, navigate to the path/to/openidm/samples/scripted-powershell-with-azure-ad 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\scripted-powershell-with-azure-ad\azureADScripts) you must also update those paths in the PowerShell connector configuration file.

6. Start IDM with the PowerShell AzureAD sample configuration:

   $ cd path/to/openidm
   $ ./startup.sh -p samples/scripted-powershell-with-azure-ad

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 IDM respository.

1. Review the list of current managed users in the 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 Azure AD to IDM, the outputshould be empty:

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

2. Run a reconciliation from Azure AD to IDM:

   $ 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 IDM 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 Azure AD to IDM

   $ 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 IDM repository for a userName that starts with 'CEO' one more time, to confirm that user has been reconciled out of the IDM 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. Download MySQL Connector/J, version 5.1 or later from the MySQL website.

   Extract the contents of the zip file, and copy the .jar into the openidm/bundle directory:

   $ cp mysql-connector-java-version-bin.jar /path/to/openidm/bundle/

2. Set up MySQL to listen on localhost, port 3306. IDM will connect to the hrdb database as user root with password password.

   If want to use an existing MySQL instance that runs on a different host or port, or you want to change the database credentials, adjust the configurationProperties in the connector configuration file (samples/scripted-sql-with-mysql/conf/provisioner.openicf-hrdb.json) before you start the sample. The default configuration is as follows:

   "configurationProperties" : {
       "username" : "root",
       "password" : "password",
       "driverClassName" : "com.mysql.jdbc.Driver",
       "url" : "jdbc:mysql://localhost:3306/hrdb",

3. Set up the hrdb database, with which IDM will synchronize its managed user repository:

   mysql -u root -p
   Enter password:
   Welcome to the MySQL monitor.  Commands end with ; or \g.
   Your MySQL connection id is 3
   Server version: 5.7.13 MySQL Community Server (GPL)
   
   Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
   
   Oracle is a registered trademark of Oracle Corporation and/or its
   affiliates. Other names may be trademarks of their respective
   owners.
   
   Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
   mysql> CREATE DATABASE hrdb CHARACTER SET utf8 COLLATE utf8_bin;
   Query OK, 1 row affected (0.00 sec)
   mysql> quit
   Bye

1. Start IDM with the configuration for the ScriptedSQL sample:

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/scripted-sql-with-mysql

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.

3. 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 because as they cannot be read into IDM as clear text. The SHA-1 Hash function is used for compatibility reasons. Use a more secure algorithm in a production database.

4. Reconcile the hrdb database with the managed user repository.

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

     2. Select Configure > Mappings.

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

     3. Click Reconcile on the first mapping (systemHrdb_managedUser).

   • 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 IDM repository.

5. 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": "1b379e4d-3b8d-47e7-93d5-a72c4b483e39",
           "_rev": "000000002d93e471"
         },
         {
           "_id": "a658f751-d6e9-4b5d-af56-071a9b05c3af",
           "_rev": "000000003c83d48a"
         },
         {
           "_id": "5b31027b-09f8-4c7f-abfa-c6bc86ae3943",
           "_rev": "00000000b042e559"
         },
         {
           "_id": "1b3f6b06-1752-4c40-ba34-51d30b184b9d",
           "_rev": "0000000092bdda6d"
         },
         {
           "_id": "9c62f0d2-47e2-4fc5-89d1-b50b782b1022",
           "_rev": "0000000025cdd3c6"
         }
       ],
       "resultCount": 5,
       "pagedResultsCookie": null,
       "totalPagedResultsPolicy": "NONE",
       "totalPagedResults": -1,
       "remainingPagedResults": -1
     }
     

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

     $ curl \
      --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": "1b379e4d-3b8d-47e7-93d5-a72c4b483e39",
           "_rev": "000000002d93e471",
           "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",
           "effectiveRoles": [],
           "effectiveAssignments": []
         }
       ],
       ...
     }    

   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 IDM can understand. With support for complex objects, the data is passed through to IDM as a list of car objects. Data is synchronized from IDM 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). IDM does not maintain group membership in this way, so the Groovy scripts do the work to translate membership between the two resources.

1. Install and configure MySQL.

2. When MySQL is up and running, import the database schema to set up the database required for the sample:

   $ mysql -u root -p < /path/to/openidm/samples/audit-jdbc/data/sample_audit_db.mysql
   Enter password: password
   $ 

   This step sets up an audit database with six tables that correspond to the various audit events. You can view the tables in the audit database as follows:

   $ mysql -u root -p 
   Enter password: password
   mysql> use audit
   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> show tables;
   +---------------------+
   | Tables_in_audit     |
   +---------------------+
   | auditaccess         |
   | auditactivity       |
   | auditauthentication |
   | auditconfig         |
   | auditrecon          |
   | auditsync           |
   +---------------------+
   6 rows in set (0.00 sec)

3. Download MySQL Connector/J, version 5.1 or later from the MySQL website. Unpack the delivery, and copy the .jar into the openidm/bundle directory:

   $ cp mysql-connector-java-version-bin.jar /path/to/openidm/bundle/

4. Edit the url property in the SQL connector configuration file (conf/provisioner.openicf-auditdb.json) to match the host and port of your MySQL instance. For example:

   "url" : "jdbc:mysql://localhost:3306/audit",

1. Prepare IDM as described in "Preparing IDM", then start the server with the configuration for this sample:

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

2. Reconcile the two data sources, either over the command-line or by using the Admin UI.

   To run the reconciliation over REST, use 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=systemCsvfileAccounts_managedUser&waitForCompletion=true"
   {
     "_id": "a3664c26-bf82-4100-b411-19edc248c306-7",
     "state": "SUCCESS"
   }

   To run the reconciliation from the Admin UI, select Configure > Mappings, select the systemCsvfileAccounts_managedUser mapping, then select Reconcile.

3. Inspect the tables in the audit database to see how the logs have been routed to that location.

   The following example displays the reconciliation audit logs:

   $ $ mysql -u root -p
   Enter password: password
   ...
   mysql> use audit;
   ...
   mysql> show tables;
   +---------------------+
   | Tables_in_audit     |
   +---------------------+
   | auditaccess         |
   | auditactivity       |
   | auditauthentication |
   | auditconfig         |
   | auditrecon          |
   | auditsync           |
   +---------------------+
    6 rows in set (0.01 sec)
   mysql> select * from auditrecon;
   
   | id | objectid | transactionid | activitydate | eventname | userid        | ... | mapping...
   |  1 | a3664... | a3664c26-b... | 2017-02-1... | recon     | openidm-admin | ... | systemCsvfile... 

   You can inspect the other audit logs in the same way.

4. By default, the audit configuration in this sample uses the router audit handler for queries, as indicated in the following line from the conf/audit.json file:

   "handlerForQueries" : "router",

   With this configuration, when you query the audit logs over REST, the audit data is returned from the router handler (in this case the MySQL database). The following example shows how to query the reconciliation audit log:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    "http://localhost:8080/openidm/audit/recon?_queryFilter=true"
   {
     "result": [
       {
         "_id": "a3664c26-bf82-4100-b411-19edc248c306-16",
         "action": null,
         "trackingIds": null,
         "sourceObjectId": null,
         "timestamp": "2017-02-14T10:19:30.688Z",
         "ambiguousTargetObjectIds": null,
         "reconId": "a3664c26-bf82-4100-b411-19edc248c306-7",
         "status": null,
         "eventName": "recon",
         "mapping": "systemCsvfileAccounts_managedUser",
         "targetObjectId": null,
         "situation": null,
         "userId": "openidm-admin",
         "transactionId": "a3664c26-bf82-4100-b411-19edc248c306-7",
         "message": "Reconciliation initiated by openidm-admin",
         "reconAction": "recon",
         "messageDetail": null,
         "entryType": "start",
         "linkQualifier": null,
         "reconciling": null,
         "exception": null
       },
       ...
   }

   You can query the other audit logs in the same way.

   For more information about querying the audit logs, see "Querying Audit Logs Over REST" in the Integrator's Guide.

1. Unpack the ActiveMQ binary. For example:

   $ tar -zxvf ~/Downloads/apache-activemq-5.14.3-bin.tar.gz

2. Create a temporary directory, copy the Active MQ Client and bnd JAR files to that directory, then change to that directory:

   $ mkdir ~/Downloads/tmp
   $ mv activemq-client-5.14.3.jar ~/Downloads/tmp/
   $ mv bnd-2.4.0.jar ~/Downloads/tmp/
   $ cd ~/Downloads/tmp/

3. Create an OSGi bundle as follows:

   1. In a text editor, create a BND file named activemq.bnd with the following contents:

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

      Your tmp/ directory should now contain the following files:

      $ ls
      activemq-client-5.14.3.jar	activemq.bnd			bnd-2.4.0.jar

   2. In that same directory, create the OSGi bundle archive file as follows:

      $ java -jar bnd-2.4.0.jar \
       wrap --properties activemq.bnd \
       --output activemq-client-5.14.3-osgi.jar \
       activemq-client-5.14.3.jar 

4. Copy the resulting activemq-client-5.14.3-osgi.jar file to the openidm/bundle directory:

   $ cp activemq-client-5.14.3-osgi.jar /path/to/openidm/bundle/

5. Copy the Apache Geronimo, hawtbuf, and JmDNS JAR files to the openidm/bundle directory:

   $ cp ~/Downloads/geronimo-j2ee-management_1.1_spec-1.0.1.jar /path/to/openidm/bundle/
   $ cp ~/Downloads/hawtbuf-1.11.jar /path/to/openidm/bundle/
   $ cp ~/Downloads/jmdns-3.4.1.jar /path/to/openidm/bundle

   Your OpenIDM instance is now ready for you to configure the JMS audit event handler.

1. Navigate to the directory where you unpacked the ActiveMQ binary, for example:

   $  cd ~/Downloads/apache-activemq-5.14.3

2. If you need SSL protection for your audit data, edit the ActiveMQ configuration file, activemq.xml, in the conf/ subdirectory.

   Find the code block associated with <transportConnectors>, and add the following (all on one line) within that block:

   <transportConnector name="ssl"
   uri="ssl://0.0.0.0:61617?transport.enabledCipherSuites=
       SSL_RSA_WITH_RC4_128_SHA,SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
   &amp;maximumConnections=1000&amp;wireFormat.maxFrameSize=104857600&amp;transport.daemon=true"/>
      

3. Navigate to the directory where you unpacked the ActiveMQ binary and run the following command to start the ActiveMQ broker:

   $ bin/activemq start
   INFO: Loading '/path/to/Downloads/apache-activemq-5.14.3//bin/env'
   INFO: Using java '/usr/bin/java'
   INFO: Starting - inspect logfiles specified in logging.properties and log4j.properties to get details
   INFO: pidfile created : '/path/to/Downloads/apache-activemq-5.14.3//data/activemq.pid' (pid '69627')

4. Start IDM with the configuration for this sample:

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

1. Use the instructions for downloading and installing MongoDB in the MongoDB Manual. For the supported version of MongoDB, see "MongoDB Connector" in the Connector Reference.

2. Set up MongoDB, based on the configurationProperties discussed in "MongoDB Connector" in the Connector Reference. By default, it listens on localhost, port 27017. For the purpose of this sample, we'll set up an administrative user of myUserAdmin with a password of Passw0rd in the admin database. We will then create a database in MongoDB named hrdb.

   Note

   The MongoDB administrative user must have the userAdminAnyDatabase role, or attempts to update users will fail.

   If want to use an existing MongoDB instance that runs on a different host or port, or you want to change the database credentials, adjust the configurationProperties in the connector configuration file (samples/sync-with-mongodb/conf/provisioner.openicf-mongodb.json) before you start the sample, as described in "Configuring the MongoDB Connector" in the Connector Reference.

3. Set up the MongoDB database, with which IDM will synchronize its managed user repository, by:

   • Enabling authentication, as described in the following MongoDB document: Enable Auth .

   • Setting up users and roles, as described in this MongoDB document: Manage Users and Roles .

1. Update samples/sync-with-mongodb/conf/provisioner.openicf-mongodb.json with the credentials and database information you created when configuring MongoDB. In our example, database would be set to hrdb, while user would be myUserAdmin with userDatabase set to admin.

2. Start IDM with the configuration for the MongoDB sample:

   $ cd /path/to/openidm
   $ ./startup.sh -p samples/sync-with-mongodb

3. Create at least one assignment and role to assign roles to users. In this example, we are creating a role to assign read privileges to users. The role created is conditional, and only assigned to active users:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Content-type: application/json" \
    --request POST \
    --data '{
      "name" : "MongoDB Read Access",
      "description": "Basic Read Access to HRDB",
      "mapping" : "managedUser_systemMongodbAccount",
      "attributes": [
        {
          "name": "roles",
          "value": [
            {
              "role": "read",
              "db": "hrdb"
            }
          ],
          "assignmentOperation" : "mergeWithTarget",
          "unassignmentOperation" : "removeFromTarget"
        }
      ]
    }' \
   "http://localhost:8080/openidm/managed/assignment?_action=create"
   {
     "_id": "fb98f4a5-0f4d-4e22-9e17-79c45c11fe20",
     "_rev": "000000005c2da0eb",
     "name": "MongoDB Read Access",
     "description": "Basic Read Access to HRDB",
     "mapping": "managedUser_systemMongodbAccount",
     "attributes": [
       {
         "name": "roles",
         "value": [
           {
             "role": "read",
             "db": "hrdb"
           }
         ],
         "assignmentOperation": "mergeWithTarget",
         "unassignmentOperation": "removeFromTarget"
       }
     ]
   }

   $ curl \
    --header "Content-type: application/json" \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request POST \
    --data '{
      "name" : "MongoDB Read Access",
      "description": "Role for accounts with read access in MongoDB.",
      "condition": "/accountStatus eq \"active\"",
      "assignments": [
        {
          "_ref": "managed/assignment/fb98f4a5-0f4d-4e22-9e17-79c45c11fe20",
          "_refResourceCollection": "managed/assignment",
          "_refResourceId": "fb98f4a5-0f4d-4e22-9e17-79c45c11fe20"
        }
      ]
    }' \
    "http://localhost:8080/openidm/managed/role?_action=create"
   {
     "_id": "5f16238e-39e1-4f8c-8b16-27d39dc64dc3",
     "_rev": "0000000011e566a2",
     "name": "MongoDB Read Access",
     "description": "Role for accounts with read access in MongoDB.",
     "condition": "/accountStatus eq \"active\""
   }

4. Create new users in IDM. Note that MongoDB requires user name, password, and roles properties to successfully create a user. In this example, the read role is assigned to new users automatically.

5. Reconcile the managed user repository with the external MongoDB database:

   • To reconcile the repository through the 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.

     2. Select Configure > Mappings.

        The Mappings page shows one mapping: From the IDM Managed User repository to the MongoDB database (managedUser_systemMongodbAccount).

     3. Select the managedUser_systemMongodbAccount mapping, and choose the Reconcile option.

   • 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=managedUser_systemMongodbAccount&waitForCompletion=true"
     {
       "_id": "e5bf074e-4da6-4ea7-8203-d4ec6f5a814a-24344",
       "state": "SUCCESS"
     }

   The reconciliation operation creates MongoDB users from the users found in managed/user.

1. Access the ActiveMQ web console, at http://localhost:8161/admin. Log in as an administrator; the default administrative user and password are admin and admin.

2. In the ActiveMQ web console, in the Queue Name text box, enter the value of idmQ from the messaging.json file in the conf/ subdirectory. The default value for queue.idmQ and destinationName is idmQ. Enter that value and select Create.

3. In the Queues window for the idmQ queue, select the Send To link under Operations.

4. You should see a Send a JMS Message window, with a Message body text box towards the bottom.

5. Copy the following text, a payload to create a new user with a user ID of mgr1, to the Message body text box:

   {
      "operation" : "CREATE",
      "resourceName" : "/managed/user",
      "newResourceId" : "mgr1",
      "content" : {
         "mail" : "mgr1@example.com",
         "sn" : "Sanchez",
         "givenName" : "Jane",
         "password" : "Password1",
         "employeenumber" : 100,
         "accountStatus" : "active",
         "telephoneNumber" : "",
         "roles" : [ ],
         "postalAddress" : "",
         "userName" : "mgr1",
         "stateProvince" : ""
      },
      "params" : {},
      "fields" : [ "*", "*_ref" ]
   }

   For comparison, note the following equivalent REST call to create the same user:

   $ curl \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --header "Content-Type: application/json" \
   --request POST \
   --data '{
        "mail" : "mgr1@example.com",
        "sn" : "Sanchez",
        "givenName" : "Jane",
        "password" : "Password1",
        "employeenumber" : 100,
        "accountStatus" : "active",
        "telephoneNumber" : "",
        "roles" : [ ],
        "postalAddress" : "",
        "userName" : "mgr1",
        "stateProvince" : "",
        "params" : {},
        "fields" : [ "*", "*_ref" ]
   }' \
   "http://localhost:8080/openidm/managed/user?_action=create"

6. Observe the OSGi console. You should see output in two parts. The first part starts with:

   *****request received******
   Parsed JMS JSON =
   ...
       

   The first part should include a JSON-formatted replay of the request that you entered in the Message body text box.

   The second part of the output includes information for that same user, as written to the managed user repository.

7. Confirm that user either in the Admin UI, or via the following REST call:

   $ curl \
   --header "X-OpenIDM-Username: openidm-admin" \
   --header "X-OpenIDM-Password: openidm-admin" \
   --request GET \
   "http://localhost:8080/openidm/managed/user/mgr1"

8. Repeat the process to create additional users. Try a different REST function. For example, you can enter the following payload in the ActiveMQ UI Message body text box, to change the first name (givenName) of the mgr1 user to Donna:

   {
      "operation" : "PATCH",
      "resourceName" : "/managed/user/mgr1",
      "rev" : "",
      "value" : [
         {
            "operation":"replace",
            "field":"/givenName",
            "value": "Donna"
         }
      ]
   }

To install AM, read through the following procedure: To Custom Configure an Instance in the Access Management Installation Guide.

1. Enter a password. The password that you set during the AM installation process becomes the password for the AM administrative user, amadmin. Once the full stack setup is complete, you'll use amadmin and that password to log into IDM.

2. When you see the Server Settings step, verify that the server settings are valid for your configuration. Make sure these settings correspond to the FQDN for your instance of AM. For this sample, you'd specify:

   • Server URL: http://openam.example.com:8080

   • Cookie Domain: openam.example.com

3. Now you should see the Configuration Data Store Settings screen. The defaults allow AM to store configuration data in an embedded directory.

   If you set up the external instance of DS as described in "Preparing an Instance of DS", the Admin Port should be 5444. You'll also need to change the Root Suffix to match the root domain for your instance of AM, in this case, dc=example,dc=com.

   Note

   If your configuration of DS includes a different Root Suffix, modify your AM installation settings accordingly.

4. In the User Data Store Settings screen, configure where AM looks for user identities. In this case, select Other User Data Store and choose DS as the User Data Store type. You can then point this installation to the DS server configured at opendj.example.com, on port 1389, with a root suffix of dc=example,dc=com. Enter the password that you used in this section: "Preparing an Instance of DS".

   AM verifies what you enter in the User Data Store Settings screen with the instance of DS that you created. Once verified, AM then allows you to select Next:

   

5. For this sample, you're installing one instance of AM. So when you reach the Site Configuration screen, accept the default No, and select Next to continue.

6. Complete the AM installation process as directed, until you're logged into AM. For details, see To Custom Configure an Instance in the Access Management Installation Guide.

7. You'll be taken to an AM installation screen. The AM administrative user is amadmin and the password is what you set during the AM installation process.

1. Navigate to http://openidm.example.com:8080/#register/. Be sure to enter the full URL, including the final forward slash /.

2. In the Register Your Account screen that appears, you should see the following options:

   • Register with Google

   • Register with Facebook

3. Select one of these options, and proceed as prompted with either a Google or Facebook account.