Migrate to LDAP User Management From OsUser

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:

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.

   The comment "Once the LDAP repository is configured, this migration will ignore users who have the same username as an LDAP user. This will ensure users are not duplicated in Confluence when you have both LDAP and local Confluence users enabled" is meant to describe avoiding CONF-8098. Your users, if they match in LDAP, will be migrated to the LDAP user repository on the database. See the Testing section below to confirm your results.

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.

Testing

1. Check that groups are associated by visiting a user from the User Browser and logging in.
2. Check your external_entites and external_members tables on your database. If done correctly, these tables should contain the users who were migrated from os_users and matched in LDAP. You should be able to see their group associations in the external_members table.

   SELECT * FROM external_entities;
   SELECT * FROM external_members;
   

3. Check your users table. These are the users who were not matched in LDAP. It might include the 'admin' user that you made when you originally created the wiki, and perhaps others who've signed up who are not in LDAP. If you need to migrate users from this table into LDAP, check the utility attached to CONF-10654.

Related Pages

• Confluence LDAP Documentation Index
• Add LDAP Integration For User Authentication Only

More information

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

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.