ldap-guide.html 18.6 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2

Matt Tucker's avatar
Matt Tucker committed
3 4
<html>
<head>
5 6
<title>Jive Software - Wildfire: LDAP Guide</title>
<link href="style.css" rel="stylesheet" type="text/css">
Matt Tucker's avatar
Matt Tucker committed
7 8
</head>
<body>
9 10 11

<div id="pageContainer">

Matt Tucker's avatar
Matt Tucker committed
12 13
<a name="top"></a>

14 15 16 17 18 19 20 21 22
	<div id="pageHeader">
		<div id="logo"></div>
		<h1>LDAP Guide</h1>
	</div>
	<div class="navigation">
		<a href="index.html">&laquo; Back to documentation index</a>
	</div>

	<div id="pageBody">
Matt Tucker's avatar
Matt Tucker committed
23 24 25 26

<h2>Introduction</h2>

<p>
27
    This document details how to configure your Wildfire installation to use
Matt Tucker's avatar
Matt Tucker committed
28 29 30 31 32
    an external directory such as Open LDAP or Active Directory. Integration with a directory
    lets users authenticate using their directory username and password.
    Optionally, you can configure Wildfire to load user profile and group information from the directory.
    Any group in Wildfire can be designated as a shared group, which means that you can pre-populate user's
    rosters using directory groups.
Matt Tucker's avatar
Matt Tucker committed
33
</p>
34

Matt Tucker's avatar
Matt Tucker committed
35
<h2>Background</h2>
36

Matt Tucker's avatar
Matt Tucker committed
37
<p>
38 39 40
    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
Matt Tucker's avatar
Matt Tucker committed
41 42 43 44
    applications) to simplify user management issues. Many LDAP servers are available,
    such as <a href="http://www.openldap.org/">Open LDAP</a>, 
    <a href="http://www.microsoft.com/windowsserver2003/technologies/directory/activedirectory/">Active Directory</a>, 
    and Novell's <a href="http://www.novell.com/products/edirectory/">eDirectory</a>.
45

Matt Tucker's avatar
Matt Tucker committed
46
</p>
47

Matt Tucker's avatar
Matt Tucker committed
48
<p>
Matt Tucker's avatar
Matt Tucker committed
49
    By default, Wildfire stores all user data in its database and performs
50
    authentication using database lookups. The LDAP module replaces that
51
    functionality and allows Wildfire to:
52 53 54 55 56
    <ul>
        <li>Use a LDAP server to authenticate a user's identity.</li>
        <li>Load user profile information from a LDAP directory.</li>
        <li>Load group information from an LDAP directory.</li>
    </ul>
57

Matt Tucker's avatar
Matt Tucker committed
58
    <b>Note:</b> Wildfire treats the LDAP directory as read-only. 
Matt Tucker's avatar
Matt Tucker committed
59
</p>
60

Matt Tucker's avatar
Matt Tucker committed
61
<p>
62
    This document will guide you through configuring LDAP support in Wildfire. These
63
    instructions assume that you're a competent LDAP user, and that you're familiar
64
    with Wildfire setup issues.
Matt Tucker's avatar
Matt Tucker committed
65 66 67
</p>

<h2>Configuration</h2>
68

Matt Tucker's avatar
Matt Tucker committed
69
<p>
70 71
    In order to configure your server to use LDAP:
    <ol>
72

73
        <li>
74
            Stop Wildfire.
75
        </li>
76
        <li>Edit <tt>conf/wildfire.xml</tt> in your Wildfire installation folder as
77 78 79
            described below.
        </li>
        <li>
80
            Restart Wildfire.
81 82
        </li>
    </ol>
83

Matt Tucker's avatar
Matt Tucker committed
84
</p>
85

Matt Tucker's avatar
Matt Tucker committed
86
<h3>Editing the Config File</h3>
87

Matt Tucker's avatar
Matt Tucker committed
88
<p>
89
    Open the configuration file <tt>conf/wildfire.xml</tt> from your Wildfire
