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.

Before proceeding you will need to Activate the Identity Management Module in your Issuetrak site.

 

Google

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

  1. Navigate to Google's Cloud Platform interface.
  2. From the lefthand menu, select IAM & Admin, then click Create a Project.
    1. If you have existing Projects, you will be taken to one of those projects by default and will not see the Create Project link. To create a new project you will need to click the drop-down in the top bar with the existing Project Name and click New Project in the pop-up.
    2. You'll be prompted to set a Project Name. We would suggest naming this something distinctive and descriptive, such as "Issuetrak Auth".
    3. 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.
    4. Click Create.
  3. From the lefthand menu, select APIs & Services, then click OAuth consent screen.
    1. Verify that the drop-down in the top bar shows the new Project name. If it does not, click the Project Name and select the new project that was just created.
    2. 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.
    3. Fill in the App Name and User support email fields. App name should be something descriptive such as "Issuetrak Testing Instance".
    4. Optional: Fill in the fields listed under App Domain.
    5. Under Authorized Domains, enter the domain of the organization that you want to authenticate with Issuetrak.
    6. Enter a valid address in the Developer contact information field for Google to send notifications to about the status of this registration.
    7. Click Save and Continue.
    8. Click Add or Remove Scopes.  Check the first 3 scopes on the list:
      1. .../auth/userinfo.email
      2. .../auth/userinfo.profile
      3. openid
    9. Click Update at the bottom of the browser.
    10. 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.

 

OKTA

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

  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.

 

OneLogin

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

  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

Steps:

  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. If you are connecting to Google, OKTA, or OneLogin select that option for Provider Template, otherwise select Custom.
    • If you selected Google, OKTA, or OneLogin the Discovery URL, Auth URL, Token URL and Scopes fields will populate automatically.
    • If you selected Custom, only the Scopes field will be pre-populated. You will need to populate the Discovery URL, Auth URL, and Token URL manually with the appropriate value from your OAuth 2.0 / OIDC provider.
  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 this OAuth 2.0 / OIDC provider with Issuetrak.   
  6. Copy and paste the Client ID and Client Secret that you gathered when creating the API application in your OAuth 2.0 / OIDC provider. 
  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 an 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 your provider 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.

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.