Guide to Troubleshooting LDAP/Active Directory Integration

Version 39

    Please note that most of this information has been rolled into the official Jive product documentation at https://docs.jivesoftware.com/

     

    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?

     

    KeyExample ValueExplanation of Field
    ldap.serverType.id*2 = AD, 3 = openLDAP, 4 = otherCode for the type of LDAP instance
    ldap.host*ldap.jive.comHostname or IP address of LDAP Server
    ldap.port*389 (default) or 636 (SSL)Port number of LDAP server
    ldap.usernameField*uidThe LDAP field name used for looking up username values
    ldap.baseDN*
    DC=support,DC=jive,DC=com
    The Distinguished Name of the base of your ldap tree.
    ldap.nameField^cnThe element key for the name attribute.
    ldap.firstNameField^givenNameFirst name element in LDAP.
    ldap.lastNameField^snSurname element in LDAP
    ldap.emailField*mailEmail element in LDAP.
    ldap.connectionPoolEnabledtrueDetermines if LDAP connection pooling is enabled (http://java.sun.com/products/jndi/tutorial/ldap/connect/config.html).
    ldap.followReferralstrueDetermines whether or not LDAP queries will follow referrals. Should always be 'true' when using Active Directory.
    ldap.adminDN*

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

    The DN for the LDAP admin user.
    ldap.adminPassword*a54313f2d3bc98fb5234566995246c7The encrypted Admin password.
    ldap.adminPassword.key* jOK2yjeI8h53UFB5A key used to encrypt the Admin password.
    ldap.adminPassword.encrypted*trueDetermines whether or not the Admin password is encrypted. Should be 'true'.
    ldap.ldapDebugEnabledfalseTurn on LDAP debug logging (This is VERY verbose! Do not use in Production except when troubleshooting!)
    ldap.sslEnabledfalseUse an SSL connection to communicate with LDAP server.
    ldap.initialContextFactory
    ldap.searchFilter(&(sAMAccountName={0})(objectClass=Person)The field that identifies this LDIF in terms of what user it describes.
    ldap.groupNameFieldcnThe field that maps a group to its CN in LDAP.
    ldap.groupMemberFieldmemberThe field that maps a group to its members.
    ldap.groupDescriptionFielddescriptionMaps a description of a group.
    ldap.posixModefalseConnect to LDAP in posix mode.
    ldap.posixEnabledfalseConnect to LDAP in posix mode.
    ldap.groupSearchFilter^(objectClass=group)The field that describes what key/value pair to expect when looking for a LDIF to delineate it's a group LDIF.
    ldap.managerFieldmanagerMaps the DN of a person's manager. (Used when synching relationships)
    ldap.managerFieldTypee.g. uid, sAMAccountName

    Sets the type of field in LDAP that identifies a user's manager.  Default is null, which means the value will be

    treated as schema default, which is a Distinguished Name, and resolved accordingly.  However, this can also beset to an attribute name (like "uid" or "sAMAccountName"), which will be compared in a search against the value of the record's manager field.

     

     

    Value must match up to attribute to look up.

    ldap.photoFieldphotoMaps a photo to a user's profile.
    ldap.lastUpdatedFieldcreationdateUsed to check if an LDAP record has been updated since the most recent sync.
    ldap.userGroupMember^memberOfThe field that maps a user to a group. (Should see on the user LDIF).
    ldap.userDN^ou=PeopleA RDN (relative to the baseDN) which contains users to sync to SBS.
    jive.sync.user.ldaptrueDetermines whether or not  user synchronizations are enabled.
    jive.sync.relationships.ldapfalseDetermines whether or not user relationships are synchronized from LDAP.
    jive.sync.profile.ldap.photofalseDetermines whether or not profile photos are synchronized from LDAP.
    jive.sync.profile.ldap.loginfalseDetermines whether or not profiles are synchronized at login.
    jive.sync.auto.disabletrueSpecifies whether Jive should disable user accounts which cannot be found in the LDAP directory.
    jive.sync.auto.disable.att.nameuserAccountControlThe name of the attribute which indicates whether or not an account is disabled in LDAP.
    jive.sync.auto.disable.att.value514 (see link)

    In Active Directory, use the following guide: http://support.microsoft.com/kb/305144

     

    You can also set up a bit-specific filter, like this: userAccountControl:1.2.840.113556.1.4.803:=2

    GroupManager.className

    com.jivesoftware.base.ldap.LdapGroupManager for LDAP groups;

    com.jivesoftware.base.database.DbGroupManager to use default group manager

    Controls whether or not permission groups are synched from LDAP.

     

    * Default/Required fields

    ^ Recommended fields

     

    Here's a couple handy links with details for configuring LDAP settings:

     

    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:

    dn: CN=Cyr \, Karl,OU=Jive_Users,DC=support,DC=jive,DC=com
    changetype: add
    objectClass: top
    objectClass: person
    objectClass: organizationalPerson
    objectClass: user
    cn: Cyr , Karl
    sn: Cyr
    physicalDeliveryOfficeName: Awesome
    givenName: Karl
    initials: KC
    distinguishedName: CN=Cyr \, Karl,OU=Jive_Users,DC=support,DC=jive,DC=com
    instanceType: 4
    whenCreated: 20081119215504.0Z
    whenChanged: 20090202220617.0Z
    displayName: Cyr , Karl
    uSNCreated: 4391224
    memberOf: CN=FilterGroup,OU=Jive_Users,DC=support,DC=jive,DC=com
    uSNChanged: 4399897
    department: Awesome
    name: Cyr , Karl
    objectGUID:: 2tnXRo7VxE6zc72YqLtOTw==
    userAccountControl: 66048
    badPwdCount: 1
    codePage: 0
    countryCode: 0
    badPasswordTime: 128769530029375000
    lastLogoff: 0
    lastLogon: 128742007081093750
    pwdLastSet: 128716053043750000
    primaryGroupID: 513
    objectSid:: AQUAAAAAAAUVAAAAF8sUcR3r8QcekDXQw9wAAA==
    accountExpires: 9223372036854775807
    logonCount: 0
    sAMAccountName: karl
    sAMAccountType: 805306368
    userPrincipalName: karl@support.jive.com
    objectCategory: CN=Person,CN=Schema,CN=Configuration,DC=support,DC=jive,DC=com
    dSCorePropagationData: 20081119220919.0Z
    dSCorePropagationData: 20081119220919.0Z
    dSCorePropagationData: 20081119220919.0Z
    dSCorePropagationData: 16010108151056.0Z
    mail: karl@fake.com

      

    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:

     

    ldifde -f output.txt -d ou=Jive_Users,dc=support,dc=jive,dc=com

     

     

     

    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 > User Data Synchronization Settings)

     

    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.

     

    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).

     

    Paging errors during the batch synchronization process

     

    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 may occur because your LDAP server does not support paged results. To confirm try the following:

     

    You can run this to figure out if PagedResults is supported: http://ldapwiki.willeke.com/wiki/View%20the%20Available%20Controls

     

    If OID 1.2.840.113556.1.4.319 is not in the list, your LDAP server does not support paged results. SunOne, for example does not support this control. All versions of Active Directory should support paging.

     

    If you have confirmed that your server does not support paging and you are still seeing these errors, disable paging with the following method:

     

    For 3.0.x+:

     

    Add the following sytem property and restart the server:

     

    name: spring.ldapConfiguration.autoSetVersion
    value: false

     

    For 5.0.4+/6.0.0+

    Add these system properties:

    ldap.sync.usePagingControl = false
    ldap.sync.useVirtualListViewControl = false
     

     

    Referral Timeouts

    Another common issue is referral timeouts. The symptoms of this issue are exceptionally long login times, failed synchronizations, and page timeouts during authentication. If you're experiencing this problem, please refer to this document: Active Directory Referral Timeouts

     

     

    How do I convert non-federated (database) user accounts to federated (LDAP) user accounts?

    Please see: Convert application-created users to LDAP users

     

     

    LDAP usernames and Case-sensitivity

    LDAP is case-insensitive. This means that you should ensure that the system property jive.usernames.case.insensitive = true if you are using LDAP as a user datastore.

     

     

     

    How to test your LDAP settings in 10 minutes or less

    Follow the steps in this document: How to test your LDAP settings in 10 minutes or less

     

     

    Does Jive integrate with the Active Directory Global Catalog? What about ADAM?

    Jive can integrate with both the Global Catalog (port 3268/3269) and Active Directory Application Mode (ADAM). In some circumstances, connecting to the Global Catalog is a preferred way of avoiding issues caused by referral resolutions.

     

     

    Tools and Resources

     

     

    jive-ask-a-question.png?a=145945776139