LDAP Information

Overview

LDAP (Lightweight Directory Access Protocol) has emerged as a dominant standard for user authentication and for storage of user profile data. It serves as a powerful tool for large organizations (or those organizations integrating many applications) to simplify user management issues.

By default, Jive Forums stores all user data in a database and performs authentication using database lookups. This LDAP module replaces that functionality and allows Jive Forums to:

• Use a LDAP server to authenticate a user's identity.
• Load and store user profile information in a LDAP directory.

This document will guide you through preparing your LDAP server and provide details about how to install the LDAP module on Jive Forums. These instructions assume that you're a competent LDAP user, and that you're familiar with Jive Forums setup issues. The iPlanet Directory Server 5.0 LDAP server was used for development and testing, but any LDAP compliant server should also work.

Choosing an LDAP storage mode

Two modes for storing user data in an LDAP directory are supported:

1. Mixed Mode (LDAP and User Database) -- Username, name and email are stored in LDAP. All Jive-specific data is stored in the Jive user database. This mode requires no changes to your LDAP directory.
2. Pure LDAP Mode -- All user data is stored in LDAP, including Jive-specific data. This mode requires you to make changes to your LDAP schema.

The first option is easier to setup and is generally the better solution. However, the second option is also appropriate in some cases. You'll choose the mode that you wish to use during the Jive Forums setup process.

The Jive Forums Setup Tool

The Jive Forums setup tool will allow you to configure the LDAP module. If you've already completed the setup process and need to use the tool again to configure LDAP, perform the following steps:

1. Stop your application server.
2. Edit jiveHome/jive_startup.xml and delete the <setup>true</setup> line.
3. Restart your application server and go to the setup tool in your browser.

Once you've entered the setup tool and are on the second setup step, choose LDAP as the authentication and user mode.

Next, you'll then be taken to a page to configure the LDAP setting for your server. A summary of the settings, their description and default values (if any) is below.

Note: All of these are required and must have values.

Name	Description	Default Value
host	LDAP server host; e.g. localhost or machine.example.com, etc.
port	LDAP server port number.	389
sslEnabled	Enable SSL connections to your LDAP server. If you enable SSL connections, the LDAP server port number most likely should be changed to 636. Note: SASL authentication is not supported.	false
usernameField	The field name that the username lookups will be performed on.	uid
nameField	The field name that holds the user's name.	cn
emailField	The field name that holds the user's email address.	mail
baseDN	The starting DN that searches for users will performed with. The entire subtree under the base DN will be searched for user accounts.
adminDN	A directory administrator's DN. All directory operations will be performed with this account. For normal usage of the module, the admin should have full administrative controls over the directory.
adminPassword	The password for the directory administrator.
debugEnabled	A value of "true" if debugging should be turned on. When on, trace information about BER buffers sent and received by the LDAP provider is written to System.out	false

Finally, on the last step of the setup process, you'll choose a user to become the inital system administrator.

Configuring your LDAP server

Note: if you use the "mixed mode" of the Jive Forums LDAP module, no changes to your LDAP directory are necessary. However, if you use the "pure mode", you'll need to make changes to your directory as detailed below.

Several custom LDAP attributes are used to store things such as the numeric Jive Forums user ID, the date the account was created, privacy flags, etc. The first step is to define these attributes in your LDAP directory.

Name	Type	OID	Multi-valued	Description
jiveUserID	Integer	1.3.6.1.4.1.10985.389.2	No	A numeric ID that Jive Forums uses to identify a user. Note: some LDAP servers may need this value to be a String in order to index the value properly. Second Note: some LDAP servers may need this value to be an integer and have the equality matching rule set to integerMatch.
jiveNameVisible	String	1.3.6.1.4.1.10985.389.3	No	The value is "true" if a user wishes to show their name publicly; "false" otherwise.
jiveEmailVisible	String	1.3.6.1.4.1.2.10985.389.4	No	The value is "true" if a user wishes to show their email address publicly; "false" otherwise.
jiveCDate	String	1.3.6.1.4.1.10985.389.6	No	The date the user became a Jive Forums user.
jiveMDate	String	1.3.6.1.4.1.10985.389.7	No	The date the user information was last updated.
jiveProps	String	1.3.6.1.4.1.10985.389.8	Yes	A collection of extended properties for the user.

Next, you can optionally create a new object class that uses the specified attributes (or modify an existing object to add the attributes). The Jive Forums LDAP module does not actually pay attention to object types, but only looks for the correct attributes. If you do create a new object, the object name should be "jivePerson" with an OID of 1.3.6.1.4.1.2.10985.389.1.

