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.

The JIRA version of this page may be more up to date. There is an updated osuser jar linked to from that page, which contains more debugging. If you are having problems getting LDAP auth working, please use that jar.

Posted by jeff at Jun 09, 2004 22:34

I just tried setting this up using IBM's internal LDAP server and it worked great. Very kewl! Here's the exact bits I used:

<provider class="com.opensymphony.user.provider.ldap.LDAPCredentialsProvider">
<property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property>
<property name="java.naming.provider.url">ldap://bluepages.ibm.com:389</property>
<property name="searchBase">ou=bluepages,o=ibm.com</property>
<property name="uidSearchName">mail</property>
</provider>

Posted by at Jul 02, 2004 20:59

When using Active Directory it is common that the user's full name (or something similar) rather than their normal username is stored in "cn" attribute. It is also common that the username is stored in the "sAMAccountName" attribute therefore to validate using their normal username use a property tag like "<property name="uidSearchName">sAMAccountName</property>".

Posted by sjrich at Jul 20, 2004 22:22

For Active Directory, we also found that the security principal has to be as below for non-anonymous lookups: (i.e. leave out the 'cn=' )

<property name="java.naming.security.principal">Manager,dc=atlassian,dc=com</property>
<property name="java.naming.security.credentials">secret</property>
<property name="exclusive-access">true</property>

Posted by at Aug 19, 2004 17:57

I've downloaded Confluence and have it set up and running using the local database for user authentication. Now, I'm trying to get the LDAP authentication to work with a Microsoft Active Directory, but I'm running into a problem. After I shut down Confluence, make the changes to osuser.xml, and then restart Confluence, not only does it not authenticate to the LDAP server (I created a local user with a name matching one that exists in the Active Directory), but the local users defined in Confluence's local database also cannot log in. If I copy the original osuser.xml file back into place, local users can once again login without a problem.

My Active Directory requires users to log in to browse the LDAP directory structure and I've verified that the credentials that I'm supplying are valid using an LDAP browsing utility. I'm trying to authenticate to the sAMAccountName property in the AD. I've tried entering the java.naming.security.principal line both with and without cn= before my username required to authenticate to the LDAP server.

As AD can communicate LDAP information on both ports 389 and 3268, I've tried both of them as well.

My modified osuser.xml file additions are as follows:

<provider class="com.opensymphony.user.provider.ldap.LDAPCredentialsProvider">
<property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property>
<property name="java.naming.provider.url">ldap://ldapserver.subdomain.mycompany.com:389</property>
<property name="searchBase">dc=users,dc=subdomain,dc=mycompany,dc=com</property>
<property name="uidSearchName">sAMAccountName</property>
<property name="java.naming.security.principal">cn=myldapuser,dc=users,dc=subdomain,dc=mycompany,dc=com</property>
<property name="java.naming.security.credentials">mypassword</property>
<property name="exclusive-access">true</property>
</provider>

These modifications was entered above the existing code as suggested.

Since local authentication suddenly stops working, it almost seems as if I'm damaging the osuser.xml file somehow, but can't see it; or I'm missing an additional configuration setting.

I apologize if this is something so ridiculously simple, but I've been spinning my wheels for a while now. Does anyone have any ideas?

Thanks

Posted by at Oct 19, 2004 16:23

Update to the above post:

I changed the searchBase to not include dc=users and it started authenticating AD users. However, it still will not authenticate local users that do not appear in the AD. I'm not sure if that is the expected behavior or not.

Thanks.

Posted by at Oct 19, 2004 17:38

Is it possible to set up more than 1 LDAP provider (see example below). Searching our entire (4000 users) LDAP tree takes minutes, not seconds.

<!-- ITS LDAP tree -->
<provider class="com.opensymphony.user.provider.ldap.LDAPCredentialsProvider">
<property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property>
<property name="java.naming.provider.url">ldap://xxx.xxx.xxx.xxx:389</property>
<property name="searchBase">ou=group1,ou=division,o=department</property>
<property name="uidSearchName">cn</property>
</provider>

<!-- DAQ LDAP tree -->
<provider class="com.opensymphony.user.provider.ldap.LDAPCredentialsProvider">
<property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property>
<property name="java.naming.provider.url">ldap://xxx.xxx.xxx.xxx:389</property>
<property name="searchBase">ou=group2,ou=division,o=department</property>
<property name="uidSearchName">cn</property>
</provider>

<!-- Entire DENR LDAP tree -->
<provider class="com.opensymphony.user.provider.ldap.LDAPCredentialsProvider">
<property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property>
<property name="java.naming.provider.url">ldap://xxx.xxx.xxx.xxx:389</property>
<property name="searchBase">ou=division,o=department</property>
<property name="uidSearchName">cn</property>
</provider>

