Add LDAP Integration

Confluence can delegate user authentication to LDAP and use LDAP group memberships to set the user's Confluence access permissions. This also allows Active Directory (AD) integration. This guide is for both users enabling LDAP, and those upgrading their LDAP scheme to support group management. It applies to LDAP over HTTP and SSL/HTTPS.

Once the LDAP is enabled and LDAP users are using Confluence, you cannot revert to local user management without those users being disabled. However, you can create new local users while using LDAP integration.

Who is this guide for?

To decide if this is the correct document for you, please answer these 2 questions:

1. Are you using Atlassian-User LDAP on Confluence 2.1.x? If so, follow the 2.1.x LDAP Upgrade Instructions instead.
   
   
2. Are you using a version of Confluence older than 2.1? If you are using 2.0.x, follow OSUser LDAP integration instead. If it is older than 2.0, you must upgrade Confluence.

Step 1 - Upgrade Confluence

Please check that you are running the latest version of Confluence. If not, we strongly recommend that you consider upgrading Confluence according to this guide. Confirm that you have upgraded successfully before trying to add LDAP to the new version.

Step 2 - Contact your LDAP/AD Administrator

Integration can only be setup by an administrator confident with running user queries against their LDAP directory. You should request assistance from your LDAP or Active Directory administrator for the following steps.

Step 3 - Check your LDAP server

Confirm this information about your LDAP server.

1. Check your server LDAP version. Supported versions are v2 and v3. Supported LDAP servers include OpenLDAP, Microsoft Active Directory, Novell eDirectory, and any server that uses Java JNDI-LDAP mapping.
   
   
2. Your LDAP or Active Directory server must support static groups. This means that the user DNs must be stored against a membership attribute inside an LDAP groups. An example of a static group is shown below:

   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 is not required. Note that the full DNs of John and Sally Smith are listed. If the values against member are not full DNs, but are just usernames, then you need to add the flag

   <useUnqualifiedUsernameForMembershipComparison>true
   </useUnqualifiedUsernameForMembershipComparison>
   

   to your LDAP configuration. Open Directory on OS X uses this configuration.
   
3. You must not have LDAP groups called 'confluence-users' or 'confluence-administrators'.
4. You must have at least one existing Confluence administrator whose username does not exist in the LDAP server (see Step 4).

Step 4 - Check the Administrator account

This step assumes that you have at least one Confluence user account which has permissions to administer your Confluence site. For this account, please check that there isn't an account on your LDAP system that has the exact same username.

If there is an LDAP account with the exact same username, and you do not have another local Confluence account that has administration rights, then you should perform one of the following:

• create another account, that doesn't exist on LDAP, to act as the administrator
  OR:
• rename your local Confluence administrator account to use another username that doesn't exist in LDAP
  OR:
• rename your LDAP account

This will ensure that you will have an account that has sufficient rights to administer your site after you migrate your users.

Step 5 - Prepare for Confluence user migration

1. Find out your Confluence base URL. To check this from Confluence, go to Administration > General Configuration > Base Url. Record this for use in Step 6.
   
   
2. Create backups in order to rollback to the old version if the migration is unsuccessful. Make a backup of your:
   • database
   • Confluence ホームディレクトリ
   • confluence/WEB-INF/classes/atlassian-user.xml (only if you have made changes)
     

Step 6 - Migrate Confluence users and configure your LDAP repository

This is a mandatory step for all users who are configuring LDAP for the first time AND who have not changed their atlassian-user.xml during installation, as per Step 5.

次の 2 つの方法があります。

• METHOD A: Migrate Confluence users first, then configure LDAP. (This method allows your users to continue using Confluence after migration, even before you have finished the LDAP configuration.)

• METHOD B: Configure LDAP users first, then migrate Confluence users. (This method ensures that the migration ignores users who have the same username as an LDAP user. This will prevent duplicate users in Confluence when you have both LDAP and local Confluence users enabled.)

The recommended method is:

• If you are running a Confluence version earlier than 2.6, follow METHOD A.

• If you are running Confluence version 2.6 or later, and none of your existing Confluence users have the same usernames as LDAP users, follow METHOD A.
• If you are running Confluence version 2.6 or later, and any of your existing Confluence users have the same usernames as LDAP users, follow METHOD B.

METHOD A: Migrate Confluence users first, then configure LDAP