Each of the attributes listed above must be added as an optional attribute since the attributes will not be created until the user logs into Jive Forums for the first time.

Finally, you may wish to create an index on the "jiveUserID" attribute so that lookups on that field are fast.

How the "pure LDAP" mode works

Jive Forums: Readme The first time a user attempts to log in to the system, their LDAP user account is checked to see if they have a "jiveUserID" attribute defined. If they do not, it's assumed that they are logging into Jive Forums for the first time and all the user information is automatically created in their LDAP user entry. This behavior seamlessly allows you to integrate Jive Forums into an existing LDAP directory without making your users go through any special account creation process.

Other user operations will work normally. Additionally, the User.getProperty(String name) and User.setProperty(String name, String value) will get and set any LDAP user attribute. For example, if your user definition includes an attribute called "telephonenumber", you could get jsmith's telephone number with:

    AuthToken auth = AuthFactory.getAuthToken("jsmith", "somepass");
    ForumFactory factory = ForumFactory.getInstance(auth);
    UserManager userManager = factory.getUserManager();
    User user = userManager.getUser("jsmith");
    String telephoneNum = user.getProperty("telephonenumber");

The following operations are not currently supported, or don't work fully in the Jive LDAP module:

• Creating new users through the UserManager is not supported. Instead, users should be created through the LDAP directory and then Jive Forums will populate any existing user entries with Jive-specific data.
• Deleting a user doesn't delete an LDAP entry, but only removes their permissions, and marks their messages as anonymous.
• The UserManager.getUserCount() and UserManager.users() methods may not perform well with large numbers of users due to LDAP implementation limitations.

Please see the module Javadocs for more information, or reference the available source code directly.

Group integration

Optionally, you can configure the LDAP module to load group information from your LDAP directory. Group integration requires setting system properties (Admin Console -> System -> System Properties), as described below:

• GroupManager.className * -- set the value to "com.jivesoftware.base.ldap.LdapGroupManager".
• ldap.groupNameField * -- the field name that the groupname lookups will be performed on. If this property is not set, the default value is cn.
• ldap.groupMemberField -- the field name that holds the members in a group. If this property is not set, the default value is member.
• ldap.groupDescriptionField -- the field name that holds the description a group. If this property is not set, the default value is description.
• ldap.posixMode * -- a value of "true" means that users are stored within the group by their user name alone. A value of "false" means that users are stored by their entire DN within the group. If this property is not set, the default value is false. Note: the posix mode must be set correctly for your server in order for group integration to work.
• ldap.groupSearchFilter -- the search filter that should be used when loading groups. If this property is not set, the default value is ("ldap.groupNameField"={0}).

Debugging

Sometimes it is necessary to turn on verbose debugging inside of the Jive Forums application. The Jive Forums LDAP module has a fair amount of debug messages available. To enable this, turn on debug messages via the Log viewer in the admin tool (you'll need to restart the appserver for this to take effect). It is only recommended you run this in a debug or test environment because there can be quite a large amount of debug generated and might impact performance.

Once debug messages are enabled watch the jive.debug.log - it should detail steps its going through to load users and authenticate them as well as any errors it may run into.

Custom Inital Context Factory

Some LDAP servers or application servers may require that a different LDAP initial context factory be used rather than the default (com.sun.jndi.ldap.LdapCtxFactory). You can set a custom initial context factory by adding the following to jive_startup.xml:

<ldap>
    ... other ldap settings here 
    <initialContextFactory>com.foo.factoryClass</initialContextFactory>
</ldap>

Connection Pooling

The default LDAP provider (Sun's) support pooling of connections to the LDAP server. Connection pooling can greatly improve performance, especially on systems with high load. Connection pooling is enabled by default, but can be disabled by setting the Jive property ldap.connectionPoolEnabled to false:

<ldap>
    ... other ldap settings here 
    <connectionPoolEnabled>false</connectionPoolEnabled>
</ldap>

You should set several Java system properties to change default pool settings. For more information, see the following pages:

• http://java.sun.com/products/jndi/tutorial/ldap/connect/pool.html
• http://java.sun.com/products/jndi/tutorial/ldap/connect/config.html

Note that if you turn on LDAP debugging, connection pooling will not be enabled. If SSL LDAP mode is enabled, you must set a system property to enable pooling of SSL LDAP connections.