This section covers what you need to know before running OpenIDM.

Follow the procedures in this section to install and run OpenIDM.

Install and start OpenIDM as described in the chapter on Installing OpenIDM Services.

OpenIDM comes with an internal noSQL database, OrientDB for use as the internal repository out of the box. This makes it easy to get started with OpenIDM. OrientDB is not yet supported for production use, however, so use a supported JDBC database when moving to production.

If you want to query the internal noSQL database, download and unzip OrientDB 1.0. Once you have downloaded and unzipped OrientDB, you can find the shell console in the bin directory. Start OrientDB console using either console.sh or console.bat, and then connect to the running OpenIDM with the connect command.

$ /path/to/orientdb-1.0rc6/bin/console.sh
>
> connect remote:localhost/openidm admin admin

Connecting to database [remote:localhost/openidm:localhost/openidm] with user 'admin'...OK

>

OpenIDM connects identity data objects held in external resources by mapping one object to another. To connect to external resources, OpenIDM uses OpenICF connectors configured for use with the external resources.

When objects in one external resource change, OpenIDM determines how the changes affect other objects, and can make the changes as necessary. This sample demonstrates how OpenIDM does this by using reconciliation and synchronization. OpenIDM reconciliation compares objects in one object set to mapped objects in another object set. Reconciliation can work in write mode, where OpenIDM writes changes to affected objects, or in report mode, where OpenIDM reports on what changes would be written without making the changes. OpenIDM synchronization reflects changes in objects to any mapped objects, making changes as necessary to create or remove mapped objects and links to associate them. For a more thorough explanation of reconciliation and synchronization, the section on Types of Synchronization in the Integrator's Guide in the Integrator's Guide.

This sample connects to an XML file holding sample user data. The XML file is configured as the authoritative source. In this sample, users are created in the local repository to show you how you can manage local users through the REST APIs. You can also use OpenIDM without storing managed objects for users in the local repository, instead reconciling and synchronizing objects directly through connectors to external resources.

Furthermore, this sample involves only one external resource. In practice, you can connect as many resources as needed for your deployment.

If OpenIDM is not running, start it as described in the procedure To Start OpenIDM Services.

Reconcile the objects in the resources either by editing conf/sync.json to set "enabled" : true and then waiting until the scheduled reconciliation happens, or by using the REST interface.

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

To see what happened, review CSV format log, openidm/audit/recon.csv.

After reconciliation runs, you can use the REST interface to display all users in the local repository, by performing an HTTP GET on the following URL: http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids.

OpenIDM returns a JSON file. Depending on your browser, it can display the JSON or download it as a file. Alternatively, you can use the following curl command to get the JSON file.

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids

{
 "query-time-ms":1,
 "result":[
  {
   "_id":"joe",
   "_rev":"0"
  },{
   "_id":"DDOE1",
   "_rev":"0"
  }],
 "conversion-time-ms":0
 }

If you created user joe as described previously in this guide, you see IDs for two users, the second user DDOE1 created during reconcililation. Now try a RESTful GET of user DDOE1 by appending the user ID to the managed user URL, http://localhost:8080/openidm/managed/user/.

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 http://localhost:8080/openidm/managed/user/DDOE1

{
 "familyName": "Doe1",
 "userName": "DDOE1",
 "givenName": "Darth1",
 "_id": "DDOE1",
 "_rev": "0",
 "email": [ "mail1@example.com" ],
 "description": "Created By XML1"
 }

In the OrientDB console, connect to the database, and then query the users and audit logs. The following shows edited excerpts from a console session querying OrientDB.

> connect remote:localhost/openidm admin admin
Connecting to database [remote:localhost/openidm:localhost/openidm] with user 'admin'...OK

> select * from managed_user

---+---------+--------------------+...+--------------------+--------------------
  #| RID     |familyName          |...|email               |description         
---+---------+--------------------+...+--------------------+--------------------
  0|     #6:0|smith               |...|[1]                 |My first user       
  1|     #6:1|Doe1                |...|[1]                 |Created By XML1     
---+---------+--------------------+...+--------------------+--------------------

2 item(s) found. Query executed in 0.011 sec(s).

> select * from audit_activity

---+---------+--------------------+--------------------+--------------------+...
  #| RID     |rev                 |status              |timestamp           |...
---+---------+--------------------+--------------------+--------------------+...
  0|    #11:0|0                   |SUCCESS             |2011-12-02T07:34:19 |...
  1|    #11:1|0                   |SUCCESS             |2011-12-02T07:34:46 |...
---+---------+--------------------+--------------------+--------------------+...

2 item(s) found. Query executed in 0.013 sec(s).

> select * from audit_recon

---+---------+--------------------+--------------------+--------------------+...
  #| RID     |timestamp           |sourceObjectId      |_openidm_id         |...
