This release of OpenIDM requires Java Development Kit 6 or Java Development Kit 7. ForgeRock recommends the most recent update of Java 6 or 7 to ensure that you have the latest security fixes.

The equivalent version of OpenJDK should work for evaluation.

OpenIDM services run in an OSGi container with an embedded Servlet container, and an embedded noSQL database. By default the OSGi container is Apache Felix. The default Servlet container is Jetty. For OpenIDM 3.0.0, the only supported configuration is running the services in Apache Felix and Jetty.

With all curl-based REST calls, OpenIDM returns the JSON object all on one line.

Without a bit of help, the JSON output is formatted all on one line. One example is shown below, and it is difficult to read:

     
      {"mail":"joe@example.com","sn":"smith","passwordAttempts":"0",
      "lastPasswordAttempt":"Mon Apr 14 2014 11:13:37 GMT-0800 (GMT-08:00)",
      "address2":"","givenName":"joe","effectiveRoles":["openidm-authorized"],
      "password":{"$crypto":{"type":"x-simple-encryption","value":{"data":
      "OBFVL9cG8uaLoo1N+SMJ3g==","cipher":"AES/CBC/PKCS5Padding","iv":
      "7rlV4EwkwdRHkt19F8g22A==","key":"openidm-sym-default"}}},"country":"",
      "city":"","_rev":"1","lastPasswordSet":"","postalCode":"","_id":"joe3",
      "description":"My first user","accountStatus":"active","telephoneNumber":
      "555-123-1234","roles":["openidm-authorized"],"effectiveAssignments":{},
      "postalAddress":"","stateProvince":"","userName":"joe3"}
     
    

At least two options are available to clean up this output.

The standard way to format JSON output is with a JSON parser such as jq. You would "pipe" the output of a REST call to jq, as follows:

$ curl \
--cacert self-signed.crt \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"https://localhost:8443/openidm/managed/user/joe" \
| jq .
     
    

The ForgeRock REST API includes an optional _prettyPrint request parameter. The default value is false. To use the ForgeRock REST API to format output, add a parameter such as ?_prettyPrint=true or &_prettyPrint=true, depending on whether it is added to the end of an existing request parameter. In this case, the following command would return formatted output:

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

Note that most command-line examples in this guide do not show this parameter, although the output is formatted for readability.

Each sample directory in openidm/samples/ contains a number of subdirectories, such as conf/ and script/. To start OpenIDM with a sample configuration, navigate to the /path/to/openidm directory and use the -p option of the startup command to point to the sample whose configuration you want to use. Some, but not all samples require additional software, such as an external LDAP server or database.

When you move from one sample to the next, bear in mind that you are changing the OpenIDM configuration.

Install an instance of OpenIDM specifically to try the samples. That way you can experiment as much as you like, and discard the result if you are not satisfied.

If you are using the same instance of OpenIDM for multiple samples, it is helpful to clear out the repository created for an earlier sample. To do so, shut down OpenIDM and delete the openidm/db/openidm directory.

$ rm -rf /path/to/openidm/db/openidm

OpenIDM should now be ready to start with a new sample. For a number of the following samples, users are created either at the UI or with a commons REST call. Once added, and when reconciliation is complete, such users should be able to log into the UI.

Prepare the LDAP server by creating a base suffix of dc=example,dc=com, and importing these objects from samples/sample2/data/Example.ldif.

dn: dc=com
objectClass: domain
objectClass: top
dc: com

dn: dc=example,dc=com
objectClass: domain
objectClass: top
dc: example

dn: ou=People,dc=example,dc=com
ou: people
description: people
objectclass: organizationalunit

dn: uid=jdoe,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
givenName: John
uid: jdoe
cn: John Doe
telephoneNumber: 1-415-523-0772
sn: Doe
mail: jdoe@example.com
description: Created for OpenIDM
userPassword: password

There is an additional user, bjensen in the sample LDIF file. This user is essentially a "dummy" user, provided for compliance with RFC 4519, which stipulates that every groupOfUniqueNames object must contain at least one uniqueMember.

Prepare OpenIDM as described in Section 3.1.2, "Preparing OpenIDM", then start OpenIDM with the configuration for sample 2.

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

Run reconciliation over the REST interface.

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

Successful reconciliation returns a reconciliation run ID.

With the configuration of sample 2, OpenIDM creates user objects from LDAP in OpenIDM, assigning the new objects random unique IDs. To list user objects by ID, run a query over the REST interface.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"

