Many LiveCycle enterprise customers prefer to integrate LiveCycle with their corporate LDAP directory to avoid the hassle of maintaining an additional user directory. Here is a procedure you can follow to configure your corporate LDAP with LiveCycle ES. This has been developed based on multiple customer engagements.
TOOLING
-----------
Download and install one of the following free tools to browse the corporate LDAP Directory :
- Apache Directory Studio
- Microsoft Active Directory Explorer
- Softerra LDAP Browser
UNDERSTAND YOUR LDAP SCHEMA
--------------------------------------------
2) Work with the LDAP Administrator and get Softerra/Apache Directory Studio working
At the very least, you would need the IP address or name of your LDAP server(s), the port (usually 389), a userID, its password as well as the Base Distinguished Name (DN).
3) Familiarize Yourself with the LDAP Schema
Integrating LiveCycle essentially involves the mapping of LiveCycle's user attributes to the LDAP users' attributes. In most cases, the directory is organized into Organizational Units (OUs) at the highest levels. Working twith the LDAP Administrator as well as the LiveCycle Business User, determine the lowest OU that would contain ALL of LiveCycle's users. Using the Softerra LDAP Browser or Apache Directory Studio, determine its DN.
BACKUP LIVECYCLE'S DATABASE
-------------------------------------------
In practical terms, integration of LiveCycle with the corporate LDAP is a trial and error effort. In many cases, it takes at least three diffferent tries before we get it right. In case the first few attempts go awry, and you feel like you need to start from a clean baseline, it is a good idea to backup your database.
INTEGRATE LIVECYCLE
------------------------------
3) Connect to the Directory from the LiveCycle AdminUI
Login to the LiveCycle Admin Console.
Navigate to Settings->User Management->Domain Management.
Click on 'New Enterprise Domain'. Type in an ID and Name (description)
Cick on 'Add Authentication'
In most cases, you'd choose 'LDAP'. Click OK.
Click on 'Add Directory'
Type in a Profile name (eg. "My_Company_Directory") and click 'Next'.
Type in the server name or IP address
Type in the port number
If only SSL connections are allowed to the LDAP Directory servers, choose SSL. Otherwise, choose No.
If binding (connecting) requires authentication (required in most cases), type in the userID that can access it and the associated password.
In the 'Populate Page With' dropdownlst, choose the type of your LDAP Directory. This will populate your user mapping fields with the most appropriate values. However, in most cases, some of these require changes.
Check the checkbox for 'Retrieve Base DNs'
Click on the button 'Test'. If the connection succeeded, the page will say "The server test was successful." (in gray, at the top - it's very easy to miss). If the test is successful, click 'Next'
The user attribute mapping field will load next.
4) Integrate Users
In the Softerra LDAP Browser, locate the entry for a user with whom you are familiar. It can be you, the LDAP Administrator, or the LiveCycle business user. Examine the user's attributes. The LiveCycle user attributes that need to be mapped to your LDAP user attributes are as follows (only some are required, others are optional). The choices you make here are VERY IMPORTANT:
- Unique Identifier
- Description
- Full Name
- Login ID
- Last Name
- Given Name
- Initials
- Business Calendar
- Organization
- Primary Email
- Secondary Email
- Telephone
- Postal Address
- Locale
- Time Zone
The most important is the Unique Identifier. You have to absolutely make sure that this is indeed unique among users in your entire directory.
The search filter field is very important also. You will need the asistance of your LDAP Administrator in coming up with a filter that brings in only those users who need to use LiveCycle and not more. If you bring in ALL of your users, the daily LDAP Synch operation will take too long to complete. Here is a sample search filter:
(&(objectclass=inetOrgPerson)(!(employeetype=0))(activestatus=y))
A very common mistake is mapping 'Locale' to an LDAP user attribute that contains the name of a city. This will cause errors such as this:
Can not persist Principal with User Id: your_LDAP_auth_login and your_domain ID: your_profile_name because one of the field's size exceeds database column length
This is because the corresponding database table column is not big enough to accomodate some of the city names (eg: San Francisco won't work). To verify, check the definition of the EDCPRINCIPALUSERENTITY. The LOCALE column is VARCHAR (20)
Click the 'Test' button. LiveCycle will query your LDAP Directory with these settings and return some results. Verify that the returned resultset is correct. pay special attention and ensure that all of the columns in the resultset are properly populated with the correct values.
Click 'Close' and then 'Next'. This will load the Group Settings page.
5) Integrate Groups
In the Softerra LDAP Browser, locate the entry for a group with whom you are familiar. It can be a group you or the LDAP Administrator is a member of.
The LiveCycle group attributes that need to be mapped to your LDAP group attributes are as follows (only some are required, others are optional). The choices you make here are VERY IMPORTANT:
- Unique Identifier
- Base DN
- Search Filter
- Description
- Full Name
- Member DN
- Member Unique Identifier
- Organization
- Primary Email
- Secondary Email
The most important is the Unique Identifier. You have to absolutely make sure that this is indeed unique among groups in your entire directory.
The search filter field is very important also. You will need the asistance of your LDAP Administrator in coming up with a filter that brings in only those users who need to use LiveCycle and not more. If you bring in ALL of your users, the daily LDAP Synch operation will take too long to complete. Here is a sample search filter:
(|(ou:dn:=Groups1)(ou:dn:=Groups2)).
Click the 'Test' button. LiveCycle will query your LDAP Directory with these settings and return some results. Verify that the returned resultset is correct. pay special attention and ensure that all of the columns in the resultset are properly populated with the correct values.
Click 'Close' and then 'Finish'.
Click OK in the 'New Enterprise Domain' page.
Click 'Save' in the 'Domain Management' page. This is CRITICAL. If you don't perform the sequence of these last three steps, your configuration changes will NOT get saved.
6) Synchronize
Check the checkbox against the domain you just configured and click 'Sync Now' to start syncnronizing the LiveCycle User Manager tables (EDC...) with information from the corporate LDAP. To determine the progress, check the appserver instance's server log or keep querying the EDCPRINCIPALENTITY table every couple of minutes using this SQL query:
SELECT COUNT(*) FROM your_schema_name.EDCPRINCIPALENTITY
While the synchronization is in progress, you will see this count going up.
7) Configuring Daily Synchronization
The default CRON expression for daily synchronization at 3 am is this:
0 00 3 ? * *
For more details on the Quartz open-source job scheduling system (version 1.4.0), see here.
VERIFY
----------
Login to the LiveCycle Admin Console.
Navigate to Settings->User Management->Domain Management.
Ensure that the 'Current Sync State' is shown as "Completed".
Ensure that you are able to login to the LiveCycle Admin Console using your LAN (LDAP) userID and password.
Here are some additional instructions on verifying a LiveCycle LDAP Synch.
EXPORT CONFIGURATION
----------------------------------
Once you are satisfied that you have a working configuration, it is a good idea to export the configuration. This will enable you to quickly import this configuration into your TEST, STAGING and PRODUCTION environments.
To do the export and import, login to the LiveCycle Admin Console and navigate to Settings->User Management->Configuration->Import and export configuration files. Please note that the exported config.xml file will not contain the password of the user configured to authenticate LiveCycle against the LDAP directory. After each import, you need to add it back and save the configuration before initiating a synch.