About OAuth / OpenID Connect

Open Authorization (OAuth) and OpenID Connect (OIDC) are both widely-used standards for identity management and authentication.  Issuetrak provides the ability to authenticate via these standards, which we will refer to as OAuth 2.0 / OIDC.  What this means is that you can use third-party authentication providers that support OAuth 2.0 / OIDC to sign into Issuetrak via (for example) a "Sign in with Google" button on your instance's login page.

Issuetrak provides configuration presets for three major providers:

  1. Google
  2. OKTA
  3. One Login

A fourth option labeled "Custom" is is also available, which allows you to add any standards-compliant provider that is not listed. 

This article explains how to enable Identity Management, as well as configure Google, OKTA, and One Login to authenticate with Issuetrak. 

Initial account creation and configuration of these third-party services is beyond the scope of this article


Activate Identity Management

Before you can use any of the third-party authentication options, you must activate the Identity Management Module.

  1. Click the gear icon in the upper right > click Features beneath System.
  2. Select Enable authenticating users with third party identity providers in the Identity Management section.
  3. (Optional) Select Allow single sign on functionality.
  4. (Optional) Select Update existing users on login. This will check for and update the user each time they log into Issuetrak.
  5. Click Update to save the new settings.

Google

This section provides steps for making Google's identity management services work with your instance of Issuetrak.

Google Configuration
  1. Navigate to Google's Cloud Platform interface.
  2. From the lefthand menu, select IAM & Admin, then click Create a Project.
    1. You'll be prompted to set a Project Name.  We would suggest naming this something distinctive and descriptive, such as "Issuetrak Auth".
    2. You can also set which organization you want this project to work with.  Select the organization that you want to be able to authenticate with Issuetrak. 
    3. Click Create.
  3. From the lefthand menu, select APIs & Services, then click OAuth consent screen
    1. Read the information provided onscreen and decide whether Internal or External is best for your organization.  If you're unsure, we would suggest selecting Internal.  Click Create after you make your selection.
    2. Fill in the App Name and User support email fields.  App name should be something descriptive such as "Issuetrak Testing Instance".
    3. Optional: Fill in the fields listed under App Domain
    4. Under Authorized Domains, enter the domain of the organization that you want to authenticate with Issuetrak.  
    5. Enter a valid address for Google to send notifications to about the status of this registration.
    6. Click Add or Remove Scopes.  Check the first 3 scopes on the list:
      1. .../auth/userinfo.email
      2. .../auth/userinfo.profile
      3. openid
    7. Click Update at the bottom of the browser.
    8. Click Save and Continue at the bottom of the browser.
  4. From the lefthand menu, select APIs & Services, then click Credentials.
  5. Click Create Credentials > OAuth client ID.
    1. Select "Web Application" from the Application Type dropdown.
    2. Enter a name for this client ID. 
    3. Under Authorized Redirect URIs, click "Add URI" and then add the following URIs separately, where IssuetrakSite is your Issuetrak instance's publicly accessible address:
      1. https://IssuetrakSite/core/adfs/verifyPassword
      2. https://IssuetrakSite/core/adfs/testconnection
      3. https://IssuetrakSite/core/login/adfs
    4. Click Create.
  6. Take note of the Client ID and Client Secret provided in the "OAuth Client Created" pop-up.  You will need both of them in the next section. 

Now we're ready to configure Issuetrak.


Issuetrak Configuration
  1. Click the gear icon in the upper right > click OAuth 2.0 / OIDC beneath Identity Management
  2. Click Add Provider beneath "OAuth 2.0 / OIDC" on the righthand menu.
  3. Select "Google" from the Provider Template dropdown.  This will populate the Discovery URL and Scopes fields. 
  4. Enter the Provider Name.  For example purposes, we will enter "Google".
  5. Enter the Domain that you want to be able to authenticate via Google with Issuetrak.   
  6. Copy and paste the Client ID and Client Secret that Google provided in the previous steps above. 
  7. Set the Button Label
  8. Optional:  Set custom colors for each aspect of the button.
  9. Click Save
  10. Click Test Connection.  You will be prompted to sign in or select a Google account to authenticate this Issuetrak instance to your project.  If this succeeds, then you will see "Successfully Authenticated" at the top of the screen, along with a list of claims and values provided by Google about the account you authenticated with. 

You're almost ready to continue from here!  You will need to set some user mappings before you can attempt to sign in via this authentication provider.


OKTA

This section provides steps for making OKTA's identity management services work with your instance of Issuetrak.