---+---------+--------------------+--------------------+--------------------+...
  0|    #12:0|2011-12-02T07:34:46 |system/xmlfile/account/1|02f5c8fd-0cc4-4a5...
  1|    #12:1|2011-12-02T07:34:46 |null                |4707745d-6b10-4c75-9b...
---+---------+--------------------+--------------------+--------------------+...

2 item(s) found. Query executed in 0.01 sec(s).

Again, this information is also available in the CSV format audit logs located in the openidm/audit directory.

$ ls /path/to/openidm/audit/
access.csv activity.csv recon.csv

Add a user to the source connector XML data file to see reconciliation in action. During the next reconciliation, OpenIDM finds the new user in the source connector, and creates the user in the local repository. To add the user, copy the following XML into openidm/samples/sample1/data/xmlConnectorData.xml.

<ri:__ACCOUNT__>
   <icf:__UID__>12345</icf:__UID__>
   <icf:__NAME__>Daffy Duck</icf:__NAME__>
   <icf:__PASSWORD__>123456789</icf:__PASSWORD__>
   <ri:email>daffy.duck@forgerock.com</ri:email>
   <ri:lastname>Duck</ri:lastname>
   <ri:firstname>Daffy</ri:firstname>
</ri:__ACCOUNT__>

Run reconciliation as described in the section on Running Reconciliation. After reconciliation has run, query the local repository to see the new user appear in the list of all users under http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids.

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids

{
 "query-time-ms":1,
 "result":[{
    "_id":"DDOE1",
    "_rev":"0"
   },{
   "_id":"joe",
   "_rev":"0"
   },{
    "_id":"Daffy Duck",
    "_rev":"0"
   }],
 "conversion-time-ms":0
 }

Also look at the reconciliation audit log, openidm/audit/recon.csv to see what took place during reconciliation. This formatted excerpt from the log covers two reconciliation runs.

"_id",  "action",...,"reconId","situation","sourceObjectId",...,              "targetObjectId","timestamp";
"02...","CREATE",...,"cc0...", "ABSENT",   "system/xmlfile/account/1",...,    "managed/user/DDOE1",...;
"47...","IGNORE",...,"cc0...", "UNQUALIFIED",""            ,...,              "managed/user/joe",...;
"79...","UPDATE",...,"d15...", "CONFIRMED","system/xmlfile/account/1",...,    "managed/user/DDOE1",...;
"af...","CREATE",...,"d15...", "ABSENT",   "system/xmlfile/account/12345",...,"managed/user/Daffy Duck",...;
"23...","IGNORE",...,"d15...", "UNQUALIFIED","",...,                          "managed/user/joe",...;

The important fields in the audit log are the action, the situation, the source sourceObjectId, and the target targetObjectId. For each object in the source, reconciliation results in a situation that leads to an action on the target.

In the first reconciliation run (the abbreviated reconID is shown as cc0...), the source object does not exist in the target, resulting in an ABSENT situation and an action to CREATE the object in the target. The object created earlier in the target does not exist in the source, and so is IGNORED.

In the second reconciliation run (the abbreviated reconID is shown as d15...) after you added a user to the source XML, OpenIDM performs an UPDATE on the user object DDOE1 that already exists in the target, in this case changing the internal ID. OpenIDM performs a CREATE on the target for the new user.

You configure the action that OpenIDM takes based on an object's situation in the configuration file, conf/sync.json. For the list of all possible situations and actions, see the Configuring Synchronization in the Integrator's Guide chapter in the Integrator's Guide.

For details on auditing, see the Using Audit Logs in the Integrator's Guide chapter in the Integrator's Guide.

You can also add users directly to the local repository through the REST interface. The following example adds a user named James Berg.

Create james (UNIX).

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request PUT
 --data '{
  "name":"james",
  "lastname":"Berg",
  "firstname":"James",
  "email":"james2@examplerock.com",
  "fullname":"hallo2",
  "description":"Created by OpenIDM REST.",
  "userPassword":"asdfkj23"
 }'
 http://localhost:8080/openidm/managed/user/james

{"_id":"james","_rev":"0"}

Create james (Windows).

C:\>curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request PUT
 --data {
 \"name\":\"james\",
 \"lastname\":\"Berg\",
 \"firstname\":\"James\",
 \"email\":\"james2@examplerock.com\",
 \"fullname\":\"hallo2\",
 \"description\":\"Created by OpenIDM REST.\",
 \"userPassword\":\"asdfkj23\"
 }
 http://localhost:8080/openidm/managed/user/james

{"_id":"james","_rev":"0"}

OpenIDM creates the new user in the repository. If you configure a mapping to apply changes from the local repository to the XML file connector as a target, OpenAM next updates the XML file to add the new user.

