Add LDAP Integration

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?

If you are using local user management in a version prior to Confluence 2.7, or os_user with authentication-only or jira user management, follow the guide to Migrate to LDAP User Management From OsUser. Otherwise, this is the correct guide for you.

Integrate only after completing Setup

If you are doing an LDAP integration as part of a new install, do not integrate until after you complete the initial setup. You can add LDAP integration after you create the admin user for your instance.

Unknown macro: {htmlComment}

This warning is here to avoid users getting a "Cannot create group 'confluence-administrators" error. -Twong 9/16/08

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 tag in atlassian-user.xml. 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 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

Follow Customising atlassian-user.xml
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.
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.
If you were using OS user previously, run the user migration. After the migration has run, remove the os user tag from atlassian-user.xml and restart Confluence.

Step 6 - Grant access to LDAP users and groups

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

Go to the Confluence 'Administration Console'. To do this:
- Open the 'Browse' menu and select 'Confluence Admin'. The 'Administration Console' view will open.
Select 'Global Permissions' in the left panel.
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 with Can Use permissions enabled before they can have access to Confluence.
Set up your Confluence page and space permissions for these LDAP groups and users.

Installation complete!

Related Pages

Confluence LDAP Documentation Index

Troubleshooting

Local user management not retained

If you run into this problem, you may be experiencing this bug.

Check your Confluence version

This documentation applies to the latest version of Confluence. There are a couple of 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.

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

More information

Browse the LDAP FAQ.
If LDAP users or groups are not displayed in Confluence, try the External User Test tool.
Check the list of known, unresolved LDAP bugs
See the comments on this page, from other users who may have left some useful information.
The 'External User Management' setting in the Confluence Administration Console should be set to OFF. This setting is for using JIRA or Crowd for External User Management.

Support

Failing all else, lodge a support request. Be sure to attach your atlassian-user.xml, a copy of the output from the External User Test tool, and a zip of your Confluence logs.

Page tree