This documentation relates to the latest version of Confluence.
If you are using an earlier version, please go to the documentation home page and select the relevant version.

Add LDAP Integration

All Versions
Click for all versions
Confluence 2.9 Documentation

Index

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. Crowd supports features that Confluence-only LDAP integration cannot support, such as multiple user directories.

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. Go to the Confluence 'Administration Console'. To do this:

    • Open the 'Browse' menu and select 'Confluence Admin'. The 'Administration Console' view will open.
  2. Select 'Global Permissions' in the left panel.
  3. Click to Edit Permissions for Groups.
  4. In the textbox to 'Grant Browse Permission', enter the name of an LDAP group that should have Confluence access. Click 'Add'.
  5. Tick the Can Use box for the LDAP group. If the group is not found, it was not present in your LDAP server.
  6. For other LDAP groups that need access to Confluence, add them using the same method.
  7. 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.
  8. 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

Troubleshooting

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.

  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.
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.

Labels:

ldap ldap Delete
integration integration Delete
confluence confluence Delete
activedirectory activedirectory Delete
external external Delete
user user Delete
management management Delete
group group Delete
filter-common-tasks filter-common-tasks Delete
Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.
  1. Jun 25, 2006

    jd lima says:

    I too am interested in a authenticationonly configuration for Confluence 2.23. I...

    I too am interested in a authentication-only configuration for Confluence 2.23+. I had zero problems with LDAP authentication for JIRA 3.62. How should I diverge from this procedure to get LDAP authentication only for Confluence?

    1. Aug 03, 2006

      Matt Ryall says:

      Authenticationonly LDAP integration is still available via OSUser Adding LDAP In...

      Authentication-only LDAP integration is still available via OSUser in Confluence 2.2, but I don't really see why you would want that. In the old world of LDAP support in Confluence 2.1 and earlier, you only have one type of user and one type of group:

      • User must exist in Confluence, password authenticated against LDAP.
      • Group must exist in Confluence, and can only contain users that exist in Confluence.

      The new LDAP configuration allows so much more:

      • User can be a strictly Confluence user, password stored in Confluence.
      • User can be an LDAP user, where both user details and password authentication are from LDAP.
      • Group can be a strictly Confluence group, and contain any LDAP or Confluence users.
      • Group can be an LDAP group, and contain LDAP users as configured in your LDAP server.

      Confluence access can be granted to any of the above categories, without the extra step of creating a new user or group in Confluence. Once a user or group has Confluence access, it can be used in space permission and page restrictions, without worrying whether it is in LDAP or Confluence.

      In the future, we're planning to support retrieval of arbitrary LDAP properties for users and displaying these on the profile page. Some LDAP servers support storage of user pictures, so this might also mean automatic profile icons. None of this will be possible if you stick with the old LDAP support.

      There also seems to be a bit of a misunderstanding about the migration process. The migration is simply an internal database table migration, no data is copied to or from the LDAP server. At some point in the future we'll probably be migrating everyone to use the new database tables via an automatic upgrade task.

      1. Mar 14

        Anonymous says:

        I am using Confluence 2.7.1. Never use osuser before and edited my atlassianuser...

        I am using Confluence 2.7.1. Never use osuser before and edited my atlassian-user to connect to LDAP.
        However, once I did that, for users with usernames exist in LDAP, in 'view user', all groups disappeared. I think atlassian-user created a gap between LDAP user and local Confluence groups. How can I solve this problem?
        I would like Atlassian-user to be compatible with OSUser to provide password auth. only to LDAP.
        It might not make sense to Atlassian (why would any user want less functionality?), but that's what our org. need.

        Plus keeping user profiles local in Confluence:

        • users will still able to login in case LDAP goes down and won't disrupt business.
        • minimize potential problems if user entries were removed from LDAP.
        1. Mar 23

          Choy Li Tham says:

          Hi, However, once I did that, for users with usernames exist in LDAP, in 'view...

          Hi,

          However, once I did that, for users with usernames exist in LDAP, in 'view user', all groups disappeared

          I would suggest you to create a support ticket at the following Issue tracker so that we could further investigate this problem from there:

          I would like Atlassian-user to be compatible with OSUser to provide password auth. only to LDAP.

          Unfortunately, Confluence does not provide this feature currently. However, we are aware of such needs and there is an improvement request being tracked at the following link:

          The improvement request above suggest Confluence to include Atlassian-user to support password authentication only to LDAP. If you are keen on this improvement, feel free to cast a vote to increase its popularity and add yourself as a watcher for future updates. Also, you can add a comment in the improvement request to truly reflect the importance of this improvement.

          Regards,
          Choy Li

  2. Jul 31, 2006

    George Rothwell says:

    I am currently evaluating 2.2.6a.&nbsp; I was able to get Confluence authenticat...

    I am currently evaluating 2.2.6a.  I was able to get Confluence authenticating off a Windows 2003 Active Directory at the group level within a couple hours.  Based on what I have seen with the LDAP integration, I trust it enough to take into production. 

    I am new to Confluence, so some of that time was reading through the users guide and administration guides. 

    This is a bit more difficult than other commerical software (such as those from Microsoft), but much better than open source applications.

    I am not sure if this guide mentions it, but the log file can help you with this process.  Check <install folder>\logs\atlassian-confluence.log

    You will see messages like this if Confluence can't connect to the LDAP server:

    ERROR [bucket.user.DefaultUserAccessor] hasMembership javax.naming.AuthenticationException: [LDAP: error code 49 - 80090308: LdapErr: DSID-0C090334, comment: AcceptSecurityContext error, data 525, vece

    A key for me to get this working was this setting.  If Confluence can't login to Active Directory, you will not get anywhere.

       <securityPrincipal>cn=<username>,cn=users,dc=<domain>,dc=<domainExtension></securityPrincipal>

    Example with username = Administrator, active directory domain = test.local.

       <securityPrincipal>cn=Administrator,cn=users,dc=test,dc=local</securityPrincipal>

  3. Aug 03, 2006

    Mark says:

    Not seeing atlassianconfluence.log anywhere on hosting server.&nbsp; Wow, this i...

    Not seeing atlassian-confluence.log anywhere on hosting server.  Wow, this is very difficult, myself and another experienced admin have spent almost an entire day on ssl and ldap integration, all wasted time.  I want to use this product, but feel as if I am doing alot of work for a product we will be paying quite a bit of $$ for.  Almost feels like pure open source.  Atleast just the ssl and ldap parts.  Other parts are smooth.

    1. Aug 03, 2006

      Matt Ryall says:

      The location of your Confluence log file will depend on your application server....

      The location of your Confluence log file will depend on your application server. The location he mentions is configured for Confluence Standalone only; the EAR/WAR edition logs to the application server's stdout.

      If you're still having trouble with configuring LDAP, please raise a support ticket on http://support.atlassian.com. We'll be able to walk you through the installation process and diagnose the problems you've encountered.

  4. Aug 03, 2006

    Mark says:

    Ok, I finally got it working.&nbsp; It was my fault, I missed a detail on the us...

    Ok, I finally got it working.  It was my fault, I missed a detail on the user and group repository.  I left out a dc=.  For example I had ou=people,dc=domaincontrollername,dc=edu when it should have been ou=people,dc=domaincontrollername,dc=parentlevel,dc=edu.

     Just be sure to go over the config with a FINE TOOTH COMB before you give up!!!!!

    Sorry for blaming confluence, it was my problem. 

  5. Aug 03, 2006

    Daniel Veselka says:

    In my case the problem with configuration was in usernameAttribute I had to repl...

    In my case the problem with configuration was in usernameAttribute - I had to replace cn with uid. <usernameAttribute>uid</usernameAttribute>.

    In original file it maps userName to  cn which was in my case FirstName+LastName, not simple uid.

  6. Aug 04, 2006

    Mark says:

    This information may help if you are new to looking at code.&nbsp; Just know tha...

    This information may help if you are new to looking at code.  Just know that these marks in the file <!-  -> are commenting out what lies between.  For example when this file full of code is run:

    <!--
    execute, blah blah blah
    -->
    execute blah

    Only execute blah is actually run.  Look for this and make sure your entire LDAP configuration is not commented out.
    FYI

  7. Aug 10, 2006

    Mark says:

    Just wanted to offer this information, it may help someone.&nbsp; I did LDAP int...

    Just wanted to offer this information, it may help someone.  I did LDAP integration and the groups the user belongs to do not reside as a "user attribute" this membership information only resided within the security group attributes, ie each group had a bunch of "uniquemember" fields listing the memebers.  Anyway in the instructions this line below sort of made me think to look at the user attributes for this field

    membershipAttribute atlassianGroupMemberOf This attribute should identify which groups the user belongs to.

    Just any FYI that this attribute could also reside within the group attribute.  Or Active Directory environment is the opposite, the user object does list the groups that the user is a member of.  Good luck. 

  8. Dec 11, 2006

    Joshua Thomas says:

    Is it possible to map other attributes of a user in LDAP into Confluence (for ex...

    Is it possible to map other attributes of a user in LDAP into Confluence (for example, homePhone, mobile, postalAddress, etc) for use in user profiles?

    1. Dec 11, 2006

      Mei Yan Chan says:

      Hi Joshua, Unfortunately Confluence does not support this feature. The only att...

      Hi Joshua,

      Unfortunately Confluence does not support this feature. The only attributes that you can map to Confluence is available at:

      http://confluence.atlassian.com/x/eUUC

      In addition, there is an open feature request being tracked at CONF-5286. Feel free to cast your vote to increase its popularity and add yourself as a watcher for future updates.

      Regards,
      Mei

  9. Dec 20, 2006

    Steven Jantzen says:

    Ok, I started with Confluence 2.2.6, and was having no luck getting it to sync w...

    Ok, I started with Confluence 2.2.6, and was having no luck getting it to sync with our AD setup (Windows 2003). I upgraded to 2.2.9, and still had no luck. However, I was finally able to get it integrated. I found that with Active Directory in atlassian-user.xml you need to set your host as the IP address or your top level AD domain controller. The other thing is that the securityPrincipal attribute needs to be set to <user>@<domain>.<domain extension>, or test@thisisnotarealdomain.com. This is in contrast to CN=<fullname>,OU=<orginizationunit>,DC=<domain>,DC=<domainextension>

     The other thing, and this could be specific to just our setup, but we have groups per branch office, and not in the Users OU. To get all groups (and users for that matter) we had to set the baseUserNamespace attribute to DC=<domain>,DC=<domain extension> and the baseGroupNamespace attribute to the same.

    Finally, make sure that if you provide a dedicated user for your LDAP integration involving an AD setup, you set the password to never expire.

    Once I figured it out, it's easy, it's just getting that first step.

  10. Jun 14, 2007

    Joe Kraska says:

    For others who are doing LDAP integration VIA Active directory, this particular ...

    For others who are doing LDAP integration VIA Active directory, this particular entry works in my environment (where "XXXXXX" is replaced by a working password):

    <ldap key="ldapRepository" name="IRAD LDAP" cache="true">
    			<host>10.35.24.59</host>
    			<port>389</port>
    			<securityPrincipal>cn=Administrator,cn=Users,dc=irad,dc=net</securityPrincipal>
    			<securityCredential>XXXXXX</securityCredential>
    			<securityProtocol>plain</securityProtocol>
    			<securityAuthentication>simple</securityAuthentication>
    
    			<baseContext>ou=IRAD OU,dc=irad,dc=net</baseContext>
    			<baseUserNamespace>ou=IRAD OU,dc=irad,dc=net</baseUserNamespace>
    			<baseGroupNamespace>ou=IRAD OU,dc=irad,dc=net</baseGroupNamespace>
    
    			<usernameAttribute>sAMAccountName</usernameAttribute>
    			<userSearchFilter>(objectClass=user)</userSearchFilter>
    			<firstnameAttribute>givenname</firstnameAttribute>
    			<surnameAttribute>sn</surnameAttribute>
    			<emailAttribute>mail</emailAttribute>
    			<groupnameAttribute>cn</groupnameAttribute>
    			<groupSearchFilter>(objectClass=group)</groupSearchFilter>
    			<membershipAttribute>member</membershipAttribute>
    			<userSearchAllDepths>true</userSearchAllDepths>
    			<groupSearchAllDepths>true</groupSearchAllDepths>
    		</ldap>
    
    		<hibernate name="Hibernate Repository" key="hibernateRepository"  description="Hibernate Repository" />
  11. Sep 17, 2007

    Arne Lovius says:

    I had the "already exists in OSUser Repository" error, and eventually found this

    I had the "already exists in OSUser Repository" error, and eventually found this which was quite an interesting read

    1. Sep 22, 2007

      Trevor Marshall says:

      Same problem. Step 5 fails with same error and when I continue I can't get back ...

      Same problem. Step 5 fails with same error and when I continue I can't get back in with my admin user after enabling LDAP. confluence-2.5.7-std.

      1. Sep 23, 2007

        Mei Yan Chan says:

        Hi Trevor, Could you please raise this issue at

        Hi Trevor,

        Could you please raise this issue at http://support.atlassian.com ?

        Thank you.

        Regards,
        Mei

        1. Sep 27, 2007

          Tomas Edwardsson says:

          Is support finding anything out? I'm evaluating this product and getting Active ...

          Is support finding anything out? I'm evaluating this product and getting Active Directory integration is vital to the evaluation.

          Migrating users ... ERROR
          User [wikiadmin] already exists in OSUser Repository

          My confluence/WEB-INF/classes/atlassian-user.xml is correct in regard to "hibernateRepository is first and the osuserRepository is second"

          1. Sep 27, 2007

            Tony Cheah Tong Nyee says:

            Hi Tomas, May I know what is the version of Confluence you are running to integ...

            Hi Tomas,

            May I know what is the version of Confluence you are running to integrate with the AD server? There is a bug reported that affects Confluence version 2.5.6 and later being tracked in the following link which is pretty similar to the problem that you are encountering:

            Feel free to add yourself as a watcher so that you will be notified if there are any updates to the bug report.

            Cheers,
            Tony

        2. Oct 17, 2007

          Trevor Marshall says:

          atlassianuser jar from

          atlassian-user jar from http://jira.atlassian.com/browse/CONF-9195 fixed the import for us. Now it seems users are slowly showing up in the People Directory as they login for the first time, which is not expected behaviour, but not bad.

  12. Oct 17, 2007

    Trevor Marshall says:

    Once we import all our users from LDAP, how do we hide those we don't want using...

    Once we import all our users from LDAP, how do we hide those we don't want using the wiki? We use Open Directory and it contains some administrative accounts that I don't want to look at in the wiki's People Directory.

    1. Oct 19, 2007

      Tony Cheah Tong Nyee says:

      Hi Trevor, Did you mean that you would like to display only a certain number of...

      Hi Trevor,

      Did you mean that you would like to display only a certain number of users in the Confluence's "People Directory" page?
      If this is the case, it is not supported in Confluence. A workaround that I can think of is, to disable the "People Directory" feature. For more details on how this can be done, please see:

      Additionally, there is also a feature request regarding restricting user profiles from being access by other users which you may be interested to look at:

      Feel free to cast your votes to increase its popularity and add yourself as a watcher for future updates.

      Cheers,
      Tony

  13. Oct 25, 2007

    Anonymous says:

    FYI, this document refers to the LDAP Dynamic Groups Plugin, which I don't think...

    FYI, this document refers to the LDAP Dynamic Groups Plugin, which I don't think will work against Confluence 2.6.  I've set it up myself and it seems to be trying to make calls to an older API, giving a NoClassDefFound exception.  I would be a good idea to note this for folks who are trying to set up 2.6.  It's a very appealing plugin and I'd like to use it if I can.

  14. Feb 10, 2008

    Antonio Almazán says:

    Hi\! We need some help\! We are trying to integrate Confluence 2.7.1 with our Ac...

    Hi!

    We need some help!

    We are trying to integrate Confluence 2.7.1 with our Active Directory (under Windows 2003) but it is impossible for us. Our goal would be that only users defined in an Active Directory group called "Confluence" can log-in in Confluence server. Here are the steps we have followed "to do" the integration:

    1.- We have defined a new group called "Confluence" in Active Directory under the "Users" section.

    2.- We have "configurated" users in order to they can belong to this new group: we have defined that users "Daniel" and "Helen" belong to "Confluence" group. In other way, user "Peter" does not belong to this group. This is because we would like to use it in order to test (in the future) that only users which belong to "Confluence" group will able to log-in in Confluence server. All users are under the "Users" section.

    3.- We have installed MySQL 5.0 in our Windows 2003 server

    4.- We have installed and integrated Confluence 2.7.1 with MySQL in our Windows 2003 server (we have an "all-in-one" server ).

    5.- We have setup Confluence without LDAP/AD integration: this means that in Confluence, we have defined only one user (the super-user) which username is "admconfluence" and we have defined a test-space called "Test". Of course, user "admconfluence" does not exist in our Active Directory server and also, we don't have defined in Active Directory any gro