This page last changed on Oct 03, 2008 by jlargman.

Is this guide for me?

Use Add LDAP Integration instead if:

  • You are setting up Confluence for the first time.
  • You do not need to retain group membership for existing users.
  • You are using hibernate user management. To find out, check <confluence-home>/confluence/WEB-INF/classes/atlassian-user.xml. If there is a hibernate tag but not an os_user tag, you're using hibernate user management.

Background Information

Confluence has three types of user management: os_user (deprecated in confluence 2.7 and later), hibernate (also known as atlassian-user), and LDAP integration.

These correspond to the three tags in atlassian-user.xml:

  • <ldap key=...>
  • <hibernate name=...>
  • <osuser key=...>

In Confluence 2.7, during the upgrade task, users are migrated from os_user to hibernate when Confluence is first started. This migration can also be run manually.

When to Run the User Migration

Under most conditions, you'll want to migrate from OsUser to Hibernate User Management. However, there is one condition under which you'll want to hold off on doing the automatic user management migration when upgrading.

As described in this jira issue, local groups are not retained when migrating from hibernate user management to LDAP. However, if you are using OsUser for user management and want to switch to LDAP, you can retain group membership by following this procedure:

If you want to upgrade to 2.7 or later and do LDAP integration, we suggest you do your LDAP integration first, then run the upgrade. If you want to run the upgrade first, you can prevent the user migration from occurring by copying your <confluence-home>/confluence/WEB-INF/classes/atlassian-user.xml file and your osuser.xml files into place before starting Confluence. To check whether the migration has run, look in the 'users' table on the database.

  1. Create a test environment. This will create an exact replica of your current version. Use your current version. This will ensure that the automatic user migration does not occur when you restart.
  2. 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.

  3. Follow Customising atlassian-user.xml
  4. 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.

  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. Stop Confluence.
  7. Edit atlassian-user.xml file and comment out the <osuser> repository.
    Change this line:
    <osuser key="osuserRepository" name="OSUser Repository"/>
    

    to this:

    <!-- <osuser key="osuserRepository" name="OSUser Repository"/> -->
    
  8. 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.

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

More information
Support

Failing all else, lodge a support request. Be sure to attach your atlassian-user.xml, Paddle logs and a zip of your Confluence logs.


Document generated by Confluence on Dec 03, 2008 15:04