1. Download hibernate_osuser_atlassian-user.xml and rename to atlassian-user.xml and copy to your confluence/WEB-INF/classes directory. (You can overwrite the one that's there)
   
2. Restart Confluence. Login as an Administrator, and go to this URL:

   <BASEURL>/admin/osuser2atluser.jsp
   

Replace <BASEURL> with the URL you currently use to access Confluence. For example, http://confluence.atlassian.com or http://foobar.com/confluence.

1. Click the link Begin migration. 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.
   
   
2. Confluence を停止します。
   
3. Start up Confluence and check that you can login using the admin account you first set up when running through the Confluence Setup Wizard. If not, re-examine your steps and repeat from there.
   
   
4. If you can't successfully login with this account, please check that the username of this account does not already exist in your LDAP server. If usernames are the same, Confluence recognises LDAP accounts over local Confluence accounts.
5. Download ldap_hibernate_cache_atlassian-user.xml, rename it to atlassian-user.xml then copy to your <INSTALL>/confluence/WEB-INF/classes directory. It should overwrite the previous atlassian-user.xml.
   
   
6. Follow Customising atlassian-user.xml
7. Please ensure that in your atlassian-user.xml file, the <osuser> repository has been commented out.
   Change this line:

   <osuser key="osuserRepository" name="OSUser Repository"/>
   

   to this:

   <!-- <osuser key="osuserRepository" name="OSUser Repository"/> -->
   

8. Go to step 7.

METHOD B: Configure LDAP, then migrate Confluence users

1. Download ldap_hibernate_osuser_atlassian-user.xml, rename it to atlassian-user.xml then copy to your <INSTALL>/confluence/WEB-INF/classes directory. It should overwrite the previous atlassian-user.xml.
   Your atlassian-user.xml file should have LDAP, hibernate and osuser repositories (in this order) enabled.
   
   
2. Follow Customising atlassian-user.xml
3. Restart Confluence. Login as an Administrator, and go to this URL:

   <BASEURL>/admin/osuser2atluser.jsp
   

Replace <BASEURL> with the URL you currently use to access Confluence. For example, http://confluence.atlassian.com or http://foobar.com/confluence.

1. Click the link Begin migration. 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.
   
2. Confluence を停止します。
   
3. Edit atlassian-user.xml file and comment out the <osuser> repository.
   Change this line:

   <osuser key="osuserRepository" name="OSUser Repository"/>
   

   to this:

   <!-- <osuser key="osuserRepository" name="OSUser Repository"/> -->
   

   
   
4. Start up Confluence and check that you can login using the admin account you first set up when running through the Confluence Setup Wizard. If not, re-examine your steps and repeat from there.
   

Step 7 - Grant access to LDAP users and groups

To grant Confluence login access to your LDAP groups and users:

1. From Confluence, go to Administration > Global Permissions
2. Click to Edit Permissions for Groups
3. In the textbox to Grant Browse Permission, enter the name of an LDAP group that should have Confluence access. Click Add.
4. Tick the Can Use box for the LDAP group. If the group is not found, it was not present in your LDAP server.
5. For other LDAP groups that need access to Confluence, add them using the same method.
6. If you are integrating LDAP with Confluence for authentication only, no LDAP groups will appear in Confluence. All the individual LDAP users will have to be manually added to an internal Confluence group having with Can Use permissions enabled before they can have access to Confluence.
7. Setup your Confluence page and space permissions for these LDAP groups and users.

To setup all LDAP users as members of particular Confluence internal groups, use the LDAP Dynamic Groups Plugin.

Installation complete!

Related Pages

• Confluence LDAP Documentation Index
• Add LDAP Integration For User Authentication Only

トラブルシューティング

Check your Confluence version

This documentation applies to Confluence 2.6. There are a couple key bugs that have been resolved in Confluence 2.6 or 2.6.1, but that pertain to 2.5.6 and 2.5.7.

1. http://jira.atlassian.com/browse/CONF-9434 relates to hibernate cache=true;
   The xml file supplied here has the hibernate cache set to "true".
2. http://jira.atlassian.com/browse/CONF-9195 relates to the migration step.
   Version 2.6.1 corrects this problem.

詳細情報

• LDAP FAQ
• If LDAP users or groups are not displayed in Confluence, download the Paddle diagnostic tool
• List of known, unresolved LDAP bugs
• Comments on this page.

サポート

Failing all else, lodge a support request. Be sure to attach your atlassian-user.xml, Paddle logs and a zip of your Confluence logs.