Migrating users between user directories

Configuring user directories

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

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

  • The difference between the two is a connector will periodically synchronize user details against LDAP and can add/delete users and groups during that process. A delegated directory can only add users/groups upon the user's first login.

    You can easily identify this by looking for the Synchronize option.

  • 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 deactivating a user in LDAP, it will be deactivated in Jira.
  • When deleting a user in LDAP, it will be deleted in Jira if it is not needed, or deactivated 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. 

For all of the following procedures, you must be logged in as a user with the Jira system administrator global permissions.

On this page:

Managing 500+ users across Atlassian products?
Find out how easy, scalable and effective it can be with Crowd!
See centralized user management.

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. If the username needs to be changed as part of the migration, rename them (see Managing users for instructions).
  2. In the upper-right corner of the screen, select Administration > User Management.
  3. In the sidebar, select User directories.
  4. Select Additional configuration & troubleshooting (section) > Migrate users from one directory to another.
  5. This option will not appear if there are no valid directories to migrate from/to.
    User directories page in Jira administration console.
  6. Select the from and to directories and migrate the users:
  7. 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.
    Success message after migrating users.

Migrating users by changing the directory order

This method is only applicable if moving users from the Jira Internal Directory into an LDAP Connector and when LDAP will manage all their groups. Migrating users in this method will not move across any groups as the groups are separate from the Jira Internal Directory to the LDAP Connector.

  1. Add the Connector, as detailed in Connecting to an directory.
  2. Move the new user directory, so that it is ordered before the Jira Internal Directory:
    User directories in Jira administration console.

When users login, they will login to the LDAP Connector rather than the Jira Internal Directory provided the usernames are identical.

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 Data Center. When  JRA-27868 - Getting issue details... STATUS  is completed, Jira will handle this in product.

Last modified on Oct 7, 2022

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.