Goal

This tutorial describes what to do, when LDAP based authentication should be replaced with Azure AD, renaming the usernames as well (optional).
Existing users should keep their tickets, pages etc. after migrating to the new IdP.

Prerequisites

  • Jira, Confluence, Bitbucket or Bamboo Server/ Datacenter
  • SAML SSO which always comes with User Sync
  • Azure Active Directory
    • Azure AD is assumed to be your new IdP, containing all the users and groups which used to exist in LDAP

Important: the following will only work, if users in Azure AD have been/ are synchronized from the existing LDAP to Azure using Azure AD Connect


High Level Migration Summary

The migration will be performed in the following order:

  1. Install SAML SSO (which always comes with the User Sync app)
  2. Register app for User Sync in Azure AD 
  3. Setup User Sync connector for your Azure AD 
  4. Let User Sync copy users from LDAP to the new directory 
  5. Verify the results
  6. Disable old LDAP directory
  7. Change usernames to Azure AD format
  8. Configure SAML SSO to use Azure AD as identity provider

Step-by-Step Migration Guide

Install SAML SSO


In your Atlassian product, open the in-product marketplace as described in the Atlassian documentation.
Search for "resolution saml" and click "Install" for SAML Single Sign On (SSO) by resolution Reichert Network Solutions GmbH



After the installation is complete, click on Manage, then choose Configure

Now, you are on the Add-on / app configuration page and the first step of the setup wizard will appear.



Register app for User Sync in Azure AD 

Below is a text based step by step guide for registering an app in Azure AD. 
This is required to connect User Sync with Azure AD, described in the next chapter.

Quickstart guide

Go to portal.azure.com, click "Azure Active Directory" in the left panel and then choose "App registrations".

  1. Click on "New registration"
  2. Enter a "Name" for the app.
  3. Click on "Register".
  4. On this page you can see the "Application ID" and the "Directory (tenant) ID". You will need both to setup the Azure AD connector in User Sync.
  5. Click on "API permissions" in the left panel.
  6. Click on "Add a permission" and choose "Microsoft Graph".
  7. Click on "Application Permissions".
  8. Search for the "Directory" entry, expand it and tick "Directory.Read.All".
  9. Click on "Add permissions" to add the permissions.
  10. Click on "Grant admin consent for ...".
  11. Next, click on "Certificate & secrets".
  12. Add a new Client secret by click on "New client secret".
  13. Enter a description, and choose "Never" for "Expires". Click on "Add".
  14. Copy the secret now ("VALUE"). You are not able to see it again after leaving that page. Please paste it to a text editor for the tutorial.


Now it is time to configure UserSync in your Atlassian product. Please keep the Azure website open, because we will need it later on.

  1. Now, go back to your Atlassian product, and go to the UserSync Configuration.
  2. Click Add Connector and choose Azure Connector.
  3. First, paste the client secret (which you copied before) into the Application Secret.
  4. Next, go back to the Azure website and click Properties in the app you have created for UserSync. Copy the Application ID and Directory (Tenant) ID and paste them into the UserSync configuration in your Atlassian product.
  5. In the UserSync configuration, activate Enable Scheduled Synchronization. You can provide a Cron expression to set a synchronisation interval.


Setup User Sync connector for your Azure AD

Now that you've got application Id, directory (tenant) Id and the application secret, you can head over to the administration console of Jira or Confluence
and click on User Sync in the the left hand navigation area. This will take you to the User Sync Configuration page.

Click on "Add Connector" and choose "Azure Connector".

Grab the Application ID, Directory (tenant) ID and the Application Secret from the previous chapter.
You can find it again on the overview page of the Azure AD app. If you forgot to copy the application secret, you need to create a new one.

Copy and paste Application IDDirectory (tenant) ID and the Application Secret into the the corresponding fields on the Azure AD connector page
and click on Authorize

Once you've successfully granted the permissions needed, the connector can now be further configured.
Click on Show Advanced Settings at the bottom of the configuration page which will reveal more configuration settings.

Scroll down to the User Sync Settings section and select "Copy theses users" as copy behaviour.

Then scroll to the Attribute Mappings section and select onPremisesSamAccountName (onPremisesSamAccountName) 
as connector attribute value for the Username application attribute value. 

This ensures that the old LDAP usernames will be preserved, so that users keep their issues, filters, pages etc.

Further down on the advanced settings page, you'll find a section called Local Group Management in which you should consider adding the below wildcard expression
for Keep these Groups:
.*

So the settings should look like this afterwards:

This is the safest way to ensure, that all groups who used to be assigned to the users in the old directory are also available in the new directory.
This is only required if you are unsure about all existing groups also being available in Azure with the same name or you can't make the transition that quickly.
You can remove that wildcard later and only groups assigned to the users in Azure would be assigned to the user in Jira/ Confluence/ Bitbucket.
You could also be more specific about what groups you want/ need to keep, by adding each by name in a single entry.

Group memberships can be important for applying restrictions to projects and spaces. Keeping all existing groups for the migration is always the safest option.

Before you save your settings, make sure scheduled synchronization is not enabled/ checked!



Now it's time to Save you settings to start the initial sync. Continue with the next chapter below.

Let User Sync copy users from LDAP to the new directory

Click on the Sync button in the actions column. User Sync will lookup the users from Azure AD in your existing directories, find them in the LDAP user directory
and copy the users to the directory which has been created by the connector.

The sync might take some time, depending on the amount of users. During and after that time, you'll see a status window, informing you about the progress:

Partial failures don't necessarily mean something is wrong, usually these are Azure AD internal users with missing attributes which couldn't be processed.
You can check details by looking at the file provided via Download results or look at the top of the status window:

Change Directory Order and Verify the results

Now that the sync operation has been completed, we have the same user in two directories:
the LDAP directory and the Azure AD directory from User Sync. 

Authentication will always happen with the user found in the first directory in the User Directories section.
Hence you need to move the Azure AD directory above the Active Directory server/ LDAP directory.
 

You should then verify the result of your migration sync, all users who have been migrated should appear under the new Azure AD directory
from the User Sync connector in the Users management console:

You should still see details like the profile icon picture, login details, group memberships and application access.

Disable old LDAP directory

Now that users have been copied, you can disable the LDAP directory (don't delete it yet).
From this point on, no user will be able to login anymore and this won't work before you've completed the configuration of the SAML SSO app in the next chapter.

Change usernames to Azure AD format

If you do want to rename your usernames so that match the Azure AD "User Principal" name, please do as instructed below.
If you don't want to- start reading 
Keep LDAP/ Active Directory Username below this section.


Go back to the User Sync configuration of your Azure connector (click on Edit) and click on Show Advanced Settings again

Navigate to the Attribute Mappings section and select userPrincipalName (userPrincipalName)
as connector attribute value for the Username application attribute value. 
Save you settings and initiate another sync again.

Once complete, you'll notice that the usernames have been changed to match the Azure AD format:

Post Username Renaming Tasks

If usernames change in Jira, Confluence and on other platforms, it's always recommended to start a re-index and clear caches of the application.
Please find below a quick summary of these tasks, depending on the Atlassian product:

Jira

Perform a background index (or one blocking Jira, causing a temporary downtime)
https://confluence.atlassian.com/adminjiraserver/search-indexing-938847710.html

Confluence

Perform a content index
https://confluence.atlassian.com/doc/content-index-administration-148844.html

Flush Caches, you can do that in at the end of the cache admin page https://your-confluence/admin/cache/showStatistics.action 
with the Flush All button. Read more about Cache management in Confluence here:
https://confluence.atlassian.com/doc/cache-statistics-150472.html

Bitbucket

We are not aware of any indexing which could be done

Bamboo

https://confluence.atlassian.com/bamboo/reindexing-data-289277251.html

Schedule synchronization with Azure AD

You might want to schedule the synchronization of your Azure directory with User Sync.
You'll find the settings for that again under Show Advanced Settings at the very bottom of the page.

Enable Scheduled Synchronization needs to be ticked, the default cron expression would then cause a sync every hour.

Now it's time to finally configure SAML SSO so that users can Single Sign-on via Azure AD.
Please follow the steps in the linked guide in the next chapter.

Keep LDAP/ Active Directory Username

This step is optional alternative to the previous chapter.
If you don't want to rename users to the new Azure AD username format as described above, because of different requirements,
you'll just need to make sure, that SSO is configured in a way so that usernames sent by Azure AD are matched against the old LDAP username format.
That can be accomplished by changing the NameId claim rule in the Azure AD SSO Enterprise app to onPremisesSamAccountName.

If this is the SSO Enterprise app, edit User Attributes & Claims

and click on Unique User Identifier: 

and change its value to onpremisessamaccountname

Configure SAML SSO app

Please follow this detailed guide to complete the setup of SAML SSO itself.
You can skip its Configure Azure AD for User Sync part as you did that already as part of this guide.
Remember: if you didn't rename the users to the Azure AD format, make sure you change the claims accordingly.