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 Active Directory add-on. If you would like to purchase support for AD, 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

 

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)
    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.


 

Activating Identity Management in Issuetrak

You will need to activate Identity Management integration in Issuetrak before you can use it.

Steps:

  1. Sign into Issuetrak with a Sys Admin account.
  2. Click the gear icon in the upper right > click on Features beneath System.
  3. Scroll down to Identity Management.
  4. Check the box next to Enable authenticating users with third party identity providers.
  5. Check the box next to Update existing users on login.
  6. Click Update.

Deactivating Identity Management in Issuetrak

You may want to deactivate Identity Management integration under certain circumstances, which will preclude the use of all forms of AD authentication with your instance of Issuetrak. 

Steps:

  1. Sign into Issuetrak with a Sys Admin account.
  2. Click the gear icon in the upper right > click on Features beneath System.
  3. Scroll down to Identity Management.
  4. Uncheck the box next to Enable authenticating users with third party identity providers.
  5. Click Update

Configuring Issuetrak to use Azure AD

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. From the right context 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 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: