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 back 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 thant 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 DN's must be stored against a membership attribute inside an LDAP groups. An example of a static groups 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 DN's 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 who's username does not exist in the LDAP server.

Step 4 - Administrator account check

This step assumes that you have at least one 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 this is the case and you do not have another local account that has administration rights, then you should perform one of the following:

• create another account to act as the administrator that doesn't exist on LDAP
• rename you local admin account to use another username that doesn't exist in LDAP
• 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 (next step).

Step 5 - Confluence user migration

The new Atlassian-User-LDAP-Integration depends on a new user managment component and requires you to migrate your current users even in the case of new installs. The following steps will guide you:

1. You will need to find out your Confluence base URL. To check this from Confluence, go to Administration > General Configuration > Base Url. Record this for later in the process.
   
   
2. You must 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)
     
     
3. 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).
   If you have already setup LDAP in your osuser.xml file and wish to migrate over to atlassian user LDAP, then you need to uncomment the ldap section, and fill in the correct details (as described in Customising atlassian-user.xml). This will prevent users in your osuser table that exist in LDAP from being migrated over. If you haven't already setup LDAP in osuser.xml please do NOT uncomment the ldap section.
   

   Are you using Confluence 2.3.x - 2.5.6 ?
   Users of +Confluence 2.3.x - 2.5.6 need to right click on osuser2atluser.jsp and download it to the \confluence\admin subdirectory of your Confluence install. Overwrite the existing osuser2atluser.jsp file.

   
   
4. Restart Confluence. Login as an Administrator, and go to this URL:

   <BASEURL>/admin/osuser2atluser.jsp
   

   Please ensure you replace <BASEURL> with the URL you currently use to access Confluence. For example, http://confluence.atlassian.com or http://foobar.com/confluence.
   
   
5. 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.
   
   
6. Confluence を停止します。
   
   
7. 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.
   
   
8. 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.

Step 6 - Configure LDAP connection in atlassian-user.xml

1. 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.
   
   
2. Follow Customising atlassian-user.xml

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

Troubleshooting Resources

• 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 that, lodge a support request. Be sure to attach your atlassian-user.xml, Paddle logs and a zip of your Confluence logs.