If you want the output to be formatted, include the _prettyPrint=true request parameter or pipe the output to a JSON parser such as jq, otherwise the resulting JSON object appears all on one line.

{
    "result": [
      {
        "_id": "53fbf0c5-aa37-4845-a4b3-92a21810a36d",
        "_rev": "0"
      },
      {
        "_id": "ae0aed26-2a9c-43e3-a6f0-ca707c9c6455",
        "_rev": "0"
      }
    ],
    "resultCount": 2,
    "pagedResultsCookie": null,
    "remainingPagedResults": -1,
 }

You should now be able to review reconciled users in the UI. Point your browser to https://localhost:8443/openidmui, log in as the openidm-admin user (with password openidm-admin), and navigate to the Users tab. Select the user whose profile information you want to see.

Alternatively, you can retrieve individual user objects by ID, as shown here.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/user/53fbf0c5-aa37-4845-a4b3-92a21810a36d"

Configure the LDAP server as for sample 2, Section 3.3.1, "LDAP Server Configuration". The LDAP user must have write access to create users from OpenIDM on the LDAP server.

When configuring the LDAP server, be sure to import the appropriate LDIF file, in this case, /path/to/openidm/samples/sample2b/data/Example.ldif

Prepare OpenIDM as described in Section 3.1.2, "Preparing OpenIDM", then start OpenIDM with the configuration for sample 2b.

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

Run reconciliation over the REST interface.

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

Successful reconciliation returns a reconciliation run ID.

With the configuration of sample 2b, OpenIDM creates user objects from LDAP in OpenIDM, assigning the new objects random unique IDs. To list user objects by ID, run a query over the REST interface.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"
   

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

{
  "result": [
    {
      "_id": "53fbf0c5-aa37-4845-a4b3-92a21810a36d"
      "_rev": "0",
    },
    {
      "_id": "6490489f-bbff-4855-808a-5c1862b09339"
      "_rev": "0",
    }
    "resultCount": 2,
    "pagedResultsCookie": null,
    "remainingPagedResults": -1,
],
 }

To retrieve the user, log into the UI, on an URI such as https://localhost:8443/openidmui as the administrative user

Alternatively, you can make a commons REST call to get a specific user object by ID.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/user/53fbf0c5-aa37-4845-a4b3-92a21810a36d"

Test the second mapping by creating a user in the OpenIDM repository. On UNIX:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{
    "mail":"fdoe@example.com",
    "sn":"Doe",
    "telephoneNumber":"555-1234",
    "userName":"fdoe",
    "givenName":"Felicitas",
    "description":"Felicitas Doe",
    "displayName":"fdoe"}' \
 "https://localhost:8443/openidm/managed/user?_action=create"

On Windows:

$ curl ^
 --cacert self-signed.crt ^
 --header "X-OpenIDM-Username: openidm-admin" ^
 --header "X-OpenIDM-Password: openidm-admin" ^
 --header "Content-Type: application/json" ^
 --request POST ^
 --data "{
  \"mail\":\"fdoe@example.com\",
  \"sn\":\"Doe\",
  \"telephoneNumber"\:\"555-1234\",
  \"userName\":\"fdoe\",
  \"givenName\":\"Felicitas\",
  \"description\":\"Felicitas Doe\",
  \"displayName\":\"fdoe\"}" ^
 "https://localhost:8443/openidm/managed/user?_action=create"

By default, automatic synchronization is enabled. 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 Synchronization Mappings File in the Integrator's Guide in the Integrator's Guide.

Test that the automatic reconciliation has been successful by locating the new user in the LDAP directory.

$ /path/to/OpenDJ/bin/ldapsearch \
 -bindDN "cn=Directory Manager" \
 -bindPassword password \
 -hostname localhost \
 -port 1389 \
 -baseDN "dc=example,dc=com" \
 "uid=fdoe" 
dn: uid=fdoe,ou=People,dc=example,dc=com
mail: fdoe@example.com
givenName: Felicitas
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
uid: fdoe
cn: Felicitas Doe
sn: Doe
   

Configure the LDAP server as for sample 2, Section 3.3.1, "LDAP Server Configuration". The LDAP user must have write access to create users from OpenIDM on the LDAP server.

In addition, two LDAP Groups should be created, which can be found in the LDIF file: openidm/samples/sample2c/data/Example.ldif:

dn: ou=Groups,dc=example,dc=com
ou: Groups
objectClass: organizationalUnit
objectClass: top

