LDAP/AD integration is one of the most frustrating and time-consuming areas to troubleshoot, both for customers and for the Jive Support team. The purpose of this document is to unveil some of the mysteries of proper LDAP configuration with Jive products, and introduce some key tools and tricks which can help us help you to find a resolution as quickly as possible.

How do I edit my LDAP settings?

After you run through the initial Jive setup process, the only way to edit your LDAP settings in the application is via the system properties page (System > Settings > System Properties). You'll want to look for any of the keys that start with "ldap.". Keep in mind that changes to system properties require a system restart to take effect.

Alternatively, you can always choose to run through the setup process again. To do this, find the file jive_startup.xml in your jiveHome directory, and set the <setup> parameter to false.

What do those settings mean, anyway?

* Default/Required fields

^ Recommended fields

com.jivesoftware.base.ldap.LdapGroupManager

How do I use LDAP debugging?

LDAP debugging might be the single most useful tool for troubleshooting an LDAP issue. Turn on the system property "ldap.ldapDebugEnabled=true" and restart your system. The LDAP output will be logged to whichever log file captures system output (i.e. catalina.out), NOT to clearspace.log. The application logs are also useful, so be sure to send that one along with catalina.out.

Be aware that LDAP debugging is VERY verbose. After you've gathered the required information and resolved your problem, you'll want to shut it off as soon as possible. As an alternative, you can also use a tool such as Wireshark to capture a TCP dump of LDAP traffic.

What is the purpose of the adminDN account?

The account you associate with the ldap.adminDN attribute should be an LDAP administrator with full read access to the branch from which you will be synchronizing data with Clearspace. This account should not be associated with a Clearspace user or administrator. It is used to bind an LDAP connection from the Clearspace server.

What is an LDIF, and how do I get it?

All LDAP directories can read and write to a file format called LDIF. An LDIF can tell a Jive support engineer just about all we'll need to know about how you need to configure your settings to properly extract user and group records from LDAP. Here's an example:

Any LDAP directory browser provides the ability to export to and import from an LDIF file. If you're using Active Directory, check out the ldifde command line tool. Here's an example of the ldifde command which will yield an LDIF output like above:

Another excellent tool is JXplorer, which helps you to validate your LDAP mappings and provides an easy-to-use LDIF export.

When are user profiles synchronized with LDAP?

User profile information is sychronized with LDAP whenever a user logs in. Alternatively, an administrator can launch a system-wide profile synchronization manually via the admin console (People > Settings > Profiles)

What is group synchronization?

LDAP Groups can be pulled into the application for the purposes of managing permissions and access control. These are separate entities from Social Groups and are not visible to end-users. It is important to note that LDAP groups are lazy-loaded, which means that you will not see a group added to Clearspace until a member of of that group has authenticated to the system for the first time.

How do I override lazy-loading of group memberships?

Using the lazy-loading technique for synchronizing group memberships is a big performance boost for the application. However, when you are setting up your communities for the first time, you may find it necessary to synchronize all group membership at once. To do this, use the following technique:

What are POSIX groups?

In some directories, groups identify their members by the full distinguished name (DN) of their members. Other groups store their member associations by the common name (CN). The latter type is a POSIX group. For example:

member= CN=Cyr \, Karl,OU=Jive_Users,DC=support,DC=jive,DC=com -> "normal" group identification
memberuid=karlcyr -> "POSIX" group

If your group type is POSIX, you'll need to enable POSIX mode (see above).

Escaping spaces in Active Directory paths (CS-11162)

If your DNs have elements which contain spaces, they may need to be escaped in order for Jive to communicate with AD:

CN=AdminMan,OU=Domain Users,DC=support,DC=jive,DC=com

CN=Admin\20Man,OU=Domain\20Users,DC=support,DC=jive,DC=com

I can't run an LDAP sync and I get this error in my logs, what should I do?

