User & Group Sync Knowledge Base Current: How to Migrate an Internal Directory to UserSync How to Migrate an Internal Directory to UserSync GoalMigrating an internal directory (or even an external directory such as LDAP, Crowd) to a User Sync directory, such that the history, groups, and tickets of the users in your Atlassian product will be retained. If you have doubts about the process or questions, please do not hesitate to contact us via https://www.resolution.de/go/support ImportantAfter this tutorial, all data from the internal users such as tickets (but not passwords) will be copied over from the internal user to the user in the User Sync directory. As a consequence, login is only possible with Single Sign-On but not with a local password anymore.The ProblemWhen the usernames of the User Sync directory and internal directory do not match, User Sync cannot find the internal users to copy over the data. A common scenario is the following:Before, users were provisioned manually or with an LDAP or Crowd directory. The usernames often consist only of the username part of their email address, while GSuite/ Azure/ Okta or other identity providers send the full email address as the username.Example: GSuite sends firstname.lastname@example.org while the user is present as user1 in the existing directoryIn the specific case of LDAP, users usually have the samAccountName as a usernameWhen performing the migration, User Sync will search for the usernames in the internal directory, but if they do not match, User Sync is not able to find the users for copying data and will create a new user insteadThe SolutionThere are at least two options to solve this, below are the most common.Transform incoming usernames from the identity provider, so that they match the internal oneMap an alternative attribute of the identity provider user to the usernameRename the existing users, such that they match the usernames sent by the identity providerRequirementsAn internal or external directory to migrate users fromA User Sync connector with the appropriate settings but one that was never synchronizedIf you did run a sync with it already for testing, please delete the User Sync connector first, including the directory that will then show up below the connector list in User Sync Directories not Assigned to a Connector (previously called orphaned directory).Create a new User Sync connector, but DO NOT SYNC ANY USER yet.Step-By-Step GuideBefore the First Migration SynchThere are two things that need to be taken care of: existing local groups and usernames. Local GroupsIf you only need to synchronize your groups from the identity provider via User Sync you can skip this section. If you used to manage your groups locally in your Atlassian product, please read the following carefully.To retain groups that are not present on the identity provider but were assigned manually in Jira, Confluence etc. so far, please do as follows:Open the User Sync connector list and Edit your User Sync connectorOpen the Provisioning Settings tab and scroll to the Group Management sectionChange the settings of Never Remove Users From These GroupsYou can specify groups that should be retained by either adding each individual group or by using regular expressions, like the examples below.Groups to keepRegular Expressionall groups.*jira-users, jira-software-users, jira-jira-.*confluence-users, confluence-employees, confluence-confluence-.*UsernamesFor a successful migration, User Sync must be able to find the user by username in the original directory.Below are the most common options. Transform incoming usernames from the identity provider, so that they match the internal one.This can be done in the attribute mapping of the Provisionings Settings tab of the User Sync connectorIf you transform usernames, you might also need to adjust the SAML SSO configuration, so that the user will be found during login.This is because the SAML response from the identity provider always contains a NameID that contains the username of the user logging in.Map an alternative attribute of the identity provider user to the usernameIn the case of an existing LDAP directory and provided that your identity provider is connected to your on-premises AD, you could map the samAccountName to match the existing users.The attribute is different for each identity provider. Below is an example of Azure AD.Rename the existing users, such that they match the usernames sent by the identity provider.This is usually not possible for external directories like LDAP. For default internal directories it is and you could use tools like our Excel connector that allows you to export users, make modifications in the Excel file and import a subset of properties back to the same directory.You can find more details about this in our knowledge base. For more complicated tasks you can always reach out to us for a custom solution.If you are not sure what to do, please contact our support at https://www.resolution.de/go/support.TransformationsUsername TransformationA username transformation is usually a regular expression. Below are some examples:Internal directory usernameIdentity Provider Username Format Transformation for the User Sync usernameRegular expressionReplacementa.email@example.com^(.*)@.*$$firstname.lastname@example.org_domain.de#EXT#@Resolution.onmicrosoft.com^(.*)_(.*)#EXT#.*$$1@$2a.examplea.example_domain.de#EXT#@Resolution.onmicrosoft.com^(.*)_.*#EXT#.*$$1If some users don't fit into any pattern, you could add separate transformation rules for each of them, like a simple search and replace.Search for the existing username, and replace it with the username on the identity provider.If you have any doubt about finding an appropriate transformation, please contact our support via https://www.resolution.de/go/support.Group Name TransformationPlease read the following article, which provides more insights on how to transform group names from the identity provider into something else.Example requirement: transform the group "Company_Jira" to "jira-software-users", so that every user in that group gets access to Jira Software.Setting Up The Connector Configuration & Performing the MigrationUser SyncBelow is the detailed list of steps again to prepare the connector for the initial migrationGo to the User Sync configuration page and click Edit for the User Sync connectorOpen the Provisioning Settings tabChange the Attribute Mapping and Edit the Username mappingClick Show DetailsClick Regular Expressions and Edit Click Add ItemAdd the desired transformation, click close and then apply.Make sure that Copy Behaviour is still set to Copy These Users, which it is by defaultScroll down and click Save and ReturnNow start the Sync and wait for it to finishAfterwards, open the User Directories setting in your Atlassian productMove the User Sync directory before the original/ internal directoryTo validate if the migration was successful, you need to open the user browser and verify if the users are now shown under the User Sync connector directory.If this is true, check for other indicators of a successful migration: profile icon, log-in details and object references were preserved. The latter you can usually see by opening the user profile. Confluence In Confluence, you'll only see the user directories on the user detail page. The primary directory is shown on top and should be your connector directory. Health Check Warning Having users with the same name in multiple directories might show an Atlassian health check warning: Duplicate user accountsThis is of no concern and can't be avoided. SAML SSOYou might need to assign the same username transformations to your SAML SSO configuration. This depends on whether you were using a SAML config already that was working or not.For a new setup, it would definitely be required. An alternative to that would be to configure the NameID value in the identity provider SSO configuration.Open the SAML Single Sign-On configuration and open the identity provider configurationScroll down to Attribute Mapping and click Edit for the UsernameApply the same transformations as in User SyncSince you are using User Sync for provisioning, you should also change the User Creation and Update settings in your SAML SSO configuration; this will make sure that users are always updated and new users are created during loginSave your configurationResultIf everything went well, you migrated users from your original/ internal directory to a User Sync directory for your identity provider. Users should still see their tickets, mentions, pages and other object references. You should disable the original directory after a successful migration, if possible. Other than LDAP or Crowd, the internal directories can't be disabled.We don't recommend deleting the directories, at least not for the period of a few months, just to make sure you didn't miss anything. If something did not work as expected, please do not hesitate to contact our support for help. We can also have a free screen share to prepare the migration together: https://calendly.com/resolution-support/support SAML Single Sign-On is available for Atlassian Server & Atlassian Data Center products. Our Jira Data Center, Confluence Data Center, Bitbucket Data Center, Jira Server, Confluence Server, Bitbucket Server and other apps are all available on the Atlassian Marketplace.