dn: cn=openidm,ou=Groups,dc=example,dc=com
uniqueMember: uid=jdoe,ou=People,dc=example,dc=com
cn: openidm
objectClass: groupOfUniqueNames
objectClass: top

dn: cn=openidm2,ou=Groups,dc=example,dc=com
uniqueMember: uid=bjensen,ou=People,dc=example,dc=com
cn: openidm2
objectClass: groupOfUniqueNames
objectClass: top

The users with DNs uid=jdoe,ou=People,dc=example,dc=com and uid=bjensen,ou=People,dc=example,dc=com are also imported with the Example.ldif file. (The user bjensen is essentially a "dummy" user, provided for compliance with RFC 4519, which stipulates that every groupOfUniqueNames object must contain at least one uniqueMember. User bjensen is not actually used in this sample.)

Prepare OpenIDM as described in Section 3.1.2, "Preparing OpenIDM", then start OpenIDM with the configuration for sample 2c.

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

Run reconciliation over the REST interface.

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

Successful reconciliation returns a reconciliation run ID.

With the configuration of sample 2c, OpenIDM creates user objects from LDAP in OpenIDM, assigning the new objects random unique IDs. To list user objects by ID, run a query over the REST interface.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"
   

The resulting JSON object should appear similar to the following:

{
  "result": [
    {
      "_id": "53fbf0c5-aa37-4845-a4b3-92a21810a36d"
      "_rev": "0",
    }
    {
      "_id": "56f0fb7e-3837-464d-b9ec-9d3b6af665c3",
      "_rev": "0"
    }
    ]
    "resultCount": 2,
    "pagedResultsCookie": null,
    "remainingPagedResults": -1,
 }

You should now be able to retrieve John Doe's user object in the UI, navigating to the domain for OpenIDM such as https://localhost:8443/openidmui. Alternatively, you can retrieve John Doe's user object at the command line by his ID.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/user/53fbf0c5-aa37-4845-a4b3-92a21810a36d"

The user object should contain a property like:

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

Now change the user on the OpenIDM side with the following REST call (on UNIX):

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '[
    {
      "operation":"replace",
      "field":"/ldapGroups",
      "value": ["cn=openidm2,ou=Groups,dc=example,dc=com"]
    }
 ]' \
 "https://localhost:8443/openidm/managed/user?_action=patch&_queryId=for-userName&uid=jdoe"

On Windows, you might need to escape certain characters, so your REST call would look like this:

$ curl ^
 --cacert self-signed.crt ^
 --header "X-OpenIDM-Username: openidm-admin" ^
 --header "X-OpenIDM-Password: openidm-admin" ^
 --header "Content-Type: application/json" ^
 --request POST ^
 --data "[
    {
    \"operation\":\"replace\",
    \"field\":\"\/ldapGroups\",
    \"value\": [\"cn=openidm2,ou=Groups,dc=example,dc=com\"]
    }
 ]" ^
 "https://localhost:8443/openidm/managed/user?_action=patch&_queryId=for-userName&uid=jdoe"

This will change the user's ldapGroups property in OpenIDM from "cn=openidm,ou=Groups,dc=example,dc=com" to "cn=openidm2,ou=Groups,dc=example,dc=com" and, as a result, the user will be removed from the one LDAP group and added to the other LDAP group on OpenDJ.

Retrieve John Doe's user object again and notice the changed "ldapGroups" property.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/user/56f0fb7e-3837-464d-b9ec-9d3b6af665c3"

By default, automatic synchronization is enabled. 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 Synchronization Mappings File in the Integrator's Guide in the Integrator's Guide.

Configure the LDAP server as for sample 2, Section 3.3.1, "LDAP Server Configuration". The LDAP user must have write access to create users from OpenIDM on the LDAP server.

In addition, two LDAP Groups should be created, which can be found in the LDIF file: openidm/samples/sample2d/data/Example.ldif (if they have not already been added through sample 2c):

dn: ou=Groups,dc=example,dc=com
ou: Groups
objectClass: organizationalUnit
objectClass: top

dn: cn=openidm,ou=Groups,dc=example,dc=com
uniqueMember: uid=jdoe,ou=People,dc=example,dc=com
cn: openidm
objectClass: groupOfUniqueNames
objectClass: top

dn: cn=openidm2,ou=Groups,dc=example,dc=com
uniqueMember: uid=bjensen,ou=People,dc=example,dc=com
uniqueMember: uid=jdoe,ou=People,dc=example,dc=com
cn: openidm2
objectClass: groupOfUniqueNames
objectClass: top

