LifeCycle of LiveCycle Domain Synchronization

A LiveCycle Enterprise Domain is synchronized with users and groups from an external entity.
The external entity can be either of the following,

  • Custom SPI – Custom Service Provider Interface allows one to connect to a external system other than LDAP for fetching users to LiveCycle.
    One can create a Custom SPI by implementing DirectoryUserProvider and DirectoryGroupProvider Interfaces.
    The following document details step by step procedure for creating a Directory Provider,
  • LDAP – Integrating an LDAP with an Enterprise Domain is very clearly detailed in this blog,
    As of LiveCycle ES3, following LDAP servers are supported,

    • Sun ONE 5.2
    • Sun ONE 6.3
    • Microsoft Active Directory 2003
    • Microsoft Active Directory 2008
    • IBM Tivoli Directory Server 6.0
    • Novell eDirectory 8.7.3
    • Lotus Domino v8.x
    • ADAM 1.1.3790.2075
    • OpenLDAP 2.3.43-12.el5_5.3.i386

I’ll talk about the following related to Domain Synchronization,

Working of Domain Synchronization with an LDAP Server

An Enterprise Domain registered with an LDAP server works in 3 steps during a sync,

  • Syncrhonize Users from LDAP
  • Syncrhonize Groups from LDAP
  • Syncrhonize Group Members from LDAP

Let’s take an example where an Enterprise Domain is registered with a Microsoft Active Directory with following specifications,

  • UniqueId for both Users and Groups is set to ObjectGUID.
  • Batch size is by default set to 200, which means that the Users, Groups, Group Members will be fetched from an LDAP in a batch of 200.
  • Let’s consider some test Users from the Active Directory LDAP,
    User 1
    dn: CN=foo,CN=users,DC=example,DC=com
    sAMAccountName: foo
    memberOf: CN=baz,CN=Users,DC=example,DC=com
    objectGUID: 1
    User 2
    dn: CN=bar,CN=users,DC=example,DC=com
    sAMAccountName: bar
    memberOf: CN=baz,CN=Users,DC=example,DC=com
    objectGUID: 2

In an Active Directory LDAP server, the ObjectGUID field is a binary field.
For simplicity sake I’m using it as numeric field.

The user synchronization phase in this example, involves the following steps:

  • Fetch 200 users (configurable batch size via editing config.xml) from LDAP.
  • Determine the value for the unique identifier for each user.
  • Look for a record in LiveCycle user table where the canonicalName matches with the user’s unique identifier.
    • Case A – If the record exists then update the user properties.
    • Case B – If the record does not exist then create a new user record.
    • Case C – If the record exists in LiveCycle Db but marked Obsolete, then mangle the userID of the previous record and continue creating the new record.
  • Once all the users have been fetched, the users present in LiveCycle Db but not modified in the current synch cycle are marked OBSOLETE.

A similar logic is used in the group synchronization phase.
Group membership phase comes into picture only if both the User and Groups synchronization for a Domain are enabled.
Group Membership links the synched User and Group on behalf of the Membership at the LDAP end between both the principals.

UniqueId used in LDAP Synchronization

In the synchronization process, the unique identifier attribute for users and groups plays a very important role.
It serves as the key attribute for helping migrate Principals registered with one LDAP to another.
This LDAP attribute used as UniqueId should fulfill the following requirements in the LiveCycle database,

  • Unique – The identifier should be unique across the whole user/group repository.
  • Immutable – It does not change for a given user/group.
  • Not recycled – The identifier once assigned to a user/group is never reused.

The following LDAP attributes are not a good candidate for a unique identifier:

  • distinguishedName
    For example, consider that a user’s distinguished name (dn) CN=foo, ou=finance, DC=bar,DC=com is used as the unique identifier.
    In this case, if foo moves to different department, then the dn will change.
  • loginId
    A user’s login ID (samAccountName in Active Directory and uid in SunOne) are sometime recycled when an old user leaves and the new user with the same name arrives.
    In this case, the new user is given the same userId.
  • email
    Email is fairly a good candidate. However, it might cause some issues when the emails are recycled or modified.