Install OpenIDM as described in the chapter on Installing OpenIDM Services.

OpenIDM comes with an internal noSQL database, OrientDB, for use as the internal repository out of the box. This makes it easy to get started with OpenIDM. OrientDB is not yet supported for production use, however, so use a supported JDBC database when moving to production.

$ cd /path/to/openidm
$ rm conf/provisioner.openicf-xml.json
 conf/sync.json
 conf/scheduler-reconcile_systemXmlAccounts_managedUser.json

$ cp -r samples/sample2/conf .

Sample 1 is described in the chapter, First OpenIDM Sample.

Sample 2 resembles sample 1, but in sample 2 OpenIDM is connected to a local LDAP server. The sample has been tested with OpenDJ directory server, but it should work with any LDAPv3 compliant server.

Sample 2 demonstrates how OpenIDM can pick up new or changed objects from an external resource. The sample contains only one mapping, from the external LDAP server resource to the OpenIDM repository. The sample therefore does not push any changes made to OpenIDM managed user objects out to the LDAP server.

$ cd /path/to/openidm
$ cp -r samples/sample2/conf .

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: 12345
sn: Doe
mail: jdoe@example.com
description: Created for OpenIDM

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

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids"

{
    "query-time-ms": 1,
    "result": [
        {
            "_id": "56f0fb7e-3837-464d-b9ec-9d3b6af665c3",
            "_rev": "0"
        }
    ],
    "conversion-time-ms": 0
 }

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/managed/user/56f0fb7e-3837-464d-b9ec-9d3b6af665c3"

Like sample 2, sample 2b also connects to an external LDAP server.

Unlike sample 2, however, sample 2b has two mappings configured, one from the LDAP server to the OpenIDM repository, and the other from the OpenIDM repository to the LDAP server.

$ cd /path/to/openidm
$ cp -r samples/sample2b/conf samples/sample2b/script .

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

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids"
   

{
    "query-time-ms": 1,
    "result": [
        {
            "_id": "56f0fb7e-3837-464d-b9ec-9d3b6af665c3",
            "_rev": "0"
        }
    ],
    "conversion-time-ms": 0
 }

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/managed/user/56f0fb7e-3837-464d-b9ec-9d3b6af665c3"

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --data '{"email":"fdoe@example.com","familyName":"Doe","userName":"fdoe",
 "givenName":"Felicitas","displayName":"Felicitas Doe"}'
 --request PUT
 "http://localhost:8080/openidm/managed/user/repoUser1"

Sample 3 shows an example configuration for the Scripted SQL connector. The Scripted SQL connector communicates with the database through configurable SQL scripts. Each operation, like create or delete, is represented by its own script.

Scripts are located in the openidm/samples/sample3/tools/ folder. The openidm/samples/sample3/data/ folder contains a data definition language script for setting up the MySQL database schema to hold the external user objects.

Prepare a fresh installation of OpenIDM before trying this sample.

$ cd /path/to/openidm
$ cp -r samples/sample3/conf samples/sample3/tools .

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

-> shutdown
-> 
$ ./startup.sh

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

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids"

{"query-time-ms":2,"result":[
 {"_id":"dc870bff-c2e9-4378-8ac1-45ee085b09bf","_rev":"0"},
 {"_id":"9046dea4-1dea-4ae8-8335-070839b12b9c","_rev":"0"},
 {"_id":"17fc954f-828a-454c-b05e-f8e9934c6e64","_rev":"0"},
 {"_id":"371855d1-44c9-4854-a576-3397275211e4","_rev":"0"},
 {"_id":"97066201-e0de-48d9-8c9e-bdf7f0f0c7e5","_rev":"0"}],
 "conversion-time-ms":0}

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/managed/user/dc870bff-c2e9-4378-8ac1-45ee085b09bf"

Sample 4 deals with a comma-separated value file as the external resource. The file name is part of the sample configuration. Therefore you do not need to manage any other external resources.

$ cd /path/to/openidm
$ cp -r samples/sample4/conf samples/sample4/data .

$ ./startup.sh
./startup.sh
Using OPENIDM_HOME:   /path/to/openidm
Using OPENIDM_OPTS:   -Xmx1024m
Using LOGGING_CONFIG:
 -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
Using boot properties at /path/to/openidm/conf/boot/boot.properties
->

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

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids"

{
    "query-time-ms": 1,
    "result": [
        {
            "_id": "a8c6a158-3e82-450e-8e28-6ebf5a01a1a6",
            "_rev": "0"
        },
        {
            "_id": "750a2375-6983-4e5f-bdbd-7e121e94cf74",
            "_rev": "0"
        }
    ],
    "conversion-time-ms": 0
 }
   