08 Jun 2009 00:08:21,104 [Task Engine Worker 0] FATAL
control.AbstractRequestControlDirContextProcessor - No matching
response control found for paged results - looking for 'class
javax.naming.ldap.PagedResultsResponseControl
08 Jun 2009 00:08:21,105 [Task Engine Worker 0] WARN sync.LdapUserDataSynchronizer - Failed to retrieve all remote users
org.springframework.ldap.OperationNotSupportedException:
[LDAP: error code 12 - Unavailable Critical Extension]; nested
exception is javax.naming.OperationNotSupportedException: [LDAP: error
code 12 - Unavailable Critical Extension]; remaining name ''
        at org.springframework.ldap.support.LdapUtils.convertLdapException(LdapUtils.java:199)
        at org.springframework.ldap.core.LdapTemplate.search(LdapTemplate.java:319)
        at org.springframework.ldap.core.LdapTemplate.search(LdapTemplate.java:259)
       
at
com.jivesoftware.community.user.sync.LdapUserDataSynchronizer.populateUsersUsingPaging(LdapUserDataSynchronizer.java:344)
        at com.jivesoftware.community.user.sync.LdapUserDataSynchronizer.getAllRemoteUsers(LdapUserDataSynchronizer.java:314)
        at com.jivesoftware.community.user.sync.LdapUserDataSynchronizer.doRun(LdapUserDataSynchronizer.java:188)
        at com.jivesoftware.util.task.AbstractPollableRunnable.run(AbstractPollableRunnable.java:108)
        at com.jivesoftware.util.cron.CronTask$TaskWrapper.run(CronTask.java:147)
        at com.jivesoftware.util.task.TaskEngine$TaskEngineWorker.run(TaskEngine.java:392)
Caused
by: javax.naming.OperationNotSupportedException: [LDAP: error code 12 -
Unavailable Critical Extension]; remaining name ''
        at com.sun.jndi.ldap.LdapCtx.mapErrorCode(LdapCtx.java:3065)
        at com.sun.jndi.ldap.LdapCtx.processReturnCode(LdapCtx.java:2951)
        at com.sun.jndi.ldap.LdapCtx.processReturnCode(LdapCtx.java:2758)
        at com.sun.jndi.ldap.LdapCtx.searchAux(LdapCtx.java:1812)
        at com.sun.jndi.ldap.LdapCtx.c_search(LdapCtx.java:1735)
        at com.sun.jndi.toolkit.ctx.ComponentDirContext.p_search(ComponentDirContext.java:368)
        at com.sun.jndi.toolkit.ctx.PartialCompositeDirContext.search(PartialCompositeDirContext.java:338)
        at com.sun.jndi.toolkit.ctx.PartialCompositeDirContext.search(PartialCompositeDirContext.java:321)
        at javax.naming.directory.InitialDirContext.search(InitialDirContext.java:248)
        at org.springframework.ldap.core.LdapTemplate$4.executeSearch(LdapTemplate.java:253)
        at org.springframework.ldap.core.LdapTemplate.search(LdapTemplate.java:293)
        ... 7 more
08 Jun 2009 00:08:21,106 [Task Engine Worker 0] WARN sync.LdapUserDataSynchronizer - Failed to sychronize users
java.lang.NullPointerException
       
at
com.jivesoftware.community.user.sync.LdapUserDataSynchronizer.populateUsersUsingPaging(LdapUserDataSynchronizer.java:353)
        at com.jivesoftware.community.user.sync.LdapUserDataSynchronizer.getAllRemoteUsers(LdapUserDataSynchronizer.java:314)
        at com.jivesoftware.community.user.sync.LdapUserDataSynchronizer.doRun(LdapUserDataSynchronizer.java:188)
        at com.jivesoftware.util.task.AbstractPollableRunnable.run(AbstractPollableRunnable.java:108)
        at com.jivesoftware.util.cron.CronTask$TaskWrapper.run(CronTask.java:147)
        at com.jivesoftware.util.task.TaskEngine$TaskEngineWorker.run(TaskEngine.java:392)

This error is occuring because your LDAP server does not support paged results and the application is trying to utilize them. You will need to disable this, which you can do with the following changes:

For 3.0.x:

Add the following sytem property and restart the server:

name: spring.ldapConfiguration.autoSetVersion
value: false 

For 2.5.x:

Place the attached file (spring-ldap.xml) in your jiveHome/etc directory and restart the server.