The current distribution of OpenIDM comes with a variety of samples in openidm/samples/. The first, openidm/samples/sample1, is installed by default, and described in the First OpenIDM Sample chapter.

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.

Installing Samples Each sample folder in openidm/samples/ contains a list of sub folders, such as conf/ and script/, depending on which files you need to run the sample. The easiest way to configure a new installation for one of the samples is to copy all files in the sample folder into the appropriate folder under openidm/. Some, but not all samples require additional software, such as an external LDAP server or database.

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. Remove the pre-installed sample1 files before starting with other samples. $ cd /path/to/openidm $ rm conf/provisioner.openicf-xml.json conf/sync.json conf/scheduler-reconcile_systemXmlAccounts_managedUser.json After removing the sample1 files, copy the relevant files from the sample you want to try. For example, if you want to configure OpenIDM to use sample2 then copy the configuration files from that sample $ cp -r samples/sample2/conf .

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

Samples Sample 2 - LDAP one way Sample 2 resembles sample 1, but in sample 2 OpenIDM is connected to a local LDAP server. The sample has been tested with OpenDJ, 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.

Prepare OpenIDM as described in , copying the configuration for sample 2. $ cd /path/to/openidm $ cp -r samples/sample2/conf .

Sample 2 expects the following configuration for the external LDAP server: The LDAP server runs on the local host. The LDAP server listens on port 1389. A user with DN cn=Directory Manager and password password has read access to the LDAP server. User objects are stored on the LDAP server under base DN ou=People,dc=example,dc=com. User objects have the object class inetOrgPerson. User objects have the following attributes: uid sn cn givenName mail description An example user object 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: jdoe@example.com description: Created by OpenIDM 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: 12345 sn: Doe mail: jdoe@example.com description: Created for OpenIDM

First start OpenIDM. Then 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/sync?_action=recon&mapping=systemLdapAccounts_managedUser" Successful reconciliation returns a "reconId" object. 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 --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" The resulting JSON object should look something like this, but all on one line. { "query-time-ms": 1, "result": [ { "_id": "56f0fb7e-3837-464d-b9ec-9d3b6af665c3", "_rev": "0" } ], "conversion-time-ms": 0 } To retrieve the user, get the object by ID. $ 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" Read openidm/conf/sync.json and openidm/conf/provisioner.openicf-ldap.json to understand the layout of the user object in the repository.

Samples Sample 2b - LDAP two way 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.

Prepare OpenIDM as described in . Copy the sample configuration, and copy the script to the script folder. $ cd /path/to/openidm $ cp -r samples/sample2b/conf samples/sample2b/script . If you already installed sample 2, then simply add the second mapping from sample 2b's sync.json file to the current sync.json file, and copy the sample script to the script folder. The script is referenced in the second mapping.

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

First start OpenIDM. Then 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/sync?_action=recon&mapping=systemLdapAccounts_managedUser" Successful reconciliation returns a "reconId" object. 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 --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" The resulting JSON object should look something like this, but all on one line. { "query-time-ms": 1, "result": [ { "_id": "56f0fb7e-3837-464d-b9ec-9d3b6af665c3", "_rev": "0" } ], "conversion-time-ms": 0 } To retrieve the user, get the object by ID. $ 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" Test the second mapping by creating a user in the OpenIDM repository. $ curl --header "X-OpenIDM-Username: openidm-admin" --header "X-OpenIDM-Password: openidm-admin" --data '{"email":"fdoe@example.com","familyName":"Doe","userName":"fdoe", "givenName":"Felicitas","displayName":"Felicitas Doe"}' --request PUT "http://localhost:8080/openidm/managed/user/repoUser1" Run reconciliation again to create the new user in the LDAP server as well.

Samples Sample 3 - Scripted SQL 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.

Prepare OpenIDM as described in . Copy the conf and tools folders. $ cd /path/to/openidm $ cp -r samples/sample3/conf samples/sample3/tools . In conf/provisioner.openicf-scriptedsql.json, edit the paths starting with /opt/111 to match your installation. You do not need to copy the sample3/data/ folder, as its content is needed only to set up the external user database. In this example OpenIDM communicates with MySQL database server. OpenIDM requires a MySQL driver, the MySQL Connector/J. Download MySQL Connector/J, unpack the delivery, and copy the .jar into the openidm/bundle directory. $ cp mysql-connector-java-5.1.18-bin.jar /path/to/openidm/bundle/ Restart OpenIDM to make sure the new bundle is picked up. -> shutdown -> $ ./startup.sh

