Adding LDAP Integration To Confluence 2.1.x

This document applies only to Confluence 2.1. For Confluence 2.2 and later, please read Add LDAP Integration. Many improvements have been made to Confluence 2.2 to resolve the common issues people were facing with LDAP integration in 2.1. If you are still running Confluence 2.1 and would like to enable LDAP Integration, we strongly recommend that you upgrade to Confluence 2.2 before doing so.

Introduction

Confluence LDAP integration lets you delegate user and group management and authentication to your favourite LDAP server. LDAP v2 and v3 servers are supported via Java's JNDI-LDAP mapping (this includes OpenLDAP, Microsoft Active Directory, Novell eDirectory and many more).

Open LDAP Integration Issues

Currently, Confluence LDAP integration only works if your LDAP or Active Directory server supports static groups. This basically means that you have LDAP groups that store membership information like this: dn: CN=Sales and Marketing,CN=Users,DC=ad,DC=atlassian,DC=com objectClass: top; group; cn: Sales and Marketing; distinguishedName: CN=Sales and Marketing,CN=Users,DC=ad,DC=atlassian,DC=com; name: Sales and Marketing; ... member: CN=John Smith,CN=Users,DC=ad,DC=atlassian,DC=com member: CN=Sally Smith,CN=Users,DC=ad,DC=atlassian,DC=com ... The membership attribute in this case is member, but this can vary for your installation. The important thing is that your user DN's are stored against some membership attribute inside your LDAP groups. In the above, notice that the full DN's of John and Sally Smith are listed.

Installation instructions

Confluence now uses a component called Atlassian-User for LDAP integration as of version 2.1.

One of the main improvements of Atlassian-User-LDAP-Integration over the old style OSUser integration (configured via osuser.xml) is that administrators will no longer have to manually create a corresponding Confluence user account for each external LDAP user wanting access to the Confluence.

Atlassian-User-LDAP-Integration is configured directly in an XML file called atlassianUserContext.xml. This document will outline how to configure this XML file and migrate your existing users so that you can take advantage of this new integration.

This document applies to new and old installations, except if you have Confluence delegating user management to JIRA. In this case, please use this doc.

It is not compulsory to upgrade to Atlassian-User LDAP integration. However, to continue using OSUser LDAP integration in Confluence 2.1 or later, you must enable backwards compatibility.

Migration to new User Management Component

The new Atlassian-User-LDAP-Integration depends on a new user managment component. As such in order to take advantage of this new integration, you need to migrate your current users (even if there is only one user - in the case of new installs). This following steps will guide through this:

1. Make a backup of your:
   • database
   • Confluence home directory
   • confluence/WEB-INF/classes/atlassianUserContext.xml (only if you have made changes)

     This is critical to allow you the option to rollback should the migration not succeed.

2. Download hibernate_osuser_atlassianUserContext.xml and rename to atlassianUserContext.xml and copy to your confluence/WEB-INF/classes directory (you can overwrite the one that's there)
3. Now uncomment the osuserMigrationBean in {{confluence/WEB-INF/classes/upgradeSubsystemContext.xml}}

   <!-- To be used. optionally, to transfer ouser data to another repository. See osuser2atluser.jsp -->
       <bean id="osuserMigrationBean" class="org.springframework.transaction.interceptor.TransactionProxyFactoryBean">
           <property name="transactionManager">
               <ref bean="transactionManager"/>
           </property>
           <property name="target">
               <ref local="osuserMigrationBeanTarget"/>
           </property>
           <property name="transactionAttributes">
               <props>
                   <prop key="*">PROPAGATION_REQUIRED</prop>
               </props>
           </property>
           <property name="proxyInterfaces">
               <value>com.atlassian.user.util.migration.EntityMigrator</value>
           </property>
       </bean>
   
       <bean id="osuserMigrationBeanTarget" class="com.atlassian.user.util.migration.OSUEntityMigrator">
           <constructor-arg index="0">
               <ref bean="hibernateUserManager" />
           </constructor-arg>
           <constructor-arg index="1">
               <ref bean="hibernateGroupManager" />
           </constructor-arg>
           <constructor-arg index="2">
               <ref bean="hibernatePropertySetFactory" />
           </constructor-arg>
           <constructor-arg index="3">
               <ref bean="profileProvider" />
           </constructor-arg>
           <constructor-arg index="4">
               <ref bean="accessProvider" />
           </constructor-arg>
       </bean>

   
   Notice how the <!-- before the <bean id="osuserMigrationBean"... and the --> after the </bean> have been removed.
4. Restart Confluence and login as an Administrator and point a browser to http://host.com/contextpath/admin/osuser2atluser.jsp (where http://host.com/contextpath is your baseurl. If you don't know what it is, please see Administration > General Configuration > Base Url)
5. Click the link Begin migration
6. You will know the migration has been successful if you see this reported:
   

   Migrating users ... Users migrated successfully!
   Migrating propertyset data ... Propertyset data migrated successfully!
   Migrating groups ... Groups migrated successfully!

   If you encounter errors, please create a support ticket at http://support.atlassian.com and attach your application server logs.

7. Stop Confluence and comment back in the osuMigrationBean in confluence/WEB-INF/classes/upgradeSubsystemContext.xml. That is:
   

   <!-- To be used. optionally, to transfer ouser data to another repository. See osuser2atluser.jsp -->
       <!--<bean id="osuserMigrationBean" class="org.springframework.transaction.interceptor.TransactionProxyFactoryBean">
           <property name="transactionManager">
               <ref bean="transactionManager"/>
           </property>
           <property name="target">
               <ref local="osuserMigrationBeanTarget"/>
           </property>
           <property name="transactionAttributes">
               <props>
                   <prop key="*">PROPAGATION_REQUIRED</prop>
               </props>
           </property>
           <property name="proxyInterfaces">
               <value>com.atlassian.user.util.migration.EntityMigrator</value>
           </property>
       </bean>
   
       <bean id="osuserMigrationBeanTarget" class="com.atlassian.user.util.migration.OSUEntityMigrator">
           <constructor-arg index="0">
               <ref bean="hibernateUserManager" />
           </constructor-arg>
           <constructor-arg index="1">
               <ref bean="hibernateGroupManager" />
           </constructor-arg>
           <constructor-arg index="2">
               <ref bean="hibernatePropertySetFactory" />
           </constructor-arg>
           <constructor-arg index="3">
               <ref bean="profileProvider" />
           </constructor-arg>
           <constructor-arg index="4">
               <ref bean="accessProvider" />
           </constructor-arg>
       </bean>-->

8. Start up Confluence and you should be able to login using the admin account you first set up when running through the Confluence Setup Wizard.

Download and install sample atlassianUserContext.xml

Download ldap_hibernate_cache_atlassianUserContext.xml and rename to atlassianUserContext.xml and copy it to your confluence/WEB-INF/classes directory.

This file is different from the one downloaded for the migration step above. It contains LDAP settings we've configured for you in advance to make things easier

Editing atlassianUserContext.xml

Now open the atlassianUserContext.xml file in an editor and search for ldapRepository.

...

<!-- LDAP Configuration -->
<bean id="ldapRepository" class="com.atlassian.user.impl.ldap.repository.DefaultLDAPRepository" singleton="true" >
...

Configuring the connection between your LDAP system and Confluence

An example connection, in atlassianUserContext.xml, between Confluence and an LDAP system.

<property name="connectionProperties">
            <props>
                <prop key="host">acme.server.com</prop>
                <prop key="port">389</prop>
                <prop key="securityPrincipal">cn=admin,dc=atlassian,dc=private</prop>
                <prop key="securityCredential">secret</prop>
                <prop key="securityProtocol">plain</prop>
                <prop key="securityAuthentication">simple</prop>
                  <prop key="baseContext">dc=atlassian,dc=private</prop>
                <prop key="initialContextFactory">com.sun.jndi.ldap.LdapCtxFactory</prop>
                <prop key="batchSize">100</prop>
            </props>
        </property>

If you are unsure of what to specify or how to determine these values and:

a) you are using Active Directory please see this document.
b) otherwise, please see this document.

