How to migrate from a connector type user directory to delegated
There are a variety of reasons to switch to from a "connector type authentication directory" or "LDAP" to Delegated Authentication Directory or "Internal with LDAP Authentication". For instance. some products like Bitbucket that work best with a small heap are not suited for indexing large numbers of users. It could be that you've run into Inconsistent/ intermittent user permissions and login issues because you have a load balanced LDAP. Another great reason to move to Delegated type directories is that only users that login will count toward your license which can help keep your license count low.
Is Delegated Right for Me?
There are a couple things you should make note of before switching to delegated LDAP.
- Your users and groups will only be updated on each login. This means that the users will continue to be licensed even after you remove their permissions by editing your LDAP. The user would have to login or be removed manually. This is a feature request in BSERV-3321. More on this later.
- There isn't a way to filter groups, so you can end up with thousands of groups that you didn't intend to see in Bitbucket. If there are too many this can result in long loading times for "@" mentions and permissions calculations.
Moving from a connector type "LDAP" user directory to Delegated will require some manual modifications to the database for everything to go smoothly, especially if this is for Bitbucket Server. Without these modifications you could end up with shadowed local groups, which prevents groups from updating, and users with SSH keys tied to their user profile that don't work for Git operations.
The embedded version of Crowd in Atlassian products works great for smaller to medium user bases, but it doesn't scale well when you're dealing with thousands of users and groups. Atlassian's intention was that enterprise customers would use standalone Crowd and as such we have designed it with those concerns in mind. Not only do you have one place to manage all your users and groups across Atlassian applications, but standalone Crowd also offers failover user directories in the event a Crowd loses connection. This is not available in Bitbucket or embedded Crowd.
Setting up Standalone Crowd as a solution is very easy to implement from your current configuration and will require little effort. However, it of course cost more money. This is the recommended implementation for enterprise customers with thousands of users, especially for Bitbucket.
Be sure to test this on a QA environment before implementing in production. Be sure to backup production before making any changes to the database.
- Create delegated directory.
- Disable old connector directory.
- Shut down Bitbucket.
- Find the ID's of the old directory and the new one. You can find this ID by going to Administration > User Directories > and editing the directories. The URL of the that page should contain a number like directoryId=30441473.
- Run the following SQL. In this example 30441473 is the new delegated directory's id, and 5537793 is the old LDAP directory’s id.
UPDATE cwd_user SET directory_id = 30441473 WHERE directory_id = 5537793;
UPDATE cwd_user_attribute SET directory_id = 30441473 WHERE directory_id = 5537793;
UPDATE cwd_group SET directory_id = 30441473 WHERE directory_id = 5537793;
UPDATE cwd_group_attribute SET directory_id = 30441473 WHERE directory_id = 5537793;
UPDATE cwd_membership SET directory_id = 30441473 WHERE directory_id = 5537793;
Once you run the above you can start Bitbucket and remove the old connector type user directory.
As I mentioned before, users won't be updated until they login. With a delegated type directory, a local users are created upon login. These users are added to an internal group that has global permissions to you application. If you were to de-activate users in your LDAP, those users could no longer access Bitbucket instantaneously, however, they would still use up a license count because they are technically allowed by the global permissions of the application. For this reason you will likely need a script to remove users who have been deactivate in your LDAP, otherwise they will slowly build up over time. This script would have to do the following periodically:
- Query for inactive or idle users
- Remove those users using SQL or REST API.