90 91 92 93 94 95
    installation in your favorite
    editor and add or change the following settings. Properties flagged with (<font color="red">
    <b>*</b></font>)
    must be set. Properties flagged with (<font color="red"><b>**</b></font>) must be set in order
    to enable LDAP group
    support, all other properties are optional:
96

Matt Tucker's avatar
Matt Tucker committed
97 98
</p>
<ul>
Matt Tucker's avatar
Matt Tucker committed
99 100
    <b>Main Settings</b><br><br>

101
    <li>provider.user.className <font color="red"><b>*</b></font> -- set the value to
102
        "org.jivesoftware.wildfire.ldap.LdapUserProvider".</li>
103
    <li>provider.auth.className <font color="red"><b>*</b></font> -- set the value to
104
        "org.jivesoftware.wildfire.ldap.LdapAuthProvider".</li>
105

106
    <li>ldap.host <font color="red"><b>*</b></font> -- LDAP server host; e.g. localhost or
107 108 109
        machine.example.com, etc. It is possible to use many LDAP servers but all of them
        <b>should share the same configuration</b> (e.g. SSL, baseDN, admin account, etc).
        To specify many LDAP servers use the comma or the white space character as delimiter.</li>
110 111 112 113 114 115
    <li>ldap.port -- LDAP server port number. If this property is not set, the default value is
        389.</li>
    <li>ldap.baseDN <font color="red"><b>*</b></font> -- the starting DN that searches for users
        will performed with.
        The entire subtree under the base DN will be searched for user accounts.
    </li>
116

117 118 119 120 121
    <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
122
    <li>ldap.adminDN -- a directory administrator's DN. All directory operations will be
123 124 125
            performed
            with this account. The admin must be able to perform searches and load user records. The
            user does
126
            not need to be able to make changes to the directory, as Wildfire treats the
127 128 129
            directory as read-only.
            If this property is not set, an anonymous login to the server will be attempted.
        </li>
Matt Tucker's avatar
Matt Tucker committed
130 131
    <li>ldap.adminPassword -- the password for the directory administrator.</li>
    <li>ldap.usernameField -- the field name that the username lookups will be performed on. If
132 133
            this property is not set, the default value is <tt>uid</tt>. Active Directory users
            should try the default value <tt>sAMAccountName</tt>.</li>
Matt Tucker's avatar
Matt Tucker committed
134
    <li>ldap.nameField -- the field name that holds the user's name. If this property is not
135 136
            set, the default value is <tt>cn</tt>. Active Directory users should use the default value
            <tt>displayName</tt>.</li>
137

Matt Tucker's avatar
Matt Tucker committed
138
    <li>ldap.emailField -- the field name that holds the user's email address. If this property
139 140
            is not set, the default value is <tt>mail</tt>. Active Directory users should use the
            the default value <tt>mail</tt>.</li>
Matt Tucker's avatar
Matt Tucker committed
141 142 143 144 145 146 147
     <li>ldap.searchFields -- the LDAP fields that will be used for user searches. If
        this property is not set, the username, name, and email fields will be searched. An example
        value for this field is "Username/uid,Name/cname". That searches the uid and cname fields
        in the directory and labels them as "Username" and "Name" in the search UI. You can add
        as many fields as you'd like using comma-delimited "DisplayName/Field" pairs. You should
        ensure that any fields used for searching are properly indexed so that searches return
        quickly.</li>
148
    <li>ldap.searchFilter -- the search filter that should be used when loading users. If this
Matt Tucker's avatar
Matt Tucker committed
149
        property is not set, the default search will be for users that have the attribute specified by
150
        ldap.usernameField.
