Migrating Users between User Directories

Organizations will often migrate to or from LDAP engines, such as Active Directory or OpenLDAP, as they grow or acquire new companies, and need to migrate users into the same LDAP engine. As changes occur outside of JIRA, they will also need to be reflected within the JIRA User Directories:

  • JIRA can have multiple User Directories (e.g. JIRA Internal, Delegated LDAP, LDAP Connector).
  • Each directory will have unique users, groups and group memberships. This means there can be multiple users of the same username with different group memberships.
  • Project Roles are global across all User Directories.
  • If you have the same user in multiple directories, the effect of directory order will apply. This means that if you add a new user directory and then change the order, so it is before your existing directory, your users will be selected from that directory first.
  • When disabling a user in LDAP, it will be disabled in JIRA.
  • When deleting a user in LDAP, it will be deleted in JIRA if it is not needed, or disabled if it is (e.g. the user has comments).
  • You can set up a User Directory with different permissions settings that will allow you to administer the groups in either LDAP, JIRA, or both.

This guide describes how to migrate users between the different User Directories as described in Configuring User Directories.

On this page:

Using the 'Migrate users from one directory to another' functionality

This functionality allows for the following scenarios:

  • Migrate all users from JIRA Internal to Delegated LDAP
  • Migrate all users from Delegated LDAP to JIRA Internal
  • Migrate all users from Delegated LDAP to Delegated LDAP

However, it cannot be used for any of the following scenarios:

  • Migrating a specific set of users or one single user from one directory to another
  • Connector User Directories — these can be easily identified, as they have a Synchronize option
  • Migrating groups only
  • Migrating users without their groups

It also has the following features:

  • If you, the currently logged-in user, are in the directory to be migrated from, your user data will not be migrated.
  • Users and groups will not be migrated if they already exist in the target directory. For example, consider a user that exists in JIRA Internal and JIRA Delegated LDAP but has different groups in JIRA Internal: when migrating from JIRA Internal to the JIRA Delegated LDAP, that user will be skipped and the groups will not be migrated.

To migrate users:

  1. Create an JIRA System Administrator in the JIRA Internal Directory, for example localadmin
  2. Log in as that user and perform the migration steps below. This will allow for all other users to be migrated.
  3. If the username needs to be changed as part of the migration, rename them (see Managing Users for instructions).
  4. Log in as a user with the 'JIRA System Administrators' global permission.
  5. Choose > User Management > User Directories.
    (tick) Keyboard shortcut: g + g + start typing directories.
  6. Choose Additional Configuration & Troubleshooting (section) > Migrate users from one directory to another.
    This option will not appear if there are no valid directories to migrate from/to.
  7. Select the from and to directories and migrate the users:
  8. You will be shown a message telling you whether the migration was successful or not. In these example screenshots, only 61 out of 62 users could be migrated, as the user doing the migration was logged into the JIRA Internal Directory.

Migrating Users Manually

If the user migration does not fall into the above scenario, you can migrate users by modifying the database. See this knowledge base article for instructions on how to do this: Move local group memberships between directories in Jira server. When  JRA-27868 - Getting issue details... STATUS  is completed, JIRA will handle this in product.

Last modified on Aug 5, 2014

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.