The user with dn uid=jdoe,ou=People,dc=example,dc=com is also imported with the Example.ldif file.

There is an additional user, bjensen in the sample LDIF file. This user is essentially a "dummy" user, provided for compliance with RFC 4519, which stipulates that every groupOfUniqueNames object must contain at least one uniqueMember. bjensen is not actually used in this sample.

Prepare OpenIDM as described in Section 3.1.2, "Preparing OpenIDM", then start OpenIDM with the configuration for sample 2d.

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

Run reconciliation for the groups mapping over the REST interface.

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

Successful reconciliation returns a reconciliation run ID.

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

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

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

{
   "result":[
      {
         "_id":"3c704429-aacd-4995-816a-fac33451c642"
         "_rev": "0",
      },
      {
         "_id":"b0982152-5099-4358-bdd1-45a39ebe0d77"
         "_rev": "0",
      }
   ]
    "resultCount": 2,
    "pagedResultsCookie": null,
    "remainingPagedResults": -1,
}

To retrieve a group, get the object by ID.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/group/b0982152-5099-4358-bdd1-45a39ebe0d77"

Your group's object should be similar to the following:

{
    "name": [
      "openidm"
    ],
    "uniqueMember": [
      "uid=jdoe,ou=People,dc=example,dc=com"
    ],
    "description": [],
    "dn": "cn=openidm,ou=Groups,dc=example,dc=com",
    "_rev": "0",
    "_id": "b0982152-5099-4358-bdd1-45a39ebe0d77"
}
   

In this example OpenIDM communicates with an external MySQL database server.

Make sure MySQL is running.

Once imported, you can review the contents of the sample in MySQL. The following command accesses the MySQL prompt:

$ mysql -u root -p

From the mysql > prompt, use the following commands to review the users configured in the sample_HR_DB.mysql file:

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. ...
     |  2 | rowley | 2aa60a8ff... | Rowley    | Birkin   | Rowley Birkin | Rowl ...
     |  3 | louis  | 1119cfd37... | Louis     | Balfour  | Louis Balfour | Loui ...
     |  4 | john   | a1d7584da... | John      | Smith    | John Smith    | John ...
     |  5 | jdoe   | edba955d0... | John      | Doe      | John Doe      | John ...
     +----+--------+------------------------------------------+-----------+---- ...
     5 rows in set (0.01 sec)
    
    

You can exit from the MySQL prompt with the quit command.

The sample 3 sync.json configuration file contains a mapping to reconcile OpenIDM and the external database. Run the reconciliation with the following command.

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

Reconciliation creates the five users from the database in the OpenIDM repository. Check the result with the following command.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"

The output includes the identifier _id for each user.

{
    "result": [ {
        "_id": "8366a23d-f6cf-46df-9746-469bf45aafcd",
        "_rev": "0"
    },
    {
        "_id": "3f90933b-9397-4897-84d0-03ed8d99f61e",
        "_rev": "0"
    },
    {
        "_id": "8fbf759d-bebc-42ed-b321-b69487b4470f",
        "_rev": "0"
    },
    {
        "_id": "9592de42-a8ef-4db3-9c6c-7d191e39b084",
        "_rev": "0"
    },
    {
        "_id": "d933441b-684b-446c-a89e-01eca6d21ef3",
        "_rev": "0"
    },
    {
        "_id": "fd962b71-752a-444b-8492-35bff57bec69",
        "_rev": "0"
    } ],
    "resultCount": 6,
    "pagedResultsCookie": null,
    "remainingPagedResults": -1
}

You can get more information about users with any of the following three methods:

You can review the users from the UI, navigating to the domain where OpenIDM is installed, with a URL similar to https://localhost:8443/openidmui

Alternatively, to view all fields for a single user, based on its _id, run the following command:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/user/8366a23d-f6cf-46df-9746-469bf45aafcd"

You can query specific fields with a REST call. For example, the following command displays the unique ID and the givenName of all managed users:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/user?_queryId=query-all&fields=_openidm_id,givenName"

No external configuration is required for this sample. Prepare OpenIDM as described in Section 3.1.2, "Preparing OpenIDM", then start up OpenIDM with the configuration of sample 4.

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

The sample4/data/hr.csv file contains two example users. The first line of the file sets the attribute names.

Review the current contents of the database in the sample4/data/xmlConnectorData.xml file. For comparison purposes, make a copy of the file in a temporary directory with a command like:

