About Azure AD Integration

Issuetrak offers integration with Azure AD via the Identity Management area of the product. The advantages of utilizing Azure AD with Issuetrak are very similar to those from using AD Federation Services:

  • Issuetrak never has the user's credentials.
  • There is no need to use an Active Directory service account.
  • The nature of Azure AD prevents applications from pulling information outside of the scope of an authenticated user.

Azure AD integration is licensed under the Identity Management add-on. If you would like to purchase support for Identity Management, please get in touch with your Account Manager.

Note that using Azure AD with Issuetrak requires:

  • That your site is configured to use SSL
  • That your site's SSL certificate is not self-signed, and can be verified with its issuer
  • That your site and Azure can communicate over standard web ports 80 and 443
  • A "Hybrid" environment backed by Active Directory/LDAP (if it is desired for Asset Management assets to be properly matched to Azure AD users, as applicable)

The Issuetrak tasks in this article can only be performed by an Issuetrak user with the “Can access and maintain Administration functions” permission or the “Sys Admin” parameter.


 

Preparing Your Azure AD Instance for use with Issuetrak

You will need to pre-register Issuetrak with your Azure AD instance before the two can communicate.

Steps:

  1. Open your Azure Management interface.
  2. Navigate to App Registrations.
  3. Click New registration.
    1. Enter a name for the new app registration.
    2. You'll be prompted to select the Account Type. We suggest using "Accounts in this organizational directory only (OrganizationName only - Single tenant)".
      • If you're using a multi-tenant app, then a Microsoft Partner Center ID will need to be added under the branding option after the initial registration.
    3. Leave the redirect URI set to Web, and enter the URL to your Issuetrak site with the following modifiers: 
      • https://IssuetrakSite/core/login/adfs
    4. Click Register.
  4. Take note of the following information, as it will be needed to configure Issuetrak later: 
    1. Application (client) ID
    2. Directory (tenant) ID
  5. Now find and click Authentication in the lefthand menu, then add the following Redirect URIs, taking care to populate your Issuetrak site's external-facing address where IssuetrakSite appears:
    • https://IssuetrakSite/core/adfs/verifyPassword
    • https://IssuetrakSite/core/adfs/testconnection
  6. Click Save.
  7. Find and click Certificates & secrets in the lefthand menu, then click New client secret.
    1. Enter a description for this secret. It is suggested that you make it clear that this is used for your Issuetrak site.
    2. Click Add.
    3. Take note of the secret value that appears below! You will need this later and it won't be shown again!
      • It is recommended that you replace your client secrets regularly.
  8. Find and click Token configuration in the lefthand menu.
  9. Add the Optional Claims:
    1. Click Add optional claim.
    2. Select the ID token type.
    3. Check the boxes to add the following claims: 
      • email  (required)
      • family_name  (required)
      • given_name  (required)
      • onprem_sid  (If migrating from an existing LDAP domain OR it is desired to match Asset Management assets to users from Azure AD)
    4. Click Add.
    5. Check the box in the pop-up that appears with this prompt: "Turn on the Microsoft Graph email, profile permission (required for claims to appear in token)."
    6. Click Add.
  10. Add the Group Claims:
    1. Click Add Groups Claim.
    2. Check the box next to All Groups (includes distribution lists but not groups assigned to the application). This will select three checkboxes, which is exactly what we want:
      1. Security Groups
      2. Directory Roles
      3. All Groups
    3. Click Add.

Now we're ready to configure Issuetrak.


 

Adding an Azure AD Provider

The below steps are intended to add a new Azure AD provider for either a new domain or if you were not already using Active Directory in your Issuetrak site. If you are currently using Active Directory for the applicable domain in your Issuetrak site and are looking to migrate to Azure AD, please refer to this article.

Steps:

  1. If you are not currently using an Identity Management integration with Issuetrak, then go ahead and enable the Identity Management Module.
  2. Click the gear icon in the upper right > click on Azure AD beneath Identity Management.
  3. From the right quick menu, click Add Provider.
  4. Fill in the required information:
    1. Provider Name - What this provider will be called in Issuetrak.
    2. Domain - The domain this provider provides services for.
    3. Azure Cloud Type - Determines the connection method between Issuetrak and your Azure instance.
    4. TenantId - You should have this from the section above.
    5. Client ID - You should have this from the section above.
    6. Client Secret - You should have this from the section above.
  5. Set the Button configuration along the right.
  6. Click Save.

 

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 LDAP or AD Federation Services.


Mapping User Templates

Steps:

  1. Click the gear icon in the upper right > click on Azure AD beneath Identity Management.
  2. Click edit next to the domain that you wish to set mappings for.
  3. Scroll down to the Define Template Mapping section.
  4. 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. Click the gear icon in the upper right > click on Azure AD beneath Identity Management.
  2. Click edit next to the domain that you wish to set mappings for.
  3. Scroll down to the Define Organization Mapping section.
  4. 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. Click the gear icon in the upper right > click on Azure AD beneath Identity Management.
  2. Click edit next to the domain that you wish to set mappings for.
  3. Scroll down to the Define Location Mapping section.
  4. 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. Click the gear icon in the upper right > click on Azure AD beneath Identity Management.
  2. Click edit next to the domain that you wish to set mappings for.
  3. Scroll down to the Define Department Mapping section.
  4. 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 is one Claim automatically mapped by default, for Email. This 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
  • Given_Name -> First Name
  • Family_Name -> Last Name

The SamAccountName mapping cannot be modified or deleted. Any other Claim can be mapped to any UDF or unused field in a user account. All Claims showing, except for the three listed above, can be edited or removed if needed.


Mapping User Properties

Steps:

  1. Click the gear icon in the upper right > click on Azure AD beneath Identity Management.
  2. Click edit next to the domain that you wish to set mappings for.
  3. Scroll down to the Define User Property Mapping section.
  4. Enter a Claim name.
  5. Select the field in the dropdown to map the Claim to.
  6. 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:


 

Deactivating an Azure AD Provider in Issuetrak

If at any point you wish to prevent user logins to Issuetrak from a specific Azure AD provider you may deactivate that provider. If you would like to deactivate the full Identity Management module in Issuetrak, please refer to this article.

Steps:

  1. Click the gear icon in the upper right > click Azure AD beneath Identity Management.
  2. Click edit next to the domain that you wish to inactivate the Azure AD connection to.
  3. Uncheck the box next to Active.
  4. Click Save.

Warning: After inactivating an Azure AD connection or the whole Identity Management module the Authentication Type for each affected user must be changed to Issuetrak and a password must be manually set or, if enabled, the user must perform a Self-Service Password Reset in order to be able to log into Issuetrak.