WIP

Goal

1. replace an existing LDAP directory with an Azure Active Directory

2. keep the existing LDAP usernames (SAM Account Name) or alternatively

3. migrate to Azure AD usernames (UPN)

Prerequisites

• Jira or Confluence 

  • LDAP based user directory, which could have been set up of type

    • Microsoft Active Directory (This option provides a quick way to select AD, because it is the most popular LDAP directory type)

    • LDAP (for other specific LDAP directory types, including the above)

  • with SAML SSO with User Sync installed

• Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server 2016 (Windows Server as Domain Controller)

• (Cloud based) Azure Active Directory identity provider

Preparing Azure AD

Please refer to the tutorial linked here describing everything you need to configure on the Azure AD side.
Once complete, you can migrate your users to a new user directory which will later replace your existing LDAP directory.

Migrating users from LDAP to Azure AD

Now that the existing Windows AD users have been synched to Azure AD, you can start setting up the replacement for the LDAP based user directory in Jira.
This is accomplished by setting up User Sync, which is part of the SAML SSO app. A new user directory will be created in the process.
Once everything is working and tested, the old LDAP based user directory can be disabled or even deleted later.

For the basic setup, you should follow the Azure AD part of the guide below, but don't start the sync procedure yet:
https://wiki.resolution.de/doc/saml-sso/latest/all/user-and-group-synchronisation-user-sync

In the connector settings you can now click on Show Advanced Settings

Unknown Attachment

Depending on what usernames you want in the end, you can choose one of the following sub steps, both involving the Attribute Mappings settings.

Keep existing LDAP usernames

To keep the existing name, just select "onPremisesSamAccountName" from the Connector Attribute dropdown of the Username record:

Unknown Attachment

Migrate to Azure AD usernames

To migrate usernames to the Azure AD format, select "userPrincipalName" from the Connector Attribute dropdown of the Username record:

Unknown Attachment

Configuring SAML SSO based authentication

Basic configuration

After the successful migration of the users to the Azure AD, SAML SSO needs to be configured to authenticate against Azure as the new identity provider.
You can follow the instructions for SAML SSO for Jira by resolution GmbH or SAML SSO for Confluence by resolution GmbH.  

Additional configuration

In order to enable the Azure IdP you've just configured to send the right name identifier, this needs to be changed via User Attributes & Claims in the Single Sign On Settings in Azure.
To do that, perform the following steps:

• navigate to your Azure portal and select your Azure Active Directory, followed by selecting "App registration" and selecting the SSO app you've set up earlier
  Unknown Attachment
  Unknown Attachment

  At the time this documentation was created, there is an "App registration" and "App registration (Preview)". This might change again.
  The "App registration" link might not reveal all apps registered from the beginning, depending on by whom it was created.
  Use the "View all applications" button to continue configuring your SSO app (by clicking on the app name again).
  

• click on the link below "Managed application in local directory"
  

  Unknown Attachment

  
  
  

• now navigate to "Single Sign On" on the page opened
  

  Unknown Attachment

  
  
  

• this will reveal the SSO settings again:
  

  Unknown Attachment

Unique User identifier is Azure AD username (UPN)

With a the original SSO configuration followed in the guides linked in chapter "Basic configuration", nothing needs to be changed.
Verify that the name identifier value is set to user.userprincipalname

Unknown Attachment

Unique User identifier is old LDAP username (SAM Account Name)

Editing the settings for "User Attributes & Claims" will enable you to change the "Unique User Identifier" at the top
of the edit screen, to use the user.onpremisessamaccountname instead

Unknown Attachment