$ cp /path/to/openidm/samples/sample4/data/xmlConnectorData.xml /tmp/

The reconciliation command run here uses the information from the hr.csv file to update the database in the sample4/data/xmlConnectorData.xml file.

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

Check the results of reconciliation. Review the updated contents of the sample4/data/xmlConnectorData.xml file.

If you want to experiment further, try changing the data in the hr.csv file. Run the noted reconciliation command again.

These users will not be visible from the OpenIDM UI, since they are mapped directly between the XML and CSV files. The internal OpenIDM repository is not updated in this sample.

If you do not configure the email service, the functionality of the sample does not change. However, you might see the following message at the OpenIDM console when you run a reconciliation operation:

Email service not configured; report not generated.

No external configuration is required for this sample. Prepare OpenIDM as described in Section 3.1.2, "Preparing OpenIDM", then start OpenIDM with the configuration of sample 5.

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

The XML files that simulate the resources are located in the openidm/samples/sample5/data/ folder. When you start OpenIDM with the sample 5 configuration, OpenIDM creates the xml_AD_Data.xml file, which does not contain users until you run reconciliation.

Run a reconciliation operation, to synchronize the contents of the simulated LDAP resource to the OpenIDM repository.

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

This command creates a user in the repository. It is not necessary to run a second reconciliation operation to synchronize the AD resource. Automatic synchronization propagates any change made to managed users in the OpenIDM repository to the simulated AD resource.

Review the contents of xml_AD_Data.xml. It should now contain information for the same user that was present in the startup version of the xml_LDAP_Data.xml file.

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

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/system/ad/account?_queryId=query-all-ids"
   
   {
  "result" : [ {
    "name" : "DDOE1",
    "__UID__" : "8dad9df3-820d-41ea-a3ab-a80c241bbc98",
    "_id" : "8dad9df3-820d-41ea-a3ab-a80c241bbc98"
  } ],
    "resultCount" : 1,
    "pagedResultsCookie" : null,
    "remainingPagedResults" : -1
}
   

