Migrating local group memberships when switching to another external directory with local groups in Bitbucket Server/DC
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
When switching to a new external directory with local groups, containing the same set of users as the one already configured in Bitbucket Server, local group membership for groups other than the default stash-users is lost. This can affect project and repository permissions that were granted through group membership, and the users will no longer be able to access those repositories after switching to the new directory
Environment
Bitbucket Server/DC 4.x-7.x
External directory with local groups
Diagnosis
After enabling the new external directory, local groups do not contain any members from the new directory. This can be verified even before disabling the old directory:
The query
1
select directory_id from cwd_group where is_local='T';returns the directory_id associated only with the old directory, and not the new for all local groups other that 'stash-users'.
You can verify which directory_id corresponds to the old and new directory connectors by the query:
1
select id, lower_directory_name from cwd_directory;Cause
This is a known issue tracked in CWD-4886
Solution
Solution/Workaround
1. First, determine all the local groups associated with the old directory_id:
1
select lower_group_name from cwd_group where directory_id='<old_directory_id>' AND is_local='T' AND lower_group_name NOT LIKE 'stash_users';2. Then, for each lower_group_name find the user membership and save them
1
select lower_child_name from cwd_membership where lower_parent_name='<lower_group_name>';3. Disable the old directory and promote the new one to the top of the list in Administration > User Directories
4. Using a REST API endpoint, add memberships to each local group - this can be scripted/combined with the results of the queries.
The rest endpoint is
1
/rest/api/1.0/admin/groups/add-userswhich accepts a POST method with an example JSON body:
1
2
3
4
5
6
7
{
"group": "group",
"users": [
"user1",
"user2"
]
}This is documented in Bitbucket rest API
⚠️ While users logging in through the new external directory will automatically be added to stash-users and therefore be licensed Bitbucket users, if the users do not re-authenticate they will be denied login. To avoid this, you may wish to also preemptively add all necessary users to the stash-users group as well following the procedure outlined above.
Was this helpful?