Goal

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

Prerequisites

  • Jira, Confluence, Bitbucket or Bamboo
  • 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: users in Azure AD have been/ are synchronized from existing LDAP with Azure AD Connect
Only then users in Azure will have the right attribute set which is required for mapping existing users against the user in Azure.

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. Set the Redirect URI to "Web" and enter "https://<your-instance>/plugins/servlet/de.resolution.usersync/oauth2/authorize" in the textfield.
  4. Click on "Register".
  5. 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.
  6. Click on "API permissions" in the left panel.
  7. Click on "Add a permission" and choose "Microsoft Graph".
  8. Click on "Delegated permission". Search for the "User" entry and expand it. Tick "User.Read" and "User.ReadBasic.All".
  9. Click on "Add permissions" to finally add the permissions.
  10. Click again on "Add a permission", choose "Microsoft Graph" and click on "Application Permissions".
  11. Search for the "Directory" entry, expand it and tick "Directory.Read.All".
  12. Then, search for "User", expand it and tick "User.Read.All".
  13. Click on "Add permissions" to add the permissions.
  14. Next, click on "Certificate & secrets".
  15. Add a new Client secret by click on "New client secret".
  16. Enter a description, and choose "Never" for "Expires". Click on "Add".
  17. 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 ID, Directory (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.

Save you settings.

Let User Sync copy users from LDAP to the new directory

Now it's time to initiate a synchronization. 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:

Verify the results

Now that the sync operation has been completed, you can navigate to the Users management console and you should notice,
that your LDAP users are now listed under the Azure directory (or whatever you named your connector):

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

To be better prepared for configuring SAML SSO in the last step of the tutorial, we need to change the usernames to the Azure AD format.
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:

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.

Configure SAML SSO app

Please follow this detailed guide to setup the SAML SSO app with Azure AD.
You can skip its Configure Azure AD for User Sync part as you did that already as part of this guide.