Migrating to Azure AD

This article provides steps for migrating a site with AD/LDAP-authenticated users to use our Azure AD integration. If you don't have AD configured but would like to configure Azure AD integration, please see this article.

At a high level, the following things happen as a result of a migration:

  1. The old domain value is validated against the new domain value to ensure that they match.
  2. AD/LDAP is deactivated.
  3. ADFS/Azure is set as the Authentication Type for all previously AD/LDAP-authenticated users.
  4. The following fields are populated for each user account:
    1. Authentication Type: ADFS/Azure
    2. Active Directory User SID
    3. Domain
  5. The mappings from Active Directory are transferred to Azure AD.
    1. Any "Map Additional Attributes" are also mapped to the "User Property Mapping".

Warning: If you are migrating from AD Federation Services to Azure AD, you must first roll back to Active Directory(LDAP) and remove the connection for AD Federation Services prior to migrating to Azure AD. Failure to complete this step will duplicate all Azure AD users as they log in for the first time and will require manual account merges for each user to resolve.


Part 1: Perform an Active Directory User Import

This step ensures that AD-authenticated users in Issuetrak have the appropriate properties set for SID, Domain, and Authentication Type. Failure to perform this step could result in duplicate user creation when users sign into Issuetrak.

Steps:

  1. Click the gear icon in the upper right > click on Active Directory beneath Identity Management > click on Import Users from the right context menu.
  2. Select the Domain from the dropdown for which this particular import should be performed from the list.
  3. Click the radio button to select either AD Group or AD OU. Click the button related to your selection. Only AD Groups or OUs with verified Organization and Permissions mappings and valid users will appear.
  4. Select the appropriate value in the window that appears.
  5. Click the Preview Import button.
  6. Verify the import is being returned properly in the Preview import window that appears.
  7. Close the Preview Import window.
  8. Click the Process Import button to process this import.
  9. Repeat the import process for as many OU/Groups as necessary to account for your AD environment and ensure all of your users will be able to authenticate.

Part 2: Preparing your Azure AD Instance

Please see this article for steps to configure your Azure AD instance to work with Issuetrak.


Part 3: Complete the Migration

With the information gathered from the initial preparation, we can migrate to Azure AD in Issuetrak.

Steps:

  1. Navigate to your Issuetrak site and log in with a Sys Admin account.
  2. Click the gear icon in the upper right > click on Azure AD beneath Identity Management.
  3. Choose Migrate from AD from the right context menu.
  4. Check the box next to "Perform an Active Directory user import".
  5. Check the box next to " Setup Azure AD Account (Guide)".
  6. Populate the following data:
    1. Provider Name: A friendly name for your Azure AD instance.
    2. Domain: The Domain of your Azure AD instance. Ensure this matches the domain currently in your Issuetrak instance's AD settings.
    3. Azure Cloud Type: The environment for your Azure AD instance.
    4. TenantID: The TenantID you obtained from configuring your Azure AD instance to work with Issuetrak.
    5. Client ID: The Client Identifier from configuring your Azure AD instance to work with Issuetrak.
    6. Client Secret: The shared secret from configuring your Azure AD instance to work with Issuetrak.
    7. Button Label: The name of the button to display on the Issuetrak Login page.
  7. Double-check the values you've entered and confirm that you are ready to migrate to Azure AD. Click Migrate Server Settings to save the settings.
  8. Click Perform Migration to finalize the process.
  9. You will be redirected to the Edit Azure AD page. Click the Test Connection button. This will launch a new browser tab to your Azure AD instance's authentication page. Sign in with your AD credentials and accept the prompt that requests permission to view your account information. You will then be taken to another page to view the Test Connection results. See this section for more information about the permission prompt.
  10. Optional: Customize the appearance of this identity provider's button on the login screen by using the fields on the right-hand side.

 

Creating User Mappings for Azure AD

The final step to configuring Azure AD is to create mappings for user accounts. Without a minimum of Organization and Template mappings, users will be unable to sign in using the identity provider you configured.

Issuetrak uses identity claims to map users to the correct organizations, user templates, locations, departments, and any user account UDFs that are configured. This is more constrained than using traditional mappings from AD or AD Federation Services.


Mapping User Templates

Steps:

  1. Sign into Issuetrak with a Sys Admin account.
  2. Click the gear icon in the upper right > click on Azure AD beneath Identity Management.
  3. Click edit next to the domain that you wish to set mappings for.
  4. Find Define Template Mapping.
  5. Set the Priority. Priority determines whether this mapping takes precedence over other mappings of the same type that match. A lower number indicates a higher priority.

