ldap-guide.html 9.67 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
	<title>Jive Messenger LDAP Guide</title>
  <link href="style.css" rel="stylesheet" type="text/css">
</head>
<body>
<a name="top"></a>

<h1>Jive Messenger LDAP Guide</h1>

<h2>Introduction</h2>

<p>
15 16
This document details how to configure your Jive Messenger installation to use 
an external LDAP store when authenticating users and loading user profile information.
Matt Tucker's avatar
Matt Tucker committed
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
</p>
<h2>Background</h2>
<p>
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.
</p>
<p>
By default, Jive Messenger stores all user data in a database and performs 
authentication using database lookups. The LDAP module replaces that 
functionality and allows Jive Messenger to:
<ul>
<li>
Use a LDAP server to authenticate a user's identity.
</li>
<li>
34
Load user profile information from a LDAP directory.
Matt Tucker's avatar
Matt Tucker committed
35 36
</li>
</ul>
37
<b>Note:</b> Jive Messenger treats the LDAP directory as read-only.
Matt Tucker's avatar
Matt Tucker committed
38 39
</p>
<p>
Matt Tucker's avatar
Matt Tucker committed
40
This document will guide you through configuring LDAP support in Jive Messenger. These
Matt Tucker's avatar
Matt Tucker committed
41
instructions assume that you're a competent LDAP user, and that you're familiar 
Matt Tucker's avatar
Matt Tucker committed
42
with Jive Messenger setup issues.
Matt Tucker's avatar
Matt Tucker committed
43 44 45 46
</p>

<h2>Configuration</h2>
<p>
Matt Tucker's avatar
Matt Tucker committed
47
In order to configure your server to use LDAP:
Matt Tucker's avatar
Matt Tucker committed
48 49
<ol>
<li>
Matt Tucker's avatar
Matt Tucker committed
50
Stop Jive Messenger.
Matt Tucker's avatar
Matt Tucker committed
51
</li>
Matt Tucker's avatar
Matt Tucker committed
52
<li>Edit <tt>conf/jive-messenger.xml</tt> in your Jive Messenger installation folder as described below.
Matt Tucker's avatar
Matt Tucker committed
53 54
</li>
<li>
Matt Tucker's avatar
Matt Tucker committed
55
Restart Jive Messenger.
Matt Tucker's avatar
Matt Tucker committed
56 57 58
</li>
</ol>
</p>
Matt Tucker's avatar
Matt Tucker committed
59
<h3>Editing the Config File</h3>
Matt Tucker's avatar
Matt Tucker committed
60
<p>
Matt Tucker's avatar
Matt Tucker committed
61
Open the configuration file <tt>conf/jive-messenger.xml</tt> from your Jive Messenger installation in your favorite
62 63
editor and add or change the following settings. Properties flagged with (<font color="red"><b>*</b></font>) must be set, 
all other properties are optional:
Matt Tucker's avatar
Matt Tucker committed
64 65
</p>
<ul>
66 67 68 69
<li><font color="red"><b>*</b></font> provider.user.className -- set the value to "org.jivesoftware.messenger.ldap.LdapUserProvider".</li>
<li><font color="red"><b>*</b></font> provider.auth.className -- set the value to "org.jivesoftware.messenger.ldap.LdapAuthProvider".</li>
<li><font color="red"><b>*</b></font> ldap.host -- LDAP server host; e.g. localhost or machine.example.com, etc.</li>
<li>ldap.port -- LDAP server port number. If this property is not set, the default value is 389.</li>
70
<li><font color="red"><b>*</b></font> ldap.baseDN -- the starting DN that searches for users will performed with. The entire   subtree under the base DN will be searched for user accounts.
Matt Tucker's avatar
Matt Tucker committed
71
</li>
72
<li>ldap.alternateBaseDN -- a second DN in the directory can optionally be set. If set, the alternate base DN will be used for authentication and loading single users, but will not be used to display a list of users (due to technical limitations).
Matt Tucker's avatar
Matt Tucker committed
73
<li>ldap.adminDN -- a directory administrator's DN. All directory operations will be performed
Matt Tucker's avatar
Matt Tucker committed
74 75
    with this account. The admin must be able to perform searches and load user records. The user does
    not need to be able to make changes to the directory, as Jive Messenger treats the directory as read-only.