Mapping your LDAP Data Information Tree to Confluence

An example configuration of mappings, in atlassianUserContext.xml, between Confluence and an LDAP system.

<property name="schemaMappingsProperties">
            <props>
                <prop key="baseUserNamespace">ou=people,dc=atlassian,dc=private</prop>
                <prop key="baseGroupNamespace">ou=groups,dc=atlassian,dc=private</prop>
                <prop key="usernameAttribute">cn</prop>
                <prop key="userSearchFilter">(objectClass=inetorgperson)</prop>
                <prop key="firstnameAttribute">givenname</prop>
                <prop key="surnameAttribute">sn</prop>
                <prop key="emailAttribute">mail</prop>
                <prop key="groupnameAttribute">cn</prop>
                <prop key="groupSearchFilter">(objectClass=groupOfNames)</prop>
                <prop key="membershipAttribute">member</prop>
                <prop key="userSearchAllDepths">true</prop>
                <prop key="groupSearchAllDepths">true</prop>
            </props>
        </property>

For further details on this attributes and you are using:

a) Active Directory, please see this document.
b) otherwise please see this document.

Configuring the LDAP Connection Pool

Adjust them as required but we advise you to leave the timeout property to zero.

<constructor-arg>
           <props>
                <prop key="com.sun.jndi.ldap.connect.pool.maxsize">0</prop>
                <prop key="com.sun.jndi.ldap.connect.pool.initsize">10</prop>
                <prop key="com.sun.jndi.ldap.connect.pool.prefsize">10</prop>
               <!-- ldap connection pool debugging setting -->
<!--                <prop key="com.sun.jndi.ldap.connect.pool.debug">fine</prop>-->
                <prop key="com.sun.jndi.ldap.connect.pool.protocol">plain ssl</prop>
                <prop key="com.sun.jndi.ldap.connect.pool.authentication">none simple DIGEST-MD5</prop>
                <!-- TTL for each conn. in milliseconds. An idle connection reaching this limit will be destroyed.-->
                <prop key="com.sun.jndi.ldap.connect.pool.timeout">0</prop>
            </props>
       </constructor-arg>

It is important that the connection pool timeout value be set to 0, as this will force Atlassian User (via the JNDI layer) to clean up lingering connections that have lived past one request. More information about LDAP pools here

Granting users access to Confluence

We're almost finished. Right now, current registered users that are not in LDAP should be able to login and use Confluence.

However, LDAP users (that also have accounts inside Confluence) must have Confluence 'USE' permission granted to the LDAP groups they belong to before they can access Confluence.

To enable a user in your LDAP system to access Confluence, you need to do one of the following:

• grant the Confluence 'USE" permission to the LDAP group the user currently belongs to. This is done in the Administration > Global Permissions page.
• Alternatively, create a new LDAP group (you must not name it 'confluence-users' or 'confluence-administrators') and repeat the above for thi s group. In future, you only need to grant an LDAP user account membership to this group for them to have access to Confluence.

Having problems with your LDAP configuration?

Please follow these guidelines for creating a new support issue:

Requesting External User Management Support