You can use LDAP (Lightweight Directory Access Protocol), including Active Directory, for authenticating Clearspace users. A standard for user authentication and for storing user profile data, LDAP is a powerful tool for large organizations (or organizations integrating many applications) to simplify user account management.
By default, Clearspace doesn't use LDAP. Instead, it stores all user data in a database and performs authentication with that data. When you select LDAP instead as the authentication system, you're asking that Clearspace authenticate against your LDAP server. During setup, you specify which users and groups from LDAP you want Clearspace to use (although you needn't use groups defined in LDAP). Clearspace will query your LDAP server to ensure that users and groups (if you want) are nominally represented in the Clearspace database (so that users can be associated with content), but will authenticate against your LDAP server.
This topic will guide you through configuring Clearspace to use your LDAP server for authentication. These instructions assume that you're a competent LDAP administrator and that you're familiar with the Clearspace admin console. Any LDAP-compliant server should work, including Active Directory.
Note: If you're using Active Directory, make sure it allows LDAP querying. You might also be interested in LDAP Querying Basics at the Microsoft web site, or LDAP Attributes at the Computer Performance web site.
The Clearspace setup tool will guide you through configuring Clearspace for use with LDAP. The setup tool is designed to prompt you for the minimum information Clearspace needs to connect to your LDAP server and retrieve the needed information. At each step along the way, the setup tool will prompt you to test the information you enter before moving forward; this reduces the chances that you'll inadvertently complete the process with settings that won't work in everyday use. Note: If you need to update configuration for LDAP after using the setup tool, you can do so by changing values for LDAP-related system properties. In the admin console, you'll find these at System > Management > System Properties; scroll to locate the properties you want to change.
The default Clearspace settings for LDAP will query for all users and groups available at the connection you specify; all of these users and groups will become Clearspace users and groups. If this isn't what you want, you can use an LDAP filter expression to limit the data retrieved from your server. You can also opt to use user data from your LDAP server, but not use its groups, instead defining groups using Clearspace.Note: Clearspace's use of LDAP user and group data is read-only; you can't make changes to LDAP data using Clearspace.
As you use the setup tool to configure Clearspace to use LDAP, you can make specific settings to meet your needs. The tool's three-step wizard includes separate steps for specifying which users to include and specifying which groups (if any) to include.
Here are a few common scenarios. You'll find more details below on how to get these results.
If you've just installed Clearspace, the setup tool will run the first time you access Clearspace. If you've already completed the setup process and need to use the tool again to configure LDAP, do the following:
Through three screens in the setup tool, you give information for connecting to the server, for querying for users, and how groups should be handled. At the outset, you choose a server type, such as Active Directory or OpenLDAP.
|First Name Field||givenName||givenName|
|Last Name Field||sn||sn|
Clearspace will use these values to query your LDAP server to retrieve information about the people who will be using Clearspace.
Note: If you're upgrading Clearspace from a version that supported only "Name Field," you can still switch the first-and-last configuration. After you upgrade, go to the admin console page at System > Management > System Properties. At the bottom of the page, add the following system properties:
Property Value ldap.firstNameField givenName ldap.lastNameField sn jive.user.lastname.firstname.enabled true
After you add the properties, navigate in the console to People > Settings > User Data Synchronization Settings. To pick up changes immediately, click Run Synchronization Task Now. If you already have synchronization enabled, you can also wait for its nightly run.
The default values will include all users found with the connection settings you gave. You can limit this to only certain users by using an LDAP filter expression.
For example, to retrieve only those users who work at the Portland office, you could enter something like the following in the User Filter box:
|Group Field||cn|| cn
|Member Field||member|| member
|Description Field||description|| description
|Member Field||memberOf||(Depends on installation.)|
Clearspace will use these values to query your LDAP server to retrieve information about the groups to use. The default values will include all groups found with the connection settings you gave. You can limit this to only certain groups by using an LDAP filter expression.
Note: In the Admin Account step of the Clearspace setup tool, you'll be prompted to choose a location for the admin account: LDAP (using the administrator from the LDAP server you just set up) or the database (meaning an account in the Clearspace database). If you choose LDAP, be sure to enter in the Current Username box the account of a valid LDAP user. The name displayed there by default might not be an account you can actually use.
You can get LDAP-specific debug information by selecting Yes for Enable Debug in the setup tool's Step 3: Connection Settings page.Note: If you turn on LDAP debugging, connection pooling will not be enabled.
You can also get broader Clearspace debug information by turning on verbose debugging inside the Clearspace application. Clearspace provides a fair number of debug messages. To enable this, turn on the debug log via the Log Viewer in the admin console. (In the console, go to System > Management > Log Viewer, click Enabled, then click Update. You'll need to restart the application server for this to take effect.) Due to the large amount of debug information this can generate (and the performance impact that has), you should run this only while developing or testing.
Once you've enabled debug messages, watch the jive.debug.log file. It should describe the steps it's going through to load users and authenticate them, as well as any errors it might run into. (You can view, download or email the debug log from within the admin console at the Log Viewer page described above.)
Some LDAP servers or application servers might 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>your.FactoryClassName</initialContextFactory> </ldap>
You might want to set Java system properties to change default pool settings. For more information, see the following pages:
Note: If you turn on LDAP debugging, connection pooling will not be enabled.
If you know that only some of the users in your LDAP database should be known to Clearspace, one way to get that subset is to create an LDAP group (such as "Clearspace users"), then filter off that group attribute for users. Here's an example:
This way you don't have to create any new OUs or move records around. You can simply modify group membership attributes on the user, something the LDAP administrator can do.