This page last changed on Sep 27, 2007 by smaddox.
 | Try Atlassian Crowd for powerful LDAP integration
Atlassian's Crowd is a web-based single sign-on (SSO) tool that simplifies application provisioning and identity management. |
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:
- Are you using Atlassian-User LDAP on Confluence 2.1.x? If so, follow the 2.1.x LDAP Upgrade Instructions instead.
- 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.
- 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.
- 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.
- You must not have LDAP groups called 'confluence-users' or 'confluence-administrators'.
- 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
- 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.
- Create backups in order to rollback to the old version if the migration is unsuccessful. Make a backup of your:
- database
- Confluence home directory
- confluence/WEB-INF/classes/atlassian-user.xml (only if you have made changes)
Step 6 - Migrate Confluence users and configure your LDAP repository
There are two ways to do this:
- 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
- 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)
- 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.
- 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.
- Stop Confluence.
- 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.
- 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.
- 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.
- Follow Customising atlassian-user.xml
- Go to step 7.
METHOD B: Configure LDAP, then migrate Confluence users
- 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.
- Follow Customising atlassian-user.xml
- 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.
- 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.
- Stop Confluence.
- Edit atlassian-user.xml file and comment out the <osuser> repository.
- 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:
- From Confluence, go to Administration > Global Permissions
- Click to Edit Permissions for Groups
- In the textbox to Grant Browse Permission, enter the name of an LDAP group that should have Confluence access. Click Add.
- Tick the Can Use box for the LDAP group. If the group is not found, it was not present in your LDAP server.
- For other LDAP groups that need access to Confluence, add them using the same method.
- 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.
- 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
Troubleshooting Resources
Failing that, lodge a support request. Be sure to attach your atlassian-user.xml, Paddle logs and a zip of your Confluence logs.
|