This page last changed on May 09, 2006 by david.soul@atlassian.com.
Old Documentation Notice
A new improved LDAP integration was introduced in Confluence 2.1.
This document describes the 'old style' OSUser LDAP integration. You MUST use this document if you are delegating user management to Jira.
Otherwise, if you are new to Confluence and have not set up LDAP integration before, we recommend using the new LDAP integration.

Introduction

Many organizations have an LDAP directory acting as a centralized database of system users. Confluence is able to authenticate users against their LDAP password.

This kind of LDAP integration is limited to checking passwords against the LDAP repository. For advanced LDAP group management, you can use the new LDAP integration in Confluence 2.1 and later.

Before starting this guide, please ensure you have gone through the normal Confluence installation process, including setting up the administrative user. Once this is done, you can apply the changes below to enable LDAP integration.

If you're starting with a brand new Confluence installation, a summary of process looks like this:

  1. Log in as the Confluence administrator, and for each LDAP user who should be able to log in to Confluence:
    • Add a new user in Confluence with the same username as in LDAP. The user's password in Confluence can be set to anything, because the password will be checked against LDAP.
    • Configure groups for the user as appropriate.
  2. Edit the OSUser configuration file to add LDAP authentication.
  3. Restart Confluence.
  4. You can now log out, and log back in as any user, using the LDAP password.

If you have an existing users and groups in Confluence, all you need to do it edit the OSUser configuration file and restart Confluence.

Instructions

In Confluence, user management is handled by OSUser, a pluggable user management framework. OSUser is configured through the WEB-INF/classes/osuser.xml file.

Default osuser.xml providers
<provider class="bucket.user.providers.CachingCredentialsProvider">
	<property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateCredentialsProvider</property>
	<property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property>
</provider>
<provider class="bucket.user.providers.CachingAccessProvider">
	<property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateAccessProvider</property>
	<property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property>
</provider>
<provider class="bucket.user.providers.CachingProfileProvider">
	<property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateProfileProvider</property>
	<property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property>
</provider>

CredentialsProviders are responsible for checking usernames and passwords, which is what we are interested in here. The default CachingCredentialsProvider looks in the Confluence database. We are going to add a ConfluenceLDAPCredentialsProvider, so that LDAP users can also be authenticated:

With LDAP authentication added
<provider class="com.atlassian.confluence.user.ConfluenceLDAPCredentialsProvider">
	<property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property>
	<property name="java.naming.provider.url">ldap://localhost:389</property>
	<property name="searchBase">dc=atlassian,dc=com</property>
	<property name="uidSearchName">cn</property>
	<!--
	<property name="java.naming.security.principal">cn=Manager,dc=atlassian,dc=com</property>
	<property name="java.naming.security.credentials">secret</property>
	<property name="exclusive-access">true</property>
	-->
</provider>
<provider class="bucket.user.providers.CachingCredentialsProvider">
	<property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateCredentialsProvider</property>
	<property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property>
</provider>
<provider class="bucket.user.providers.CachingAccessProvider">
	<property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateAccessProvider</property>
	<property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property>
</provider>
<provider class="bucket.user.providers.CachingProfileProvider">
	<property name="chain.classname">com.opensymphony.user.provider.hibernate.HibernateProfileProvider</property>
	<property name="chain.configuration.provider.class">bucket.user.BucketHibernateConfigProvider</property>
</provider>

You will need to update the following properties to suit your LDAP server:

  • url (currently set to ldap://localhost:389)
  • searchBase (currently set to dc=atlassian,dc=com)
  • uidSearchName (currently set to cn)

If your LDAP server is not configured to allow anonymous lookups, you need to:

  1. remove comment tags
  2. enter the username; including searchBase (currently set to cn=Manager,dc=atlassian,dc=com)
  3. enter password (currently set to secret)

How it works

It is useful to have a general idea of how this setup works. This section outlines some consequences of the current implementation, and provides some help for people experiencing LDAP connection problems.

Only password-checking for LDAP users done in Confluence

The main point to realise is that user profiles are still managed in Confluence (the CachingProfileProvider in osuser.xml). Only the password lookup is done against LDAP, and only if the Confluence username coincides with a LDAP username.

Technically, this behaviour is due to Credentials (password) checking being a separate operation to user-profile lookups. The profile can be loaded from the Confluence database, but the password looked up from LDAP. Furthermore, multiple credentials providers can be specified (here, LDAP and OSUser), and if one fails, the other will be used. This allows non-LDAP users to log in with their Confluence password.

Not all LDAP users have Confluence access

Another effect of this implementation is that LDAP users do not automatically have access to Confluence. A Confluence account must be created for each user wishing to use Confluence.

This is because each Confluence user has a set of groups (for example, 'confluence-users') stored in their profile. Without an associated group, that user can do nothing; not even browse Confluence (they lack the 'use' permission).

Thus, for an LDAP user to be able to use Confluence, a Confluence admin must create an account for them, and assign them to a group (typically 'confluence-user'). The password in this Confluence account will be ignored, as the LDAP password will override it.

Document generated by Confluence on Dec 20, 2007 18:51