$ curl
 --header "X-OpenIDM-Username-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/managed/user/a8c6a158-3e82-450e-8e28-6ebf5a01a1a6"

{
    "userName": "Doe",
    "givenName": "Darth",
    "employeeNumber": "123456",
    "_id": "a8c6a158-3e82-450e-8e28-6ebf5a01a1a6",
    "_rev": "0",
    "email": "doe@forgerock.org"
 }

Sample 5 demonstrates the flow of data from one external resource to another. The resources are called LDAP and AD, but in the sample both directory-like resources are simulated with XML files.

$ cd /path/to/openidm
$ cp -r samples/sample5/conf samples/sample5/script .

$ ./startup.sh
./startup.sh
Using OPENIDM_HOME:   /path/to/openidm
Using OPENIDM_OPTS:   -Xmx1024m
Using LOGGING_CONFIG:
 -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
Using boot properties at /path/to/openidm/conf/boot/boot.properties
->

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

Sample 6 resembles sample 5, but sample 6 uses two real LDAP connections. To simplify setup, both provisioners point to the same LDAP server, and only use different base DNs, so you can simulate use of two directory servers with a single OpenDJ directory server, for example.

Sample 6 picks up new and changed users from the LDAP suffix, ou=people,dc=example,dc=com, and sends updates to the "Active Directory" suffix ou=people,o=ad. To keep the example relatively simple, no configuration is provided for the flow from AD to LDAP.

$ cd /path/to/openidm
$ cp -r samples/sample6/conf .

3.8.2. External Configuration

Out of the box, the sample provisioners are configured to use two independent LDAP servers. Change the sample to connect to a single LDAP server representing both external resources by using the same port numbers in both provisioner .json files. For example, change conf/provisioner.openicf-ad.json so the port number line reads "port" : 1389.

3.8.2.1. Prepare OpenDJ For LiveSync

With LiveSync, OpenIDM detects changes in an external resource as they happen. OpenIDM detects changes in OpenDJ by reading the External Change Log (ECL). The ECL is presented as an LDAP subtree with base DN cn=changelog. Each change is represented as an entry in the subtree. Each change entry remains in the subtree until the log is purged (by default three days).

You turn on the change log in OpenDJ by enabling replication. OpenDJ provides the change log even if it does not in fact replicate data to another OpenDJ server (though it can log, in this case, harmless error messages because it is not connected to another replica).

To enable replication without another server, set up replication when installing OpenDJ.

3.8.2.2. LDAP Configuration

Sample 6 is configuration for an external LDAP server set up as follows.

• The LDAP server runs on the local host.

• The LDAP server "LDAP" listens on port 1389.

• The LDAP server "AD" listens on port 4389. Change this to 1389 to use a single LDAP server.

• The LDAP server both have a user with DN cn=Directory Manager and password password who can read and write to the data and read the change log.

• User objects are stored under:

  • Base DN ou=people,o=ad for the connector called "AD".

  • Base DN ou=people,dc=example,dc=com for the connector called "LDAP".

• User objects have the object class inetOrgPerson.

• User objects have the following attributes:

  • uid

  • sn

  • cn

  • givenName

  • mail

  • description

  The LDIF representation of an example user is as follows.

  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: 12345
  sn: Doe
  mail: ddoe@example.com
  description: Created by OpenIDM
  

Prepare the LDAP server by creating two base DNs, dc=example,dc=com and o=AD, and then importing the following objects.

For the "LDAP" directory, import samples/sample6/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: 12345
sn: Doe
mail: jdoe@example.com
description: Created for OpenIDM

For the "AD" directory import samples/sample6/data/AD.ldif.

dn: o=AD
objectClass: domain
objectClass: top
dc: organization

dn: ou=People,o=AD
ou: people
description: people
objectclass: organizationalunit

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

{"reconId":"7da56fc0-54de-4c7b-bae3-de7c7a999387"}

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids"

{
    "query-time-ms": 1,
    "result": [
        {
            "_id": "56f0fb7e-3837-464d-b9ec-9d3b6af665c3",
            "_rev": "0"
        }
    ],
    "conversion-time-ms": 0
}

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/managed/user/56f0fb7e-3837-464d-b9ec-9d3b6af665c3"

$ /path/to/OpenDJ/bin/ldapsearch
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --hostname `hostname`
 --port 1389
 --baseDN o=AD
 "(uid=*)"

dn: uid=jdoe,ou=people,o=ad
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: top
givenName: John
description: Created for OpenIDM
uid: jdoe
cn: John Doe
sn: Doe
mail: jdoe@example.com

{
    "enabled" : true,
    "type" : "cron",
    "schedule" : "0/15 * * * * ?",
    "invokeService" : "provisioner",
    "invokeContext" : {
        "action" : "liveSync",
        "source" : "system/ldap/account"
    }
}