About Active Directory Federation Services (AD FS)

Active Directory Federation Services (AD FS) is a framework for authenticating users to an application without direct communication with a domain controller. This is a better and more secure way of implementing authentication for Issuetrak because:

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

AD FS 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.

We also provide integration with Microsoft's Entra ID platform, discussed separately in this article.

The 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 the AD FS Server

Please see this article for steps to configure your AD FS server to work with Issuetrak.

 

Adding an AD Federation Services Provider

The below steps are intended to add a new AD FS 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 AD FS, please refer to this article.

With the information gathered from preparing AD FS we can set up AD Federation Services in Issuetrak.

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 AD Federation Services beneath Identity Management.
  3. Choose Add Provider from the right quick menu beneath AD Federation Services.
  4. Populate the following data:
    1. Provider Name: A friendly name for the AD FS server.
    2. Domain: The Domain containing the users.
    3. Provider URL: The URL to the AD FS server.
    4. Client ID: The Client Identifier from setting up AD FS.
    5. Client Secret: The shared secret from setting up AD FS.
    6. Button Label: The name of the button to display on the Issuetrak Login page.
  5. Click Save to save the settings. You will be redirected to the Edit AD Federation Services Provider page.
  6. Click the Test Connection button to verify all the settings.
    1. This button launches a new browser tab to your AD FS provider's authentication page.
    2. It is necessary to sign in with an Active Directory account to view the Test Connection results.
  7. 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 AD FS

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

Issuetrak uses AD FS identity claims to map users to the correct organizations, user templates, locations, departments, and any user account UDFs that are configured.

When you enter the matching value for a claim, Issuetrak will do a 'contains' search to find matches. If needed, you can prefix the value with "cn=" to allow more precise matches of that value to be selected.

Additionally, you may choose to toggle "Exact Match" when you add a mapping.

Mapping User Templates

Steps:

  1. Click the gear icon in the upper right > click on AD Federation Services beneath Identity Management.
  2. Click edit next to the provider 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.
    1. You may choose to toggle "Exact Match" for this mapping.
  3. Select which User Template this user should be mapped to upon a successful match.
  4. Click Save.
Mapping Organizations

AD Federation Services integration in Issuetrak assigns organizations differently depending on whether it is creating new users or merely updating them.

New users created by manual AD import, scheduled AD import, or upon login will have their organization set only by the organization they are mapped to within Mapping Organizations. This becomes their primary organization, and no membership is granted based on the organization membership of user templates designated in the Define Template Mapping section.

Users updated via manual import, scheduled import, or upon login will have their organization set thusly:

  • If the existing user has only a primary organization membership and it doesn't match the organization they are mapped to, then their primary organization membership is changed to their mapped organization.
  • If the existing user has membership in more than just their primary organization, and their current primary organization differs from the organization they are mapped to, then their primary organization will change to match the organization they're mapped to and they will retain membership in their formerly primary organization.

Steps:

  1. Click the gear icon in the upper right > click on AD Federation Services beneath Identity Management.
  2. Click edit next to the provider 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.
    1. You may choose to toggle "Exact Match" for this mapping.
  3. Select which Organization this user 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 AD Federation Services beneath Identity Management.
  2. Click edit next to the provider 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.
    1. You may choose to toggle "Exact Match" for this mapping.
  3. Select which Location this user 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 AD Federation Services beneath Identity Management.
  2. Click edit next to the provider 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.
    1. You may choose to toggle "Exact Match" for this mapping.
  3. Select which Department this user 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

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, except for the three listed above, can be deleted if needed.

Managing User Property Mappings

Steps:

  1. Click the gear icon in the upper right > click on AD Federation Services beneath Identity Management.
  2. Click edit next to the provider that you wish to set mappings for.
  3. Scroll down to the Define User Property Mapping.
  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.

 

User Imports

User imports for AD FS are accomplished via LDAP. That is, you must have an Active Directory LDAP configured for the same domain in Issuetrak in order to conduct a user import. Additionally, user imports for AD FS can only be accomplished as Scheduled Imports.

Please see the following articles for assistance with performing user imports:

 

Deactivating an AD FS Provider in Issuetrak

If at any point you wish to prevent user logins to Issuetrak from a specific AD FS 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 AD Federation Services beneath Identity Management.
  2. Click edit next to the provider that you wish to inactivate the AD FS connection to.
  3. Uncheck the box next to Active.
  4. Click Save.

Warning: After inactivating an AD FS 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.

Was this article helpful?
Thank you for your feedback!
User Icon

Thank you! Your comment has been submitted for approval.

Related Articles

 Copyright © Issuetrak, Inc. All rights reserved.