Summary:

External users lost their local group membership in Bitbucket after they were moved between Organizational Units(OU) in an external directory. Although returning them to their original OU or adjusting the filters to incorporate new OU in Bitbucket can restore the users or groups, it does not reinstate user membership in the original local groups.

Environment:

The solution has been validated in Bitbucket Data Center 8.19.10 but may apply to other versions.

Diagnosis:

If the database debug log is enabled, the following event will be recorded in the atlassian-bitbucket.log. In this example, Bitbucket is removing all group memberships for a user named "user1" because the user was not found during the directory synchronisation.

2025-01-14 19:03:01,960 INFO  [Caesium-1-1]  c.a.c.d.DbCachingRemoteChangeOperations deleting [ 1 ] users
2025-01-14 19:03:01,973 DEBUG [Caesium-1-1] c.a.s.i.c.TransactionManagerBatchProcessor processing [ 1 ] objects in [ 1 ] batches of [ 20 ] with [ com.atlassian.crowd.util.persistence.hibernate.batch.hibernate5.operation.RemoveUserOperation ]
2025-01-14 19:03:01,974 DEBUG [Caesium-1-1] org.hibernate.SQL delete from cwd_membership where lower_child_name=? and directory_id=? and membership_type=?
2025-01-14 19:03:01,974 TRACE [Caesium-1-1] o.h.type.descriptor.sql.BasicBinder binding parameter [1] as [VARCHAR] - [user1]
2025-01-14 19:03:01,974 TRACE [Caesium-1-1] o.h.type.descriptor.sql.BasicBinder binding parameter [2] as [BIGINT] - [32770]
2025-01-14 19:03:01,974 TRACE [Caesium-1-1] o.h.type.descriptor.sql.BasicBinder binding parameter [3] as [VARCHAR] - [GROUP_USER]

Cause:

If a group or user is moved to a different Organizational Unit (OU) and the existing user and group filter in Bitbucket cannot locate them during directory synchronization, those groups and users will be removed from Bitbucket. Additionally, any such users who were part of a local group will also be removed. Moving them back to their original OU or adjusting the filters will restore the user/group, but it will not reinstate the user in their local groups.

For example, consider a user named user1 who belongs to the organizational unit OU1. If the Bitbucket user directory is set up with a user filter to synchronize only users from OU1, and user1 is moved to another organizational unit, OU2, in the external user directory, Bitbucket will not find "user1" in OU1 during the next sync. As a result, "user1" will be removed from Bitbucket's user list and from any local Bitbucket groups that it was a part of. 

Solution:

• If only a few users have lost their local group membership, you can manually add them back through the GUI.
• If many users have been removed from local groups and adding them individually isn't feasible, follow the procedure below: 
  
  • Set up a staging or testing environment using the most recent Bitbucket backup taken prior to the issue. kindly check How to Establish a Staging Environment KB for more information.
  • Once the test instance is ready, you will need to repeat the following API calls for each group:

    • Use the API to retrieve the users associated with a specific group. This information should be obtained from the staging environment. For detailed instructions, kindly review Get group members.

      curl --request GET \
        --url 'http://{baseurl}/rest/api/latest/admin/groups/more-members?context={context}' \
        --header 'Accept: application/json;charset=UTF-8'

      
      

    • Use the following API to Add multiple users to group on the original Bitbucket instance where users lost their privileges. This API will reinstate the users into the group. 
      

      curl --request POST \
        --url 'http://{baseurl}/rest/api/latest/admin/groups/add-users' \
        --header 'Accept: application/json;charset=UTF-8' \
        --header 'Content-Type: application/json' \
        --data '{
        "group": "group",
        "users": [
          "user1",
          "user2"
        ]
      }'