You can use the _id of the user to read the user information from the AD resource, for example:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/system/ad/account/8dad9df3-820d-41ea-a3ab-a80c241bbc98"
   
   {
  "email" : [ "mail1@example.com" ],
  "name" : "DDOE1",
  "__UID__" : "8dad9df3-820d-41ea-a3ab-a80c241bbc98",
  "firstname" : "Darth",
  "lastname" : "Doe",
  "_id" : "8dad9df3-820d-41ea-a3ab-a80c241bbc98"
}[

To verify that the sample is working, repeat the process. Set up a second user in the xml_LDAP_Data.xml file. An example of how that file might appear with a second user (GDOE1) is shown here:

<?xml version="1.0" encoding="UTF-8"?>
<icf:OpenICFContainer
    xmlns:icf="http://openidm.forgerock.com/xml/ns/public/resource/openicf/resource-schema-1.xsd"
    xmlns:ri="http://openidm.forgerock.com/xml/ns/public/resource/instances/resource-schema-extension"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://openidm.forgerock.com/xml/ns/public/resource/instances/resource-schema-extension
    samples/sample5/data/resource-schema-extension.xsd
    http://openidm.forgerock.com/xml/ns/public/resource/openicf/resource-schema-1.xsd
    data/resource-schema-1.xsd">
    <ri:__ACCOUNT__>
       <icf:__UID__>1</icf:__UID__>
       <icf:__PASSWORD__>TestPassw0rd2</icf:__PASSWORD__>
       <ri:firstname>Darth</ri:firstname>
       <icf:__DESCRIPTION__>Created By XML1</icf:__DESCRIPTION__>
       <icf:__NAME__>DDOE1</icf:__NAME__>
       <ri:email>mail1@example.com</ri:email>
       <ri:lastname>Doe</ri:lastname>
    </ri:__ACCOUNT__>
    <ri:__ACCOUNT__>
       <icf:__UID__>2</icf:__UID__>
       <icf:__PASSWORD__>TestPassw0rd2</icf:__PASSWORD__>
       <ri:firstname>Garth</ri:firstname>
       <icf:__DESCRIPTION__>Created By XML1</icf:__DESCRIPTION__>
       <icf:__NAME__>GDOE1</icf:__NAME__>
       <ri:email>mail2@example.com</ri:email>
       <ri:lastname>Doe</ri:lastname>
    </ri:__ACCOUNT__>
</icf:OpenICFContainer>

Rerun the reconciliation and query REST commands shown previously. The reconciliation operation creates the new user from the simulated LDAP resource in the OpenIDM repository. Automatic synchronization then creates that user in the AD resource.

No external configuration is required for this sample. Prepare OpenIDM as described in Section 3.1.2, "Preparing OpenIDM", then start OpenIDM with the configuration of sample 5b.

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

The XML files that simulate an external LDAP and AD resource are now located in the openidm/samples/sample5b/data/ directory. The simulated AD data store file, xml_AD_Data.xml, does not contain users until you run reconciliation.

Run the sample in exactly the same way that you did for Sample 5, following the steps in Section 3.9.3, "Run the Sample".

To demonstrate integration of the samples with the OpenIDM UI, this sample uses the UI to view and make changes to user objects in the repository. However, you can also use the REST interface to make these changes, as shown in the previous section.

Log into the OpenIDM UI as the administrative user. On a local system, navigate to https://localhost:8443/openidmui. The default administrative account and password are both openidm-admin.

Make a change to the data of an existing user (DDOE1). With automatic synchronization, that change is reflected almost immediately on the external resources. For sample 5b, you should see the changes in both XML files in the /path/to/openidm/sample5b/data directory. Alternatively, you can query the external resources over REST, as described previously.

The synchronization is successful, across all configured external resources, so the updated user record can be seen in both the xml_LDAP_Data.xml and xml_AD_Data.xml files.

The next step is to simulate a problem connecting to the LDAP resource. One way to do so on the local system is to rename the LDAP data file so that it is unreadable. On a Linux system, the following command, as an administrative user, would serve that purpose:

$ cd /path/to/openidm/samples/sample5b/data
$ sudo mv xml_LDAP_Data.xml xml_LDAP_Data.xml.bak

In the UI, now try another update to user DDOE1. With the modified filename of the simulated LDAP resource, automatic synchronization cannot write to this resource. An error similar to the following is displayed in the log file, openidm0.log.0:

Data file does not exist:
/path/to/openidm/samples/sample5b/data/xml_LDAP_Data.xml

Although the AD resource is available, automatic synchronization will not reach this resource, because the mapping is specified after the managed/user to LDAP mapping in the sync.json file.

When the automatic synchronization fails for the LDAP resource, the onSync hook invokes the compensate.js script. This script attempts to revert the original change by performing another update to DDOE1 in the repository (managed/user). This change, in turn, triggers another automatic synchronization to the AD and LDAP resources.

Because the LDAP resource is still unreadable, the synchronization to LDAP fails again, which triggers the compensate.js script again. This time, however, the script recognizes that the change was originally called as a result of a compensation and aborts.

The original synchronization error from the first update is thrown from the script and the UI should display that error. If you refresh the UI, and view that user entry again, you will notice that the change to the entry has been reverted.

Note that if you change the name of the AD resource file (to make it unavailable), a change to a managed/user entry will be synchronized successfully with the LDAP resource (because that mapping appears first in sync.json). The synchronization will fail for the AD resource. In this case, the change will be reverted on both the managed/user entry, and the LDAP resource.

If you have an existing, active instance of AD, set up OpenDJ, as described in the OpenDJ Installation Guide.

During installation, populate OpenDJ with the data in the Example.ldif file, available in the /path/to/sample6/data directory.

The actions run in this sample should not change any data on the AD server.

In this sample, an AD deployment is simulated with a different baseDN (dc=fakead,dc=com) on the same OpenDJ server instance. You can also simulate the AD server with a separate OpenDJ instance, running on the same host, as long as the two instances communicate on different ports. The data for the simulated AD instance is contained in the file AD.ldif. The data for the OpenDJ instance is contained in the file Example.ldif.

Now that OpenDJ and a real or simulated AD database is configured, prepare OpenIDM as described in Section 3.1.2, "Preparing OpenIDM". You can then start OpenIDM with the configuration for sample 6.

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

The following sections show how to run the sample with command-based reconciliation with a REST call, and to configure scheduled reconciliation with LiveSync.

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

{"_id":"9ece3807-08c3-4ec6-87fb-a6a2d0c71cee"}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/system/ldap/account?_queryId=query-all-ids"

{
  "result": [ {
     "dn" : "uid=jdoe,ou=People,dc=example,dc=com",
     "_id" : "uid=jdoe,ou=People,dc=example,dc=com"
     }, {
     "dn" : "uid=bjensen,ou=People,dc=example,dc=com",
     "_id" : "uid=bjensen,ou=People,dc=example,dc=com"
    } ],
  "resultCount": 2,
  "pagedResultsCookie": null,
  "remainingPagedResults": -1,
}

$ ./ldapsearch \
 --port 1389 \
 --baseDN dc=example,dc=com \
 "(uid=jdoe)"

{
    "enabled" : false,
    "type" : "cron",
    "schedule" : "0/15 * * * * ?",
    "invokeService" : "provisioner",
    "invokeContext" : {
        "action" : "liveSync",
        "source" : "system/ad/account"
    },
    "invokeLogLevel" : "debug"
}

Prepare OpenIDM as described in Section 3.1.2, "Preparing OpenIDM", then start OpenIDM with the configuration for sample 7.

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

Run a reconciliation to pull the user from samples/sample7/data/xmlConnectorData.xml into the OpenIDM internal repository.

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

Reconciliation creates a user object in the repository. Retrieve the user from the repository.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/user/DDOE1"

The user object has the following JSON representation.

{
  "_id" : "DDOE1",
  "_rev" : "2",
  "schemas" : "['urn:scim:schemas:core:1.0']",
  "ims" : [ {
    "type" : "aim",
    "value" : "jonyOnAim"
  }, {
    "type" : "skype",
    "value" : "skyperHiasl"
  } ],
  "locale" : null,
  "phoneNumbers" : [ {
    "type" : "work",
    "value" : "1234567"
  }, {
    "type" : "home",
    "value" : "1234568"
  } ],
  "emails" : [ {
    "type" : "work",
    "value" : "hallo@example.com",
    "primary" : true
  }, {
    "type" : "home",
    "value" : "jdoe@forgerock.com"
  } ],
  "externalId" : "DDOE1",
  "preferredLanguage" : "en_US",
  "meta" : {
    "lastModified" : "Thu May 01 2014 12:57:10 GMT-0800 (GMT-08:00)",
    "created" : "Thu May 01 2014 12:56:27 GMT-0800 (GMT-08:00)"
  },
  "userType" : "permanent",
  "photos" : [ {
    "type" : "photo",
    "value" : "https://photos.example.com/profilephoto/72930000000Ccne/F"
  }, {
    "type" : "thumbnail",
    "value" : "https://photos.example.com/profilephoto/72930000000Ccne/T"
  } ],
  "title" : "Mr.Universe",
  "timezone" : "America/Denver",
  "profileUrl" : "https://login.example.com/DDOE1",
  "nickName" : "Jonny",
  "name" : {
    "familyName" : "Doe",
    "middleName" : "Hias",
    "formatted" : "Dr. John H Doe III",
    "givenName" : "John",
    "honorificSuffix" : "III",
    "honorificPrefix" : "Dr."
  },
  "userName" : "DDOE1",
  "displayName" : "John Doe",
  "addresses" : [ {
    "streetAddress" : "100 Universal City Plaza",
    "region" : "CA",
    "formatted" : "100 Universal City Plaza\nHollywood, CA 91608 USA",
    "postalCode" : "91608",
    "primary" : "true",
    "locality" : "Hollywood",
    "type" : "work",
    "country" : "USA"
  }, {
    "streetAddress" : "222 Universal City Plaza",
    "region" : "CA",
    "formatted" : "222 Universal City Plaza\nHollywood, CA 91622 USA",
    "postalCode" : "91622",
    "primary" : "false",
    "locality" : "Hollywood",
    "type" : "home",
    "country" : "USA"
  } ],
  "groups" : [ {
    "value" : "usemploys",
    "display" : "US Employees"
  }, {
    "value" : "euemploys",
    "display" : "EU Employees"
  } ]
}

The sample script file, scim.js in the /path/to/samples/sample7/script directory, transforms the user data from the resource into the JSON object layout required by SCIM schema.

Prepare OpenIDM as described in Section 3.1.2, "Preparing OpenIDM", then start OpenIDM with the configuration for sample 8.

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

The sync.json file in the /path/to/samples/sample8/conf directory includes brief examples of log messages.

Run reconciliation over the REST interface.

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

Successful reconciliation returns a reconciliation run ID.

Notice the log messages displayed on the OpenIDM (Felix) console. The following example omits timestamps and so forth to show only the message strings.

->
...Case no Source: the source object contains: = null [5235432-...
...Case emptySource: the source object contains: = {lastname=Carter, mobile...
...Case sourceDescription: the source object contains: = Created By XML1
...Case onCreate: the source object contains: = {lastname=Carter, mobile...
...Case result: the source object contains: = {SOURCE_IGNORED={count=0, ids=[]},...

Prepare OpenIDM as described in Section 3.1.2, "Preparing OpenIDM", then start OpenIDM with the configuration for sample 9.

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

Generic mapping speeds up development, and can make system maintenance more flexible by providing a more stable database structure. However, generic mapping can have a performance impact and does not take full advantage of the database facilities (such as validation within the database and flexible indexing). In addition, queries can be more difficult to set up.

In a generic table, the entire object content is stored in a single large-character field named "fullobject" in the "mainTable" for the object. To search on specific fields, you can read them by referring to them in the corresponding properties table for that object. The disadvantage of generic objects is that, because every property you might like to filter by is stored in a separate table, you must join to that table each time you need to filter by anything.

The following diagram shows a pared down database structure for the default generic table, and indicates the relationship between the main table and the corresponding properties table for each object.

These separate tables can make the query syntax particularly complex. For example, a simple query to return user entries based on a user name would need to be implemented as follows:

SELECT fullobject FROM ${_dbSchema}.${_mainTable} obj INNER JOIN ${_dbSchema}.${_propTable} prop
    ON obj.id = prop.${_mainTable}_id INNER JOIN ${_dbSchema}.objecttypes objtype
    ON objtype.id = obj.objecttypes_id WHERE prop.propkey='/userName' AND prop.propvalue = ${uid}
    AND objtype.objecttype = ${_resource}",
   

The query can be broken down as follows:

Tables for user definable objects use a generic mapping by default.

The following sample generic mapping object illustrates how managed/ objects are stored in a generic table.

  "genericMapping" : {
      "managed/*" : {
          "mainTable" : "managedobjects",
          "propertiesTable" : "managedobjectproperties",
          "searchableDefault" : true,
          "properties" : {
              "/picture" : {
                  "searchable" : false
              }
          }
      }
  },
   

By default, all properties in a generic mapping are searchable. Although there are no individual indexes in a generic mapping, you can improve search performance by setting only those properties that you need to search as "searchable". Properties that are searchable are created within the corresponding properties table. The properties table exists only for searches or look-ups, and has a composite index, based on the resource, then the property name.

To restrict searches to specific properties, set the "searchableDefault" to false for the mapping, and then explicitly set "searchable" to true for each property that should be searched. The following sample extract from repo.jdbc.json indicates searches restricted to the "userName" property.

"genericMapping" : {
    "managed/user" : {
        "mainTable" : "manageduserobjects",
        "propertiesTable" : "manageduserobjectproperties",
        "searchableDefault" : false,
        "properties" : {
            "/userName" : {
            "searchable" : true
            }
        }
    }
},
   

With this configuration, OpenIDM creates entries in the properties table only for "userName" properties of managed user objects.

If the global "searchableDefault" is set to false, properties that do not have a searchable attribute explicitly set to true are not written in the properties table.

Explicit mapping is more difficult to set up and maintain, but can take complete advantage of the native database facilities.

An explicit table offers better performance and simpler queries. There is less work in the reading and writing of data, since the data is all in a single row of a single table. In addition, it is easier to create different types of indexes that apply to only specific fields in an explicit table. The disadvantage of explicit tables is the additional work required in creating the table in the schema. Also, because rows in a table are inherently more simple, it is more difficult to deal with complex objects. Any non-simple key:value pair in an object associated with an explicit table is converted to a JSON string and stored in the cell in that format. This makes the value difficult to use, from the perspective of a query attempting to search within it.

Note that it is possible to have a generic mapping configuration for most managed objects, and to have an explicit mapping that overrides the default generic mapping in certain cases. The sample configuration provided in /path/to/openidm/samples/misc/repo.jdbc-mysql-explicit-managed-user.json has a generic mapping for managed objects, but an explicit mapping for managed user objects.

OpenIDM uses explicit mapping for internal system tables, such as the tables used for auditing.

Depending on the types of usage your system is supporting, you might find that an explicit mapping performs better than a generic mapping. Operations such as sorting and searching (such as those performed in the default UI) tend to be faster with explicitly-mapped objects, for example.

The following sample explicit mapping object illustrates how internal/user objects are stored in an explicit table.

"explicitMapping" : {
    "internal/user" : {
        "table" : "internaluser",
        "objectToColumn" : {
            "_id" : "objectid",
            "_rev" : "rev",
            "password" : "pwd",
            "roles" : "roles"
        }
    },
    ...
}