How to migrate Bamboo users between two external user directories with different user name formats
Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
The steps outlined on this article are provided AS-IS. This means we've had reports of them working for some customers — under certain circumstances — yet are not officially supported, nor can we guarantee they'll work for your specific scenario.
You may follow through and validate them on your own non-prod environments prior to production or fall back to supported alternatives if they don't work out.
We also invite you to reach out to our Community for matters that fall beyond Atlassian's scope of support!
You've setup Bamboo 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 and then disabling the original directory will not transfer over those associations.
For example:
DomainA --> UserA --> username: charlieatlassianDomainB --> 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 one method to switch user authentication from an Active Directory to another Active Directory and keep user history.
We strongly recommend you do this first in a non-production, staging, or test environment. Make sure you take a Bamboo backup before proceeding with the following steps.
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.
Environment
Bamboo connected to Jira, Crowd, or LDAP for User Management.
Solution
Migrating to an external directory
Log in to Bamboo as an admin user authenticating with the Internal User Directory.
Disable the external directory.
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 Bamboo REST API to avoid manually entering these. Consider using Renaming user and Creating user REST API endpoints.
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.
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.
Add the new directory connector below the internal.
Synchronize the directory manually. If you sync at this point, you should not see new users in Bamboo because they will have the same usernames as the users in the Bamboo Internal Directory.
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.
You can also move from the internal to a new external directory, starting from step 5 and following the rest of the steps.
There is an open request to provide the ability to migrate users across directories:
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:
The external directory is above the Bamboo internal directory, so all (or most) users appear to be from the external directory
Move the Bamboo internal directory above the external (do not disable any directory!)
Now all (or most - the duplicated users we created for the rename) users should appear to be coming from Bamboo Internal directory, and there are no duplicates in the Users UI interface.
Delete one test user from the Bamboo Internal directory. Now, the same user will still appear in the Users interface, with the "external directory" listed next to their name.
Log in as that user and check that their history is intact (pull request activity, personal repos)
Promote the external directory above the internal.
Was this helpful?