Goal

Migrating 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

Important

After 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.

In our tutorial, the Copy Behaviour is set to copy these users. This only applies to the first sync of a user that does not exist in the connector directory yet.

The Problem

When 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 user1@domain.com while the user is present as user1 in the existing directory
- In the specific case of LDAP, users usually have the samAccountName as a username
When 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 instead

The Solution

There 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 one
Map an alternative attribute of the identity provider user to the username
Rename the existing users, such that they match the usernames sent by the identity provider

Requirements

An internal or external directory to migrate users from
A User Sync connector with the appropriate settings but one that was never synchronized

If 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 Guide

Before the First Migration Synch

There are two things that need to be taken care of: existing local groups and usernames.

Local Groups

If 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 connector
Open the Provisioning Settings tab and scroll to the Group Management section
Change the settings of Never Remove Users From These Groups

You can specify groups that should be retained by either adding each individual group or by using regular expressions, like the examples below.

Groups to keep	Regular Expression
all groups	.*
jira-users, jira-software-users, jira-	jira-.*
confluence-users, confluence-employees, confluence-	confluence-.*

Usernames

For 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 connector

If 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 username
In 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.

Transformations

Username Transformation

A username transformation is usually a regular expression. Below are some examples:

Internal directory username	Identity Provider Username Format	Transformation for the User Sync username
		Regular expression	Replacement
a.example	a.example@domain.com	^(.)@.$	$1
a.example@domain.de	a.example_domain.de#EXT#@Resolution.onmicrosoft.com	^(.)_(.)#EXT#.*$	$1@$2
a.example	a.example_domain.de#EXT#@Resolution.onmicrosoft.com	^(.)_.#EXT#.*$	$1

If 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 Transformation

Please 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 Migration

User Sync

Below is the detailed list of steps again to prepare the connector for the initial migration

Go to the User Sync configuration page and click Edit for the User Sync connector
Open the Provisioning Settings tab
Change the Attribute Mapping and Edit the Username mapping
Click Show Details
Click Regular Expressions and Edit
Click Add Item
Add the desired transformation, click close and then apply.
Make sure that Copy Behaviour is still set to Copy These Users, which it is by default
Scroll down and click Save and Return
Now start the Sync and wait for it to finish
Afterwards, open the User Directories setting in your Atlassian product
Move the User Sync directory before the original/ internal directory

To 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 accounts
This is of no concern and can't be avoided.

SAML SSO

You 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 configuration
Scroll down to Attribute Mapping and click Edit for the Username
Apply the same transformations as in User Sync
Since 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 login
Save your configuration

Result

If 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