76
    If this property is not set, an anonymous login to the server will be attempted.
Matt Tucker's avatar
Matt Tucker committed
77
</li>
Matt Tucker's avatar
Matt Tucker committed
78
<li>ldap.adminPassword -- the password for the directory administrator.</li>
79 80 81 82 83 84
<li>ldap.usernameField -- the field name that the username lookups will be performed on. If this property is not set,
    the default value is <tt>uid</tt></li>
<li>ldap.nameField -- the field name that holds the user's name. If this property is not set, the default value is
    <tt>cn</tt></li>
<li>ldap.emailField -- the field name that holds the user's email address. If this property is not set,
    the default value is <tt>mail</tt>.</li>
Matt Tucker's avatar
Matt Tucker committed
85 86 87
<li>ldap.debugEnabled -- a value of "true" if debugging should be turned on. When on, trace
    information about buffers sent and received by the LDAP provider is written to System.out</li>
<li>ldap.sslEnabled -- a value of "true" to enable SSL connections to your LDAP server. If you
88 89 90 91 92 93 94 95 96 97 98 99
    enable SSL connections, the LDAP server port number most likely should be changed to 636.</li>
<li>ldap.initialContextFactory --  the name of the class that should be used as an initial context
 		factory. if this value is not specified, "com.sun.jndi.ldap.LdapCtxFactory" will be used instead.
		Most users will not need to set this value.
<li>ldap.autoFollowReferrals -- a value of "true" indicates that LDAP referrals should be automatically
		followed. If this property is not set or is set to "false", the referral policy used is left up to
		to the provider. A referral is an entity that is used to redirect a client's request to another server. 
		A referral  contains the names and locations of other objects. It is sent by the server to indicate 
		that the information that the client has requested can be found at another location (or locations), 
		possibly at another server or several servers. 
<li>ldap.connectionPoolEnabled -- a value of "false" disables LDAP connection pooling. If this
		property is not set, the default value is "true".
Matt Tucker's avatar
Matt Tucker committed
100 101
</ul>
<p>
Matt Tucker's avatar
Matt Tucker committed
102
Below is a sample config file section:
Matt Tucker's avatar
Matt Tucker committed
103 104 105 106
</p>
<pre><code>
&lt;jive&gt;
...
Matt Tucker's avatar
Matt Tucker committed
107 108 109
    &lt;ldap&gt;
        &lt;host&gt;&lt;/host&gt;
        &lt;port>389&lt;/port&gt;
110
        &lt;usernameField&gt;uid&lt;/usernameField&gt;
Matt Tucker's avatar
Matt Tucker committed
111 112
        &lt;nameField&gt;cn&lt;/nameField&gt;
        &lt;emailField&gt;mail&lt;/emailField&gt;
Matt Tucker's avatar
Matt Tucker committed
113 114
        &lt;baseDN&gt;ou=People;dc=example;dc=com&lt;/baseDN&gt;
        &lt;adminDN&gt;cn=Directory Administrator&lt;/adminDN&gt;
Matt Tucker's avatar
Matt Tucker committed
115 116 117 118 119 120 121 122 123 124 125 126 127 128
        &lt;adminPassword&gt;&lt;/adminPassword&gt;
    &lt;/ldap&gt;
    &lt;provider&gt;
        &lt;user&gt;
            &lt;className&gt;org.jivesoftware.messenger.ldap.LdapUserProvider&lt;/className&gt;
        &lt;/user&gt;
        &lt;auth&gt;
            &lt;className&gt;org.jivesoftware.messenger.ldap.LdapAuthProvider&lt;/className&gt;
        &lt;/auth&gt;
    &lt;/provider&gt;