For example, if two User Template mappings named Alpha (Priority 1) and Bravo (priority 2) are matched to the same user account, the mapping with the higher priority (lower number) takes precedence. Thus, a user account that matches both templates' criteria will be mapped to Alpha.

  1. Enter the name of the Claim that will be scanned by Issuetrak to determine the origin of this mapping.
  2. Enter the Matching Value that applies to the claim.
  3. Select which User Template this claim should be mapped to upon a successful match.
  4. Click Save.

Mapping Organizations

Steps:

  1. Sign into Issuetrak with a Sys Admin account.
  2. Click the gear icon in the upper right > click on Azure AD beneath Identity Management.
  3. Click edit next to the domain that you wish to set mappings for.
  4. Find Define Organization Mapping.
  5. Set the Priority. Priority determines whether this mapping takes precedence over other mappings of the same type that match. A lower number indicates a higher priority.

For example, if two Organization mappings named Alpha (Priority 1) and Bravo (priority 2) are matched to the same user account, the mapping with the higher priority (lower number) takes precedence. Thus, a user account that matches both Organizations' criteria will be mapped to Alpha.

  1. Enter the name of the Claim that will be scanned by Issuetrak to determine the origin of this mapping.
  2. Enter the Matching Value that applies to the claim.
  3. Select which Organization this claim should be mapped to upon a successful match.
  4. Click Save.

Mapping Locations

Steps:

  1. Sign into Issuetrak with a Sys Admin account.
  2. Click the gear icon in the upper right > click on Azure AD beneath Identity Management.
  3. Click edit next to the domain that you wish to set mappings for.
  4. Find Define Location Mapping.
  5. Set the Priority. Priority determines whether this mapping takes precedence over other mappings of the same type that match. A lower number indicates a higher priority.

For example, if two Location mappings named Alpha (Priority 1) and Bravo (priority 2) are matched to the same user account, the mapping with the higher priority (lower number) takes precedence. Thus, a user account that matches both Locations' criteria will be mapped to Alpha.

  1. Enter the name of the Claim that will be scanned by Issuetrak to determine the origin of this mapping.
  2. Enter the Matching Value that applies to the claim.
  3. Select which Location this claim should be mapped to upon a successful match.
  4. Click Save.

Mapping Departments

Steps:

  1. Sign into Issuetrak with a Sys Admin account.
  2. Click the gear icon in the upper right > click on Azure AD beneath Identity Management.
  3. Click edit next to the domain that you wish to set mappings for.
  4. Find Define Department Mapping.
  5. Set the Priority. Priority determines whether this mapping takes precedence over other mappings of the same type that match. A lower number indicates a higher priority.

For example, if two Department mappings named Alpha (Priority 1) and Bravo (priority 2) are matched to the same user account, the mapping with the higher priority (lower number) takes precedence. Thus, a user account that matches both Departments' criteria will be mapped to Alpha.

  1. Enter the name of the Claim that will be scanned by Issuetrak to determine the origin of this mapping.
  2. Enter the Matching Value that applies to the claim.
  3. Select which Department this claim should be mapped to upon a successful match.
  4. Click Save.

User Property Mappings

There are several claims automatically mapped by default for Street Address, City, State, etc. These can be edited or deleted if necessary.

Additionally, three claims are mandatory and automatically mapped to fields for each user. They are mapped as follows:

  • SamAccountName > User Id
  • GivenName > First Name
  • LastName > Last Name

Any other Claim can be mapped to any UDF or unused field in a user account.


Mapping User Properties

Steps:

  1. Sign into Issuetrak with a Sys Admin account.
  2. Click the gear icon in the upper right > click on Azure AD beneath Identity Management.
  3. Click edit next to the domain that you wish to set mappings for.
  4. Find Define User Property Mapping.
  5. Enter a Claim name.
  6. Select the field in the dropdown to map the Claim to.
  7. Click Save.


Testing User Mappings

The Test User Mappings button provides the capability to authenticate a user account and immediately display the mappings that are applied to that account. It is recommended for customers to test user account mappings by creating a 'dummy' AD account that has the same mappings as the target user(s), then authenticate that user via the Test User Mappings prompt to check the mappings.

Even if you're just testing the mappings, if it's the first time Issuetrak is attempting to authenticate via Azure, then it will display a prompt that may seem unexpected. See the section below for more information on this.


 

First Time Signing into Issuetrak via Azure AD

The first time you attempt to sign into Issuetrak with your Azure AD credentials, you will be greeted with a prompt in your browser to provide permissions to Issuetrak to use Azure AD for authentication. You must accept this in order for Azure AD integration with Issuetrak to work.

The prompt will look something like this: