Summary

You've setup Bitbucket Server connected to an external LDAP User Directory and now your organization is migrating users to another domain or LDAP directory where the username format is different. You want to migrate to the new directory without losing any data (pull requests, personal forks etc) associated with users/usernames from your old LDAP. Simply adding the new directory then disabling the original directory will not transfer over those associations.

Example: 
DomainA --> UserA --> username: charlieatlassian 
DomainB --> UserA (same user in Domain A) --> username: charlie.atlassian

You are planning to discontinue DomainA, so you want to copy/move/migrate UserA (charlieatlassian) in DomainA to UserA in DomainB  (charlie.atlassian) without any data loss. This guide describes two methods to switch user authentication from an Active Directory to another Active Directory and keep user history. 

Environment

• Bitbucket
• LDAP

Solution

Option 1 - Using a temporary attribute

Using a temporary additional attribute to change the usernames used in the original(old)directory before migrating to the new directory allows you to preserve associations in the course of migrating.

Step 1

1. Identify an attribute you can use, or create a new one, in your original external directory.  In Active Directory, for example, there are a number of "extension attributes" named things like "initials" which can be used. 
2. Populate the above-identified attribute with the username for the new domain/directory.
3. Modify your Bitbucket User Directory Configuration in () (Administration) > User Management > User Directories so that the "User Name Attribute" and "User Object Filter" (in User Schema Settings) is changed to the temporary attribute.
   • If you used "initials" as the new added attribute, you can add it to the User Scheme Settings in Bitbucket as below:

• • Remember to use the value of "initials" attribute as the User name while retrieving users and groups.
  • Synchronize the directory.  At this point you should see your user's usernames updated to the new format.

Step 2

1. Verify all users are able to login and have not lost any data. Users will need to log in by using whatever has been set in their "extension attributes".
2. Add a new User Directory, as detailed in Connecting to an LDAP directory to add the new Active Directory.
3. If you sync at this point, you should not see new Users in Bitbucket because they will have the same usernames as the Users synced from the original directory.
4. Promote the new directory above the old directory.
   

The result of this should be that your users are able to log in using the new username, which will be authenticated against the new directory server, and you are safely able to disable and/or remove the old directory connector (after testing that everything is working as expected). 

Option 2 - Using internal directory

1.  You need to be logged in as an admin user authenticating with the Internal Bitbucket .
2.  Disable the external directory.
3.  Create users in the Internal Directory with their username matching the original/old external directory. It may be worthwhile to script this using something like the Bitbucket REST API to avoid manually entering these. (See Bitbucket core Rest API)
4.  Promote the Internal Directory above the external directory. At this point if you had manually set a password for the Internal Directory users, you should be able to log in as one and verify that associations are still intact.
5.  Rename users to use the username format of the new external directory. As above, it's probably best to script or otherwise automate this step.
6.  Add the new directory connector below the internal. 
7.  Synchronize the directory manually. If you sync at this point, you should not see new users in Bitbucket because they will have the same usernames as the users in the Bitbucket Internal Directory. 
8.  Promote the new directory connector above the Internal Directory. (Now if you look again at user directory the renamed users will only have the directory connector as the user directory)

Note: You can also move from the internal to a new external directory, starting from step 5 and following the rest of the steps.

Note: There is an open request to provide the ability to migrate users across directories  BSERV-5195 - Add ability to Migrate Users from one directory to another GATHERING INTEREST

Removing the internal users created for the migration

After you verify that the migration is successful, you should remove the internal users created to accomplish it. One reason for that would be that if users from the external AD are ever removed, the internal user will remain and consume a license. The search function may also return two users.

To do so:

1. The external directory is above the Bitbucket internal directory, so all (or most) users appear to be from the external directory
2. Move the Bitbucket internal directory above the external (do not disable any directory!)
3. Now all (or most - the duplicated users we created for the rename) users should appear to be coming from Bitbucket Internal directory, and there are no duplicates in the Users UI interface.
4. Delete one test user from the Bitbucket Internal directory. Now, the same user will still appear in the Users interface, with the "external directory" listed next to their name.
5. Log in as that user and check that their history is intact (pull request activity, personal repos)
6. Promote the external directory above the internal.

Caveat

One important limitation here is that Group membership information won't be maintained using this approach.  If groups are managed entirely externally, you'll need to make sure before migrating that the correct groups are configured in the new directory.