Matt Tucker's avatar
Matt Tucker committed
151 152 153 154 155 156 157 158 159 160

    <br><br>
    <b>Group Settings</b><br><br>

    <li>provider.group.className <font color="red"><b>**</b></font> -- set the value to
        "org.jivesoftware.wildfire.ldap.LdapGroupProvider".</li>
    <li>ldap.groupNameField <font color="red"><b>**</b></font> -- the field name that the groupname
        lookups will be performed on. If this property is not set, the default value is <tt>cn</tt>.</li>
    <li>ldap.groupMemberField -- the field name that holds the members in a group. If this property
        is not set, the default value is <tt>member</tt>.</li>
161

Matt Tucker's avatar
Matt Tucker committed
162 163 164 165 166 167 168
    <li>ldap.groupDescriptionField -- the field name that holds the description a group. If this
        property is not set, the default value is <tt>description</tt>.</li>
    <li>ldap.posixMode <font color="red"><b>**</b></font> -- 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 <tt>false</tt>. <b>Note:</b>
        the posix mode must be set correctly for your server in order for group integration to
        work.</li>
169

Matt Tucker's avatar
Matt Tucker committed
170 171 172 173 174 175 176
    <li>ldap.groupSearchFilter -- the search filter that should be used when loading groups. If this
        property is not set, the default value is <tt>("ldap.groupNameField"={0})</tt>.</li>

    <br><br>
    <b>Connection Settings</b><br><br>

    <li>ldap.debugEnabled -- a value of "true" if debugging should be turned on. When on, trace
177 178
            information about buffers sent and received by the LDAP provider is written to
            System.out</li>
Matt Tucker's avatar
Matt Tucker committed
179
    <li>ldap.sslEnabled -- a value of "true" to enable SSL connections to your LDAP server. If
180 181 182
            you
            enable SSL connections, the LDAP server port number most likely should be changed to
            636.</li>
183

184 185 186 187 188 189
    <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
Matt Tucker's avatar
Matt Tucker committed
190 191 192 193 194
        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.
195 196
    <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
197

Matt Tucker's avatar
Matt Tucker committed
198
</ul>
199

Matt Tucker's avatar
Matt Tucker committed
200
<p>
201
    Below is a sample config file section:
Matt Tucker's avatar
Matt Tucker committed
202
</p>
203
<pre>
204 205 206
    &lt;jive&gt;
      ...
      &lt;ldap&gt;
207

Matt Tucker's avatar
Matt Tucker committed
208 209
        &lt;host&gt;&lt;/host&gt;
        &lt;port>389&lt;/port&gt;
210
        &lt;usernameField&gt;uid&lt;/usernameField&gt;
Matt Tucker's avatar
Matt Tucker committed
211
        &lt;nameField&gt;cn&lt;/nameField&gt;
212

Matt Tucker's avatar
Matt Tucker committed
213
        &lt;emailField&gt;mail&lt;/emailField&gt;
Matt Tucker's avatar
Matt Tucker committed
214 215
        &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
216
        &lt;adminPassword&gt;&lt;/adminPassword&gt;
217

218 219
      &lt;/ldap&gt;
      &lt;provider&gt;
Matt Tucker's avatar
Matt Tucker committed
220
        &lt;user&gt;
221
          &lt;className&gt;org.jivesoftware.wildfire.ldap.LdapUserProvider&lt;/className&gt;
Matt Tucker's avatar
Matt Tucker committed
222
        &lt;/user&gt;
223

Matt Tucker's avatar
Matt Tucker committed
224
        &lt;auth&gt;
225
          &lt;className&gt;org.jivesoftware.wildfire.ldap.LdapAuthProvider&lt;/className&gt;
Matt Tucker's avatar
Matt Tucker committed
226
        &lt;/auth&gt;
227
        &lt;group&gt;
228
          &lt;className&gt;org.jivesoftware.wildfire.ldap.LdapGroupProvider&lt;/className&gt;
229

230
        &lt;/group&gt;
231 232 233
      &lt;/provider&gt;
      ...
    &lt;/jive&gt;
234
</pre>
Matt Tucker's avatar
Matt Tucker committed
235

236
<p>You'll most likely want to change which usernames are authorized to login to the
237 238
    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