For this sample, OpenIDM connects to an external MySQL database server. Sample 3 expects the following configuration for MySQL: The database is available on the local host. The database listens on port 3306. You can connect over the network to the database with user root and password password. MySQL serves a database called HRDB with a table called Users. The database schema is as described in the data definition language file, openidm/samples/sample3/data/sample_HR_DB.mysql. Import the file into MySQL before running the sample. $ ./bin/mysql -u root -p < /path/to/openidm/samples/sample3/data/sample_HR_DB.mysql Enter password: $ If the configuration of the external database is correct, then OpenIDM should show five users during startup. The check method, executed for each connected resource, executes a select * from Users statement.

The sample 3 sync.json configuration file contains a mapping to reconcile OpenIDM and the external databasee. Run the reconciliation with the following command. $ 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" Reconciliation creates the five users from the database in the OpenIDM repository. Check the result with the following command. $ 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" The result should resemble the following JSON object. {"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} To view the JSON for one of the users, get the user by the value of the _id. $ 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"

Samples Sample 4 - CSV file 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.

Prepare OpenIDM as described in . Copy the configuration, and copy the data folder holding the .csv file. $ cd /path/to/openidm $ cp -r samples/sample4/conf samples/sample4/data .

The only external resource you need is the data/hr.csv file you copied.

The sample4/data/hr.csv file contains two example users. The first line of the file sets the attribute names. Running reconciliation creates two users in the OpenIDM repository $ 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" Check the results of reconciliation with the following command. $ 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" The result should resemble the following JSON object, but all on one line. { "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 } To view the JSON for one of the users, get the user by the value of the _id. $ 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" }

Samples Sample 5 - Sychronization of two resources 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.

Prepare OpenIDM as described in . Copy the configuration, and copy the script folder that holds sample JavaScript files. $ cd /path/to/openidm $ cp -r samples/sample5/conf samples/sample5/script .

No extra external resource needs configuration for this example. The XML files used are located in the openidm/samples/sample5/data/ folder. When you start OpenIDM with the sample 5 configuration, it creates xml_AD_Data.xml, which does not contain users until you run reconciliation.

Run reconciliation between OpenIDM and the pseudo-LDAP resource. $ 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" This command creates a user in the repository and also in the pseudo AD resource, represented by the samples/sample5/data/xml_AD_Data.xml file.

Samples Sample 6 - LiveSync between two LDAP servers 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 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.

Prepare OpenIDM as described in . Copy the configuration for sample 6. $ cd /path/to/openidm $ cp -r samples/sample6/conf .

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.

With LiveSync, OpenIDM detects changes in an external resource as they happen. OpenIDM detects changes in OpenDJ by reading the External Change Log (ECL), a mechanism similar to the Retro Change Log for those who have worked with Sun Directory Server. 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. Topology Options screen from the OpenDJ QuickSetup wizard The OpenDJ QuickSetup wizard lets you set up replication at installation time.

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

The following sections show how to run the sample both once with reconciliation, and continuously with LiveSync.

Start up OpenIDM, and then run reconciliation. $ 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" The result of a successful reconciliation is a reconId object. {"reconId":"7da56fc0-54de-4c7b-bae3-de7c7a999387"} With the configuration for sample 6, OpenIDM creates user objects from LDAP in the repository, and also in the target AD suffix. After reconciliation, list all users. $ 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" The result should resemble the following JSON object, though all on one line. { "query-time-ms": 1, "result": [ { "_id": "56f0fb7e-3837-464d-b9ec-9d3b6af665c3", "_rev": "0" } ], "conversion-time-ms": 0 } To read the user object, use the _id value. $ 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" You can also view users created in the AD suffix with the following ldapsearch command, assuming you changed the port number to 1389. $ /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

In contrast to reconciliation, which you can start by using a scheduler configuration or by using the REST interface directly, you must start LiveSync using a scheduler. The sample comes with the following scheduler configuration file for LiveSync in conf/scheduler-activeSynchroniser_systemLdapAccount.json. { "enabled" : true, "type" : "cron", "schedule" : "0/15 * * * * ?", "invokeService" : "provisioner", "invokeContext" : { "action" : "liveSync", "source" : "system/ldap/account" } } Activated LiveSync by editing the file, conf/scheduler-activeSynchroniser_systemLdapAccount.json, to change the "enabled" property value to true. With LiveSync enabled, you can change LDAP users and see them show up in AD as OpenIDM flows the data between resources dynamically.