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.

If you answered no to the above 2 points, then this is the correct guide for you.

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 with System Administrator permissions, whose username does not exist in the LDAP server (see Step 4).

Step 4 - Check the System Administrator account

This step assumes that you have at least one Confluence user account which has System Administrator permissions for 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 System Administrator permissions 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 - Configure your LDAP repository

1. Follow Customising atlassian-user.xml
2. Start up Confluence and check that you can log in using the System Administrator account you first set up when running through the Confluence Setup Wizard. If not, re-examine your steps and repeat where necessary.
3. If you can't successfully log in 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.

Step 6 - 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 with Can Use permissions enabled before they can have access to Confluence.
7. Set up your Confluence page and space permissions for these LDAP groups and users.

Tip: To set up all LDAP users as members of particular Confluence internal groups, you can try the LDAP Dynamic Groups Plugin.

Installation complete!

Related Pages

• Confluence LDAP Documentation Index

トラブルシューティング

Check your Confluence version

This documentation applies to Confluence 2.7. 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.