239
    list of authorized usernames is controlled via the <tt>admin.authorizedUsernames</tt>
240
    property. For example, to let the usersnames "joe" and "jane" login to the admin console:</p>
Matt Tucker's avatar
Matt Tucker committed
241

242
<pre>
243 244
    &lt;jive&gt;
      ...
245
      &lt;admin&gt;
246
        ...
Matt Tucker's avatar
Matt Tucker committed
247
        &lt;authorizedUsernames&gt;joe, jane&lt;/authorizedUsernames&gt;
248
      &lt;/admin&gt;
249

250 251
      ...
    &lt;/jive&gt;
252
</pre>
253

Matt Tucker's avatar
Matt Tucker committed
254
<p><a name=""><h2>Custom Search Filter</h2></a></p>
255

256
<p>By default, Wildfire will load all objects under the baseDN that
257 258 259 260 261 262 263 264 265
    have the attribute specified by <tt>ldap.usernameField</tt>. In the
    case that the username field is set to "uid", the search for all users
    would be "(uid=*)". However, there are cases when this logic does
    not work -- for example, when a directory contains other objects besides
    users but all objects share "uid" as a unique identifier field. In that
    case, you may need to specify a custom search filter using
    <tt>ldap.searchFilter</tt>. As an example, a search filter for all users
    with a "uid" and a "cn" value of "joe" would
    be:</p>
266 267 268 269

<pre>(&(uid={0})(cn=joe))</pre>

<p>The "{0}" value in the filter above is a token that should be present in
270 271
    all custom search filters. It will be dynamically replaced with "*" when
    loading the list of all users or a username when loading a single user.</p>
272 273

<p>Some custom search filters may include reserved XML entities such as
274
    "&". In that case, you must enter the search filter into the wildfire.xml
275
    file using CDATA:
276

277
    <pre>&lt;searchFilter&gt;&lt;![CDATA[(&(sAMAccountName={0})(|(givenName=GEORGE)(givenName=admin)))]]&gt;&lt;/searchFilter&gt;</pre>
278

279
    <p><a name="ctxFactory"><h2>Custom Inital Context Factory</h2></a></p>
280

281
    <p>
282

283 284
        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).
285
        You can set a custom initial context factory by adding the following to wildfire.xml:
286 287 288 289

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

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

296 297 298 299 300
    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>:
301

302 303 304
    <pre>&lt;ldap&gt;
        ... other ldap settings here
        &lt;connectionPoolEnabled&gt;false&lt;/connectionPoolEnabled&gt;
305

306
        &lt;/ldap&gt;</pre></p>
307 308

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

313 314 315 316
        <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>
317

318
    </ul>
319
</p>
320

321
<p>Note that if you turn on LDAP debugging, connection pooling will not be enabled.
322 323 324 325 326 327 328 329 330 331
    If SSL LDAP mode is enabled, you must set a system property to enable pooling of
    SSL LDAP connections.</p>

<p><a name="vcard"><h2>LDAP vCard Integration</h2></a></p>

<p>The LDAP vCard provider will expose LDAP profile information as vCard data for XMPP
clients that support the XMPP vCard extension. First, enable the provider:</p>

<pre>
    &lt;provider&gt;
332

333 334
      ...
      &lt;vcard&gt;
335
        &lt;className&gt;org.jivesoftware.wildfire.ldap.LdapVCardProvider&lt;/className&gt;
336 337 338 339 340
      &lt;/vcard&gt;
      ...
    &lt;/provider&gt;
</pre>

341
<p>Next, you must add mappings between LDAP fields and vCard fields in the wildfire.xml file.
342 343 344 345 346 347 348 349 350 351 352 353 354 355
    The vcard attributes are configured by adding an attrs="attr1,attr2" attribute to the vcard
    elements. Arbitrary text can be used for the element values as well as MessageFormat style
    placeholders for the ldap attributes. For example, if you wanted to map the LDAP attribute
    displayName to the vcard element FN, the XML snippet would be:
    &lt;FN attrs="displayName"&gt;{0}&lt;/FN&gt;</p>

