Preparing AD Federation Service | Issuetrak Help Center

This document is a guide to configuring Active Directory Federation Services (AD FS) 2019 for use with Issuetrak.

Prerequisites

You must have the following information on hand before beginning this process:

Your Issuetrak site's Application URL
- This is found by clicking the gear icon in the upper right > click on Defaults beneath System.
- Additionally, if you intend to perform the Manual Steps below, you will need the following URLs populated with your site's Application URL in place of {site}:
  - {site}/core/login/adfs
  - {site}/core/adfs/verifypassword
  - {site}/core/adfs/testconnection
The URL to the AD FS server.

Configuring the AD FS Server

With the prerequisites, we can now configure the AD FS server to communicate with Issuetrak. This can be quickly accomplished via the PowerShell script we've included in the Issuetrak distribution OR performed manually.

Automated AD FS Server Configuration

We've created a PowerShell script to make this process quicker and easier for you.

On-premises customers can either get the script from the link above or from the Issuetrak distribution's Utilities folder.

This script is intended to be executed on the AD FS server that you will use with your Issuetrak instance. If you are curious about what the script does, please read the rest of this section, read the script in a text editor, and read the "Manual Steps" further down.

Copy the file {IssuetrakDistribution}\Utilities\New-IssuetrakADFS.ps1 to the AD FS server.
From the AD FS server, launch PowerShell ISE as an Administrator, navigate to the script's location, then execute the script.
You will be prompted to enter "SiteName". This is a friendly name for the site in AD FS. We suggest entering the name of your Issuetrak site.
You will be prompted to enter "ApplicationURL". This is found by clicking the gear icon in the upper right > click on Defaults beneath System.

The script will now display the following important information generated from the AD FS server:

Provider URL
Client ID
Client Secret

You should highlight the displayed information and copy it to a secure location. All of it is necessary to configure AD FS within Issuetrak. You will not be able to view the Client Secret again after you close PowerShell.

Are you migrating to AD Federation Services? If so, see this article for the next steps.

Is this the first time you're configuring AD Federation Services? Go here to learn how to configure Issuetrak for AD FS.

Manual Steps, Part 1: Initial AD FS Server Configuration

Open the AD FS Management Console.
Select Application Groups from the lefthand menu.
Choose Add Application Group… from the Actions menu.
Enter a name and select Server application accessing a web API under Client-Server applications. Click Next.
Copy the Client Identifier and save it for later.
Enter the three site URLs listed in the prerequisites above into the redirect URI, clicking Add after each one. Click Next.
Check Generate a shared secret, then save the secret for later. This will be needed to set up the Issuetrak site further along in the process. Click Next.
Paste in the Client Identifier into the identifier box, then click add. Click Next.
Select the access policy that fits your needs. Permit everyone will allow all users through to Issuetrak while a different policy will restrict who can attempt a login to Issuetrak. Click Next.
Under Permitted Scopes, select openId and allatclaims. Click Next.
Verify the displayed information, and then click Next to complete the main setup.

Manual Steps, Part 2: Passing Claims to Issuetrak

Issuetrak requires a number of claims to be added to allow mapping user data from Active Directory to Issuetrak users. This procedure will apply the basic claims needed for Issuetrak.

In the Application Groups section of the AD FS Management Console, select the previously set up application and then select Properties from the Actions menu.
Select the Web API, then select Edit.
Navigate to the Issuance Transform Rules tab and select Add Rule…
Select Send Claims Using a Custom Rule from the dropdown menu, then click Next.
Set the claim name to Issuetrak Required Claims.

Set the following Custom Rule.

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("Company", "Department", "DisplayName", "Email", "GivenName", "LastName", "TelephoneNumber", "StreetAddress", "SamAccountName", "City", "StateName", "PostalCode", "CountryName", "CountryCode", "distinguishedName", "memberOf", "User-Principal-Name"), query = ";company,department,displayName,mail,givenName,sn,telephoneNumber,StreetAddress,sAMAccountName,l,st,PostalCode,co,c,distinguishedName,memberOf,userPrincipalName;{0}", param = c.Value);

Add another custom rule with the following name and data:

Name: Issuetrak Optional Claims

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("Description", "Division", "EmployeeId", "EmployeeNumber", "EmployeeType", "ExtensionAttribute1", "ExtensionAttribute10", "ExtensionAttribute11", "ExtensionAttribute12", "ExtensionAttribute13", "ExtensionAttribute14", "ExtensionAttribute15", "ExtensionAttribute2", "ExtensionAttribute3", "ExtensionAttribute4", "ExtensionAttribute5", "ExtensionAttribute6", "ExtensionAttribute7", "ExtensionAttribute8", "ExtensionAttribute9", "FacsimileTelephoneNumber", "HomePhone", "HomePostalAddress", "ImportedFrom", "Info", "Initials", "IpPhone", "Language", "Mail", "Manager", "MiddleName", "Mobile", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", "Pager", "PersonalPager", "PersonalTitle", "PhysicalDeliveryOfficeName", "PostOfficeBox", "PreferredLanguage", "PrimaryInternationalIsdnNumber", "PrimaryTelexNumber", "Street", "TargetAddress", "Title", "WwwHomePage"), query = ";Description,Division,employeeID,employeeNumber,employeeType,ExtensionAttribute1,ExtensionAttribute10,ExtensionAttribute11,ExtensionAttribute12,ExtensionAttribute13,ExtensionAttribute14,ExtensionAttribute15,ExtensionAttribute2,ExtensionAttribute3,ExtensionAttribute4,ExtensionAttribute5,ExtensionAttribute6,ExtensionAttribute7,ExtensionAttribute8,ExtensionAttribute9,FacsimileTelephoneNumber,HomePhone,HomePostalAddress,ImportedFrom,Info,Initials,IpPhone,Language,mail,Manager,MiddleName,Mobile,Name,Pager,PersonalPager,PersonalTitle,PhysicalDeliveryOfficeName,PostOfficeBox,PreferredLanguage,PrimaryInternationalIsdnNumber,PrimaryTelexNumber,street,TargetAddress,title,WwwHomePage;{0}", param = c.Value);

Optional claims can be added as needed. The claims listed above are not necessarily needed and can be tailored to your needs.

To complete the configuration, click Finish > OK > OK.