OKTA Configuration
  1. Navigate the OKTA's configuration interface.
  2. Along the lefthand menu, click Applications > Applications
  3. Choose Create App Integration
  4. Select OIDC - OpenID Connect, then Web Application.  Click Next.
  5. Set the "App Integration Name".  We recommend that you make this descriptive, such as "Issuetrak Testing Instance". 
  6. For Sign-In Redirect URIs, add the following URIs separately, where IssuetrakSite is your Issuetrak instance's publicly accessible address:
    1. https://IssuetrakSite/core/adfs/verifyPassword
    2. https://IssuetrakSite/core/adfs/testconnection
    3. https://IssuetrakSite/core/login/adfs
  7. In Assignments, read the available options and determine the best option that will suit your organization's needs.
  8. Click Save.
  9. Take note of the Client ID and Client Secret provided on the next screen.  You will need both of them in the next section. 

Now we're ready to configure Issuetrak.


Issuetrak Configuration
  1. Click the gear icon in the upper right > click OAuth 2.0 / OIDC beneath Identity Management
  2. Click Add Provider beneath "OAuth 2.0 / OIDC" on the righthand menu.
  3. Select "OKTA" from the Provider Template dropdown.  This will populate the Discovery URL and Scopes fields. 
  4. Copy and paste the Client ID and Client Secret that OKTA provided in the previous steps above. 
  5. Set the Button Label
  6. Click Save.
  7. Click Test Connection.  You will be prompted to sign in or select an account to authenticate this Issuetrak instance to your provider.  If this succeeds, then you will see "Successfully Authenticated" at the top of the screen, along with a list of claims and values provided by Google about the account you authenticated with. 

You're almost ready to continue from here!  You will need to set some user mappings before you can attempt to sign in via this authentication provider. 


OneLogin

This section provides steps for making OneLogin's identity management services work with your instance of Issuetrak.

OneLogin Configuration
  1. Navigate to OneLogin's administration portal (this varies according to the domain you have with them). 
  2. From the top menu, choose Applications > Applications
  3. In the upper right corner, click Add App
    1. In the Search field, type "oidc" and then select "OpenIdConnect (OIDC)" from the search results. 
    2. Set the display name to "Issuetrak Auth" (or any friendly name for this that you wish). 
    3. Click Save.
  4. From the lefthand menu, choose Configuration.
  5. Make the following entries in the Redirect URI's field where IssuetrakSite is your Issuetrak instance's publicly accessible address:
    1. https://IssuetrakSite/core/adfs/verifyPassword
    2. https://IssuetrakSite/core/adfs/testconnection
    3. https://IssuetrakSite/core/login/adfs
  6. Click Save.
  7. From the lefthand menu, click SSO.
  8. Take note of the Client ID, Client Secret and Issuer URL here.  You will need them for the next section. 
  9. Scroll down to Token Endpoint and set the "Authentication Method" dropdown to "POST". 
  10. Click Save.

Now we're ready to configure Issuetrak.


Issuetrak Configuration
  1. Click the gear icon in the upper right > click OAuth 2.0 / OIDC beneath Identity Management
  2. Click Add Provider beneath "OAuth 2.0 / OIDC" on the righthand menu.
  3. Select "OneLogin" from the Provider Template dropdown.  This will populate the Discovery URL and Scopes fields. 
  4. You will need to update the Discovery URL to match the Issuer URL provided by OneLogin in the previous steps.
  5. Copy and paste the Client ID and Client Secret that OneLogin provided in the previous steps above. 
  6. Set the Button Label
  7. Click Save.
  8. Click Test Connection.  You will be prompted to sign in or select an account to authenticate this Issuetrak instance to your provider.  If this succeeds, then you will see "Successfully Authenticated" at the top of the screen, along with a list of claims and values provided by Google about the account you authenticated with. 

You're almost ready to continue from here!  You will need to set some user mappings before you can attempt to sign in via this authentication provider. 


Creating User Mappings

The final step to configuring OAuth 2.0 / OIDC 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 OAuth 2.0 / OIDC 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 OAuth 2.0 / OIDC 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 OAuth 2.0 / OIDC 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 OAuth 2.0 / OIDC 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

Four claims are mandatory and automatically mapped to fields for each user. They are mapped as follows:

  • preferred_username -> User Id
  • given_name -> First Name
  • family_name -> Last Name
  • email -> Email

Any other available 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 OAuth 2.0 / OIDC 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' 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.