Therefore, the synchronization logic by default, uses the following LDAP attributes for different LDAP server,

  • objectGUID – for Microsoft Active Directory
  • objectGUID – for ADAM
  • nsuniqueId – for SunOne
  • guid – Novell eDirectory
  • dominoUNID – Lotus Domino
  • ibm-entryuuid – IBM Tivoli

However, these attributes can be replaced with any other attribute of LDAP which fulfills the above mentioned requirements.

User Indentity in LiveCycle

The user identity of a user in LiveCycle is governed by the following rules.
In a LiveCycle domain,

  • A user’s loginid (edcprincipaluserentity.uidstring) is unique but with respect to it’s own domain, i.e. same userId can co-exist in another domain.
  • A user’s canonicalName (edcprincipalentity.canonicalname) is unique  but with respect to it’s own domain, i.e. same canonicalName can co-exist in another domain.
  • Each user and group is assigned an oid (, which is used to refer the user by other systems in LiveCycle.
    It’s unique across all domains.
    Therefore, a process refers to a user using its Oid.
  • A user can be uniquely referred using:
    • User’s LiveCycle DomainName and LoginId
    • User’s LiveCycle DomainName and CanonicalName
    • User’s Oid

Unique Identifier Migration

There are times when an Enterprise needs to migrate it’s users to another LDAP, or let say an Enterprise may have multiple LDAP servers but now wants to consolidate the principals in a single domain.
In broader sense the migration works as follows,

  • Modify the unique identifiers from old one to new ones according to the new LDAP server.
  • The next Synchronization detects that the unique identifier has changed. Therefore, the Synchronization logic is modified.
  • Fetch 200 users from LDAP.
  • For each user, determine the value for the old unique identifier.
  • Look for a record in LiveCycle user table, where the record’s canonicalName matches with the old unique identifier.
    • Case A – If the record exists, update the user properties and the canonicalName.
    • Case B – If the record does not exist, create a new user record with the new canonicalName.
  • Once all the users are fetched, find all the users who have not been modified in the current cycle, and mark them OBSOLETE.
  • In the end, the canonicalName (unique identifier) for all users is changed to the new Unique Id.
  • Ensure that during this Synchronization process, the value for old unique identifier is not changed at the Old LDAP’s end.

Scenario 1

An Enterprise has configured an LDAP DirectoryProvider in LiveCycle, which uses email as the unique identifier.
Due to various reasons mentioned above, an Enterprise may want to move to objectGUID, whereas other details, such as the LDAP server, domain, and so on, remain unchanged.
In this case, after the unique identifier has been changed, the canonical name for all active Users will be migrated to the new one.

Scenario 2

An Enterprise has configured a SunOne LDAP DirectoryProvider, which uses nsuniqueId as the unique identifier.
As a part of an IT exercise all the users at the LDAP end have migrated from SunOne to Active Directory.
This means that all the LiveCycle Users that are a part of the Enterprise Domain registered with Sunone will have to migrate to Active Directory.
Strict care has to be taken to preserve the User’s Identity in such a way that the said User’s work doesn’t get affected.

  • LDAP1 – Old LDAP server, SunOne
  • LDAP2 – New LDAP server, Active Directory

The user accounts will be migrated from LDAP1 to LDAP2.
While doing this, a user account will be active only in one of the LDAP servers.
After the migration, it will be marked inactive in the other one.
As UniqueId will be different between LDAP1 and LDAP2, one needs to change the unique identifier in a way that the user identity is maintained.
i.e. the user identity should be federated between both the LDAPs based on a particular attribute which can also serve as the uniqueId during migration.

The following steps need to be performed to conclude a successful migration,

  • In the Directory Provider configured with LDAP1, change the unique identifier from nsuniqueId to uid.
    It assumes that the value for uid(from SunOne) and samAccountName(from Active Directory) remains same between LDAP1 and LDAP2.
  • Run the Synchronization. It will change the unique identifier from nsuniqueId to uid, and thereby update the canonicalName for the Users in LiveCycle database.
  • During the migration, LDAP1 will have users disabled while the same users will be in active in LDAP2.
    Now, one needs to configure LDAP2 as the new Directory Provider in the same LiveCycle domain with unique identifier set to samAcccountName.
    For example, the user Bob is disabled in LDAP1 and enabled in LDAP2.
    In this case, when the Synchronization runs,

    • It fetches the user Bob from LDAP1, which is inactive, and therefore will be disabled.
    • It fetches the users Bob from LDAP2, which is active. Its unique identifier will be used to look up the user Bob in LiveCycle database.The record will be found (from the Synchronization by LDAP1) and updated.
  • After migration is complete, the new Directory Provider can switch to the commonly used uniuqeId attribute and synchronize again, i.e. objectGuid in this case.

Bookmark and Share

5 Responses to LifeCycle of LiveCycle Domain Synchronization

  1. Albertus says:

    Good day,

    Thank you for a very informative post.

    I’m trying to understand the detailed steps to migrate users between 2 Microsoft Active Directory instances. It seems that you have a detailed understanding, so it would be great if you could assist me in understanding exactly what is needed?

  2. apugalia says:

    When you create an Enterprise Domain with Active Directory as an LDAP, then you specify ObjectGUID as the unique Identifier. That’s the default settings unless you go and change it in Users/Group Settings page of Directory Provider Settings.

    Now let say you have Enterprise Domain configured and running good with Active Directory X. Now you want to point the same Enterprise to start referring to Active Directory Y.

    First of all, make sure that the users of both the Active Directories share some common attribute. Generally, the samAccountName value is the common link between the users from two different Active Directories.

    1. First make a canonical name change by editing the Directory Provider Settings and replacing ObjectGUID with samAccountName in Users/Groups Settings page.
    2. Save the changes and re-sync the domain.
    3. Now replace the server settings of Active Directory X with Active Directory Y in the Directory Provider.(keeping the UniqueId as samAccountName)
    4. Now resync the Enterprise Domain.
    5 You’ll see that all the users still retain their history but now they will start pointing to Active Directory Y instead of X.
    6. Now you can change the canonical name back to the original one, e.g. ObjectGUID.
    7. Resync the Enterprise Domain.

  3. Hi,

    Thanks for the great post.

    I have a hopefully simple question.

    1) I have LCES3 connected & synchronizing to the clients AD. (Enterprise Domain setup in the LC Adminui)
    2) I need to periodically query a specific group and do something with each user.
    3) The specific group contains 975 users
    4) Im using the Find Group & findGroupMembers operations from the UserManagerLookupService to retrieve a list of users.

    1) The findGroupMembers operation is only returning 200 users.

    What I have tried / Noted:
    1) Modifying the offset & resultSize values of the findGroupMembers operation to try get the next “batch” of users – no luck.
    2) I opened the GROUP in LC AdminUI and noted that there are only 200 users in the GROUP – I resynchronized
    2 a) Then in LC AdminUI, I went to “Edit Enterprise Domain” -> Directory -> Directory Group. I clicked TEST and saw the GROUP. I clicked on the GROUP, and noted in the “member” Attributes Names in the Attribute Value it listed all 975 users.
    3) I have resynchronzied the Enteprise domain multiple times, but still no reflection (all users showing in the group).
    4) The users that need to be in the group, however are showing in the LC AdminUI as users, however in the user’s user groups, it shows that it is not associated with that group.

    1) Why does LC AdminUI not reflect the correct number of users in a group in a synchronized Enterprise domain.(it limits it to 200)

    Thanking all in advance

  4. Regarding what was said in the article: “Fetch 200 users (configurable batch size via editing config.xml) from LDAP”.

    Im using JBOSS LCES3, which config.xml are we talking about here?

    Kind Regards,

  5. The “200 configurable batch size”, is that a batch or a limit size?

    How do you fetch more than 200?