...
&lt;/jive&gt;
</code></pre>

129
<p>You'll most likely want to change which usernames are authorized to login to the
Matt Tucker's avatar
Matt Tucker committed
130 131 132 133 134 135 136 137 138 139 140 141
admin console. By default, only the user with username "admin" is allowed to login. However,
you may have different users in your LDAP directory that you'd like to be administrators. The
list of authorized usernames is controlled via the <tt>adminConsole.authorizedUsernames</tt>
property. For example, to let the usersnames "joe" and "jane" login to the admin console:</p>

<pre><code>
&lt;jive&gt;
...
    &lt;adminConsole&gt;
    ...
        &lt;authorizedUsernames&gt;joe, jane&lt;/authorizedUsernames&gt;
    &lt;/adminConsole&gt;
Matt Tucker's avatar
Matt Tucker committed
142 143 144
...
&lt;/jive&gt;
</code></pre>
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218


<p><a name="debugging"><h2>Custom Inital Context Factory</h2></a></p>

<p>
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_config.xml:

<pre>&lt;ldap&gt;
    ... other ldap settings here 
    &lt;initialContextFactory&gt;com.foo.factoryClass&lt;/initialContextFactory&gt;
&lt;/ldap&gt;</pre>   
</p>

<p><a name="connectionPool"><h2>Connection Pooling</h2></a></p>

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 <tt>ldap.connectionPoolEnabled</tt> 
to <tt>false</tt>:

<pre>&lt;ldap&gt;
    ... other ldap settings here 
    &lt;connectionPoolEnabled&gt;false&lt;/connectionPoolEnabled&gt;
&lt;/ldap&gt;</pre></p>

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

<li> <a href="http://java.sun.com/products/jndi/tutorial/ldap/connect/pool.html">
http://java.sun.com/products/jndi/tutorial/ldap/connect/pool.html</a>
<li> <a href="http://java.sun.com/products/jndi/tutorial/ldap/connect/config.html">
http://java.sun.com/products/jndi/tutorial/ldap/connect/config.html</a>

</ul>
</p>
	    
<p>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.</p>    

<h2>LDAP FAQ</h2>
<p>

<b>Can I create new users through Jive Messenger when using LDAP?</b>
<ul>No, Jive Messenger treats LDAP directories as read-only. Therefore, it's
not possible to create or edit users through the application.</ul>

<b>Why is the list of usernames not sorted in the admin console when using LDAP?</b>
<ul>Several popular LDAP servers such as OpenLDAP do not support server-side
sorting of search results. On those servers, users will appear out of order.</ul>

<b>I switched to LDAP and now cannot login to the admin console. What happened?</b>
<ul>If you can no longer login to the admin console after switching, one of two
things most likely happened:<ol>
			 <li>By default, only the username "admin" is allowed to login to the
			 admin console. Your directory may not contain a user with a username
			 of "admin". In that case, you should modify the list of usernames authorized 
			 to login to the admin console (see above).
			 <li>You may have set the baseDN to an incorrect value. The LDAP module
			 recursively searches for users under the node in the directory specified 
			 by the baseDN. When the baseDN is incorrect, no users will be found.
</ol>
You can also enable debugging to get more information from the LDAP module. To
do this, add &lt;log&gt;&lt;debug&gt;&lt;enabled&gt;true&lt;/enabled&gt;&lt;/debug&gt;&lt;/log&gt; 
to your <tt>conf/jive_messenger.xml</tt> file. Log statements will be written 
to the <tt>logs/debug.log</tt> file.
</ul>


Matt Tucker's avatar
Matt Tucker committed
219
</body>
Matt Tucker's avatar
Matt Tucker committed
220
</html>