<p>The vCard XML must be escaped in CDATA and must also be well formed. It is the exact
    XML this provider will send to a client after after stripping attr attributes and populating
    the placeholders with the data retrieved from LDAP. This system should be flexible enough to
    handle any client's vCard format. An example mapping follows.</p>

<pre>
    &lt;ldap&gt;
      &lt;vcard-mapping&gt;
356

357 358 359 360 361
        &lt;![CDATA[
          &lt;vCard xmlns='vcard-temp'&gt;
            &lt;FN attrs=&quot;displayName&quot;&gt;{0}&lt;/FN&gt;
            &lt;NICKNAME attrs=&quot;uid&quot;&gt;{0}&lt;/NICKNAME&gt;
            &lt;BDAY attrs=&quot;dob&quot;&gt;{0}&lt;/BDAY&gt;
362

363 364 365 366 367
            &lt;ADR&gt;
              &lt;HOME/&gt;
              &lt;EXTADR&gt;Ste 500&lt;/EXTADR&gt;
              &lt;STREET&gt;317 SW Alder St&lt;/STREET&gt;
              &lt;LOCALITY&gt;Portland&lt;/LOCALITY&gt;
368

369 370 371 372
              &lt;REGION&gt;Oregon&lt;/REGION&gt;
              &lt;PCODE&gt;97204&lt;/PCODE&gt;
              &lt;CTRY&gt;USA&lt;/CTRY&gt;
            &lt;/ADR&gt;
373

374 375 376 377 378
            &lt;TEL&gt;
              &lt;HOME/&gt;
              &lt;VOICE/&gt;
              &lt;NUMBER attrs=&quot;telephoneNumber&quot;&gt;{0}&lt;/NUMBER&gt;
            &lt;/TEL&gt;
379

380 381 382 383 384
            &lt;EMAIL&gt;
            &lt;INTERNET/&gt;
            &lt;USERID attrs=&quot;mail&quot;&gt;{0}&lt;/USERID&gt;
            &lt;/EMAIL&gt;
            &lt;TITLE attrs=&quot;title&quot;&gt;{0}&lt;/TITLE&gt;
385

386 387 388 389
            &lt;ROLE attrs=&quot;&quot;&gt;{0}&lt;/ROLE&gt;
            &lt;ORG&gt;
              &lt;ORGNAME attrs=&quot;o&quot;&gt;{0}&lt;/ORGNAME&gt;
              &lt;ORGUNIT attrs=&quot;&quot;&gt;{0}&lt;/ORGUNIT&gt;
390

391 392 393 394 395
            &lt;/ORG&gt;
            &lt;URL attrs=&quot;labeledURI&quot;&gt;{0}&lt;/URL&gt;
            &lt;DESC attrs=&quot;uidNumber,homeDirectory,loginShell&quot;&gt;
            uid: {0} home: {1} shell: {2}
            &lt;/DESC&gt;
396

397 398 399 400 401
          &lt;/vCard&gt;
        ]]&gt;
      &lt;/vcard-mapping&gt;
    &lt;/ldap&gt;
</pre>
402 403

<h2>LDAP FAQ</h2>
404

405 406
<p>

407 408
    <b>Can I create new users through Wildfire when using LDAP?</b>
    <ul>No, Wildfire treats LDAP directories as read-only. Therefore, it's
409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429
        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.
        However, you can enable client-side sorting of search results by setting
        <tt>ldap.clientSideSorting</tt> to true in the XML configuration file.</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;
430

431
        to your <tt>conf/wildfire.xml</tt> file. Log statements will be written
432 433
        to the <tt>logs/debug.log</tt> file.
    </ul>
434 435


436 437 438 439
	</div>

</div>

Matt Tucker's avatar
Matt Tucker committed
440
</body>
Matt Tucker's avatar
Matt Tucker committed
441
</html>