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 OneLogin 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. Click the icon with three horizontal lines in the upper left corner, 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. Click the icon with three horizontal lines in the upper left corner, 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 APIs & Services menu on the left 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 to OKTA's administration portal (this varies according to the domain you have with them).
  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.
  10. In the lefthand menu, click Security > API.
  11. You should be taken to the Authorization Servers tab (if this is included in your OKTA license).
    • If you do not see the Authorization Servers tab, then you will be using OKTA's default authorization server, take note of the below Discovery URL (replacing ${yourOktaOrg} with your OKTA domain and skip Steps 12-13.
      • https://${yourOktaOrg}/.well-known/openid-configuration
  12. On the Authorization Servers tab, identify which Authorization Server you wish to use and click on the name of that Authorization Server.
  13. Take note of the Metadata URI, you will need this as the Discovery URL in the next section.

Note: The token returned from OKTA to Issuetrak will only include what is called a "thin" token by OKTA. This token will only contain a very limited number of fields instead of the full profile details. The only user fields that are returned by OKTA are Email and Full Name. Due to this, the Firstname, Lastname, and Display name in Issuetrak for the user will all show the user's email address by default. It is recommended to map the "name" field returned from OKTA as the user's Display Name in Issuetrak using the steps below in the User Property Mapping 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 and Client Secret. You will need them for the next section.
  9. Right-click Well-known Configuration next to the Issuer URL and select Open link in new tab.
  10. Switch to the new tab that opened and take note of the full URL in the browser's address bar. You will need this as the Discovery URL in the next section as well.
  11. Switch back to the tab where you are adding the App in the OneLogin Admin console.
  12. Scroll down to Token Endpoint and set the "Authentication Method" dropdown to "Basic". 
  13. Click Save.

You should confirm that the new App has been added for the appropriate Users, Groups, or Roles in your OneLogin admin portal.

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 the Discovery URL, Auth URL, Token URL and Scopes fields will populate automatically.
    • If you selected OKTA or OneLogin, populate the Discovery URL that you gathered in the previous section and click Apply. The Auth URL and Token URL should populate at that point. If they do not, verify the Discovery URL is correct.
    • If you selected Custom, only the Scopes field will be pre-populated. You will need to populate the Discovery URL manually at a minimum and press Apply, but you may also need to manually populate the Auth URL and Token URL with the appropriate value from your OAuth 2.0 / OIDC provider if they do not automatically populate after clicking Apply next to the Discovery URL.
  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.

Some OAuth 2.0 / OIDC providers (like OKTA) will only provide limited profile information from the user. If the "given_name" and "family_name" claims listed above are not returned, the First and Last name fields for the user in Issuetrak will be populated with their email address. If there is a field returned from the provider containing the full name of the user that can be mapped to the "Display Name" field in Issuetrak.

For example, OKTA will only return the Email and Name fields for the user. So, you could add the below user property mapping to use the "Name" field provided by OKTA as the Display Name in Issuetrak:

  • name > Display Name
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 that customers 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.