Posted by allan.axon@ncmail.net at Oct 27, 2004 13:33

Is there another reasonable source of documentation for OSUser? I haven't figured out why Confluence and Jira are using such a poorly documented API for user management. Even the Open Symphony page seems to treat OSUser as a pigment challenged hair color step child.

I understand that adding LDAP for user credentials may provide an alternative/additional means for user authentication but it's not clear what that class is supposed to do and how it integrates with Confluence/Jira. At our site we use an LDAP directory, but not for authentication. Instead an out-of-band kerberos based implementation is used to provide authentication. Users are authenticated out-of-band and the user ID then becomes available via the REMOTE_USER http request variable. An apache module is used to intercept any requests to a page or portion of a web site so once the authentication takes place it would just need to pass the user id token to the profile and access providers. Any suggestions?

Posted by jaf30@cornell.edu at Feb 03, 2005 12:27

We had to add the dc=users in 2003 AD. For simplicity (although it took us a while to figure out), we created a simple user that had the cn and the sAMAccount the same.

As soon as we restarted the local users also stopped authenticating. Still don't have the issue for both AD/LDAP and local users resolved.

Posted by at Feb 09, 2005 23:14

Our installation of Jira already uses Active Directory for authentication. We recently acquired confluence. Confluence is setup to use Jira's database for user accounts, but it wants to use a user's jira password... how can I configure confluence so that it looks up users in jira's database and asks AD for authentication?

Posted by prak23@gmail.com at Mar 25, 2005 15:12

Is there a resolution to the point raised by Praveen as I am currently looking at exactly the same issue for my company.

Posted by at Apr 07, 2005 05:06

Did you ever get any info on this? I have been trying to get this right for while and can't figure it out.

Posted by at Apr 08, 2005 12:02

Perhaps I missed this, but what do I need to do to force LDAP authentication only?

The real concern for me is that the user can log in with either the LDAP password or the Confluence-set password. It feels that if I go with the method of creating the account with a long, random password that won't ever be used, it's still a hack.

Better solution?

Posted by at Apr 12, 2005 13:47

Does Confluence support SLDAP, on port 636? I have no problems going over 389, but 636 is not allowing me in. Has anyone had any experience with this?

Posted by muddp@nationwide.com at May 03, 2005 12:46

We are using ldap over SSL without issue to Sun One. Have you tried the osuser jar mentioned at the top of the comments (the jira one) it makes troubleshooting issues such as this MUCH easier and will give you real error messages. We ran into issues with it not accepting the SSL cert at first.

Posted by at Jun 17, 2005 13:56

Did you get an answer to this? I am looking at deploying it in a similar situation.

Posted by lkb2k at Aug 02, 2005 10:39

Will this only do password checking, or can it also be used to manage the group membership. The current implementation of group management and permissions is a bit clunky.

Posted by troymckinnon at Dec 29, 2005 17:13

This only does Authentication.

See DEV:Confluence LDAP Documentation Indexfor information on using the new Atlassian User component for full LDAP user/group management.

Tom

Posted by tom@atlassian.com at Dec 29, 2005 18:01

I have been successful in testing using LDAP for Confluence with user management in JIRA. If the user is in LDAP but the password lookup fails, it does not seem to try the Jira lookup. Is this correct behavior? Also, what does "exclusive-access"=true do?

Posted by bob.swift@lakeviewtech.com at Jan 05, 2006 22:09

Yes that is correct behaviour.

exclusive-access=true tells the provider it has exclusive access to the database (ie can take advantage of in memory caches)

Posted by tom@atlassian.com at Jan 09, 2006 23:39

If you're getting the following exception:

AuthenticationException: [LDAP: error code 49 - 80090308: LdapErr: DSID-0C090334, comment: AcceptSecurityContext error, data 525, vece ]

 

Try to changing to security principal to the following format:

<property name="java.naming.security.principal">Domain\User</property>

 

Posted by winston.w.lee@boeing.com at Jan 26, 2006 21:33

Geez. Is anyone else finding it as hard as I do to parse XML that is not indented?

I keep finding myself reaching for the edit tab to put the spaces before subordinate XML elements.

Did we reprioritize readability to the bottom of the heap and no one told me?

Let me know how to get edit access and I will happily remedy the situation.

Posted by scanny at May 05, 2006 04:39

For Active Directory this worked for us (see property principal):

<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://ldapserver:389</property>
        <property name="searchBase">dc=company,dc=de</property>
        <property name="uidSearchName">sAMAccountName</property>
       
        <property name="java.naming.security.principal">LDAPUSER</property>
        <property name="java.naming.security.credentials">password</property>
        <property name="exclusive-access">true</property>
</provider>

Posted by loetterle at Sep 07, 2006 08:05
Document generated by Confluence on Feb 07, 2007 23:55