About Active Directory Federation Services (AD FS)

Information

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 Active Directory add-on. If you would like to purchase support for AD, please get in touch with your Account Manager.


Comparison: AD vs AD Federation Services

Here is a comparison between the two authentication methods with respect to Issuetrak.

Capability Active Directory AD Federation Services
Uses LDAP Yes No
Uses OAUTH No Yes
Can bulk import users Yes No
Supports Multifactor Authentication (MFA) No Yes
Needs service account Yes No
Single Sign-On Yes, for On-Premises only Yes
Can map AD user attributes to Issuetrak user account UDFs Yes, but limited to only certain attributes Yes, can map any claim to any user text UDF
Secures Domain-Disabled User Accounts Yes, inactivates user account Yes, prevents sign-in
User Mappings Based On... AD OU or Group AD FS Claim


Preparing the AD FS Server

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


Activating AD FS in Issuetrak

Once your AD FS server is ready to work with Issuetrak, you should activate AD FS in Issuetrak. Activating AD FS is the same process as activating AD.

Steps:

  1. Sign into Issuetrak with a Sys Admin account.
  2. Navigate to Administration > System > System Settings > Features.
  3. Check the box next to "Integrate/Authenticate users with Active Directory".
  4. Click Update.

Adding an AD Federation Services Provider

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

Steps:

  1. Navigate to your Issuetrak site and log in with a Sys Admin account.
  2. If you are not currently using Active Directory with Issuetrak, then go ahead and enable the Active Directory Module.
  3. Navigate to Administration > Identity Management.
  4. Choose AD Federation Services from the lefthand menu.
  5. Choose Add from the lefthand menu.
  6. Populate the following data:
    1. Provider Name: A friendly name for the AD FS server.
    2. Domain: The Domain of the AD FS server.
    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 Name: The name of the button to display on the Issuetrak Login page.
  7. Click Save to save the settings.  You will be redirected to the Edit AD Federation Services Provider page.
  8. 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.
  9. Add mappings for Template and Organization. Users that do not match a valid Template and Organization mapping will not be able to log in. See the section "Creating User Mappings for AD FS" below for more information on this.

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.


Mapping User Templates

Steps:

  1. Sign into Issuetrak with a Sys Admin account.
  2. Navigate to Administration > Identity Management > AD Federation Services.
  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. Navigate to Administration > Identity Management > AD Federation Services.
  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. Navigate to Administration > Identity Management > AD Federation Services.
  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. Navigate to Administration > Identity Management > AD Federation Services.
  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. Navigate to Administration > Identity Management > AD Federation Services.
  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 Mappings

The only way to test mappings is to authenticate to Issuetrak with AD FS, then look at the resulting user account's properties.  Therefore, it is recommended for customers to test mappings by creating a 'dummy' AD account that has the same mappings as the target user(s), then authenticate that user to Issuetrak to check the mappings.