LiveSync with an LDAP server

This sample resembles the sample described in Synchronize data between two external resources. However, this sample demonstrates liveSync from one external LDAP resource to another. LiveSync is the mechanism by which changes are pushed from an external resource to IDM and then, optionally, to another external resource. For more information see Synchronization types.

The sample assumes a scenario where changes in an Active Directory server are synchronized, using LiveSync, with a ForgeRock Directory Services (DS) server.

The sample provides a configuration for two scenarios, depending on whether you are using a live Active Directory (AD) service, or whether you are simulating the AD service with a DS server. Each scenario is associated with a file in the livesync-with-ad/alternatives directory. Depending on your scenario, copy the corresponding file to the livesync-with-ad/conf directory:

Live AD Instance: If you have an AD instance to test with, use that AD instance as the first LDAP resource. For the second LDAP resource, configure DS as described in Set Up the LDAP Resources. The data for the DS instance is contained in the file samples/livesync-with-ad/data/Example.ldif.

For the connection to Active Directory, copy the provisioner.openicf-realad.json file from livesync-with-ad/alternatives to the conf/ directory and rename it provisioner.openicf-ad.json.

Because this sample demonstrates synchronization from the AD server to DS, data on the AD server is not changed.
Simulated AD Instance: If you are simulating the AD instance with a DS server, copy the provisioner.openicf-fakead.json file from livesync-with-ad/alternatives to the conf/ directory and rename it provisioner.openicf-ad.json.

This sample simulates an AD server on the same instance of DS, using a different base DN (dc=fakead,dc=com). You can also simulate the AD server with a separate DS 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 samples/livesync-with-ad/data/AD.ldif. The data for the DS instance is contained in the file samples/livesync-with-ad/data/Example.ldif.

Set up the LDAP resources

Whether you use a simulated Active Directory server, or a live Active Directory server, you must still set up a DS instance as the second LDAP resource.

Set up DS using /path/to/openidm/samples/livesync-with-ad/data/Example.ldif , and do one of the following:

Configure the Connection to a Live AD Instance

To configure the connection to a live AD instance, open the connector configuration file (provisioner.openicf-ad.json) in a text editor. Update the file as required to reflect your AD instance. At a minimum, check and update the following parameters:

host: The hostname or IP address of the AD server.
port: The LDAP port; 389 by default.
ssl: Whether the connection to the AD instance is secured over SSL; false by default.
principal: The full DN of the account that is used to bind to the server, for example, "CN=Administrator,CN=Users,DC=example,DC=com".
credentials: If a password is used, replace null with that password. When IDM starts, it encrypts that password in the provisioner.openicf-ad.conf file.
baseContexts: A list of DNs for account containers, for example, "CN=Users,DC=Example,DC=com".
baseContextsToSynchronize: Set to the same value as baseContexts.
accountSearchFilter: The LDAP search filter to locate accounts; only user accounts by default.
accountSynchronizationFilter: The LDAP search filter to synchronize user accounts; only user accounts by default.

If you do not want to filter out computer and disabled user accounts, set the accountSearchFilter and accountSynchronizationFilter to null.

Configure the Connection to a Simulated AD Instance

If you do not have a testable instance of AD available, you can simulate an AD instance in a separate suffix on the existing DS instance. The data/AD.ldif file includes LDIF data for a simulated AD instance.

If you have not already done so, copy the samples/livesync-with-ad/alternatives/provisioner.openicf-fakead.json to the conf subdirectory and rename it provisioner.openicf-ad.json.

This file sets up the connection to the DS server, targeting the suffix (dc=fakead,dc=com) that is simulating an AD server.

Load the simulated data into that suffix:

/path/to/opendj/bin/ldapmodify \
--port 1636 \
--useSSL \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--hostname localhost \
--bindDN uid=admin \
--bindPassword password \
--filename /path/to/openidm/samples/livesync-with-ad/data/AD.ldif
# ADD operation successful for DN dc=fakead,dc=com

# ADD operation successful for DN ou=People,dc=fakead,dc=com

# ADD operation successful for DN uid=bobf,ou=People,dc=fakead,dc=com

# ADD operation successful for DN uid=stony,ou=People,dc=fakead,dc=com

Run the sample

When both DS and a real or simulated AD server are configured, prepare IDM as described in Prepare IDM. Then start IDM with the configuration for this sample:

cd /path/to/openidm/
./startup.sh -p samples/livesync-with-ad

The following sections show how to synchronize the two external LDAP data stores by running a reconciliation operation, how to configure scheduled liveSync.

Reconcile the two LDAP data stores

Review the entries in the DS server (imported from the Example.ldif file). When you run reconciliation, any entries that share the same uid with the AD data store will be updated with the contents from AD.

If you have set up the simulated AD data store as described in Simulated AD Instance, compare the entries in the AD.ldif and Example.ldif files. Note that each file has two different users—after importing the data, the AD instance has users bobf and stony, and the DS instance has users jdoe and bjensen.

Run reconciliation over the REST interface:
```
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/recon?_action=recon&mapping=systemAdAccounts_managedUser&waitForCompletion=true"
```
The reconciliation operation returns a reconciliation run ID, and the status of the operation.
```
{
  "state": "SUCCESS",
  "_id": "985ee939-fbe1-4607-a757-00b404b4ef77"
}
```
The reconciliation operation synchronizes the data in the AD server with the IDM repository (managed/user). Implicit synchronization then pushes those changes out to the DS server. For more information about implicit synchronization, see Synchronization types.

List all the users in the DS server:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/ldap/account?_queryFilter=true&_fields=_id,dn"

Your DS server should now contain four users:

{
  "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": "fc4feff0-11ae-430f-858d-338b1b05d66a",
      "dn": "uid=bobf,ou=People,dc=example,dc=com"
    },
    {
      "_id": "ba07d4f4-0e2b-4c53-aecb-4b234e1fec1c",
      "dn": "uid=stony,ou=People,dc=example,dc=com"
    }
  ],
  ...
}

The two users from the AD server have been added to the DS server.

Configure liveSync

LiveSync pushes changes made in an external system to the IDM repository. You can launch a liveSync operation over REST, or configure a schedule to poll for changes. This sample includes a liveSync schedule (conf/schedule-activeSynchroniser_systemAdAccount.json) that is disabled by default. When the schedule is enabled, a liveSync operation is launched every 15 seconds.

To activate liveSync, change the value of the enabled property in the schedule configuration from false to true:

{
    "enabled" : true,
    "type" : "simple",
    "repeatInterval" : 15000,
    "persisted" : true,
    "concurrentExecution" : false,
    "invokeService" : "provisioner",
    "invokeContext" : {
        "action" : "liveSync",
        "source" : "system/ad/account"
    },
    "invokeLogLevel" : "debug"
}

Test liveSync

Test liveSync as follows:

Create an LDIF file with a new user entry (uid=bsmith) that will be added to the AD directory.

You can use the following LDIF file (bsmith.ldif) as an example. This sample file assumes the simulated AD instance. Adjust the DN if you are using a live AD instance:

dn: uid=bsmith,ou=People,dc=fakead,dc=com
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: top
givenName: Barry
description: Created to see liveSync work
uid: bsmith
cn: Barry
sn: Smith
mail: bsmith@example.com
telephoneNumber: 1-415-523-0772
userPassword: 5up35tr0ng

Use the ldapmodify command to add the new user to the AD directory:

/path/to/opendj/bin/ldapmodify \
--port 1636 \
--useSSL \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--hostname localhost \
--bindDN uid=admin \
--bindPassword password \
--filename /path/to/bsmith.ldif
# ADD operation successful for DN uid=bsmith,ou=People,dc=fakead,dc=com

Within 15 seconds, liveSync should create the user in the IDM repository.

Test that the liveSync has worked by viewing the new user in IDM.

The easiest way to do this, is through the End User UI. You should be able to log in to the End User UI (http://localhost:8080) as user bsmith, with password 5up35tr0ng. If you can log in to the UI as this new user, liveSync has synchronized the user from the AD directory to the managed/user repository.

Implicit synchronization pushes this change out to the DS server. To test this synchronization operation, search the DS baseDN for the new user entry.

/path/to/opendj/bin/ldapsearch \
--port 1636 \
--useSSL \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--hostname localhost \
--bindDN uid=admin \
--bindPassword password \
--baseDN ou=people,dc=example,dc=com \
"(uid=bsmith)"

IDM 7.2.1