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 button 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.
    5. A Notifications popup will appear and once the project creation is complete, click on the Select Project option that is shown.
  3. Click the icon with three horizontal lines in the upper left corner, select APIs & Services, then click OAuth consent screen.
    1. Click Get started.
    2. Enter an App name and select a User support email.
    3. Click Next.
    4. 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.
    5. Click Next.
    6. Enter an email address in the Contact Information field and click Next.
    7. Check the box to agree to the Google API Services: User Data Policy and click Continue.
    8. Click Create.
    9. If you selected External above, click Audience on the left > click Publish app > click Confirm.
  4. Click Data Access on the right
    1. Click Add or Remove Scopes. Check the first 3 scopes on the list:
      1. .../auth/userinfo.email
      2. .../auth/userinfo.profile
      3. openid
    2. Click Update at the bottom of the browser.
    3. Click Save at the bottom of the browser.
  5. Click Clients in the left menu.
  6. Click + Create Client.
    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.
  7. You will be provided with your Client ID and Client Secret. You will need this information to configure Issuetrak in the next section. You can choose to copy/paste these values into your own credential management framework or download the JSON to a safe location for reference later.

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: By default, 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.

If your OKTA tenant includes the "API Access Management" feature, it is possible to either modify an existing Authorization Server or create a Custom Authorization Server. This will allow you to edit the Claims for the authorization server to force the first name, last name, and group memberships to be sent to Issuetrak.

  1. While logged into your Okta tenant as an admin, click Security > API in the left menu.
  2. If you are not using an existing Authorization Server and would like to use that one, click the name to edit it.
    1. If you are using the existing servers for other applications, it would likely be best to create a new one for Issuetrak. Click the + Add Authorization Server button.
    2. Enter a descriptive name to indicate what the server is used for (like "Issuetrak OAuth").
    3. Enter api://default in the Audience field.
    4. Click Save.
  3. Click the Claims tab.
  4. Click the + Add Claim button.
  5. Enter first_name in the Name field.
  6. Next to Include in token type, select ID Token and Always.
  7. The Value Type should be set to Expression.
  8. In the Value field enter: appuser.given_name
  9. Click Create.
  10. Click the + Add Claim button.
  11. Enter last_name in the Name field.
  12. Next to Include in token type, select ID Token and Always.
  13. The Value Type should be set to Expression.
  14. In the Value field enter: appuser.family_name
  15. Click Create.
  16. Click the + Add Claim button.
  17. Enter groups in the Name field.
  18. Next to Include in token type, select ID Token and Always.
  19. Select Groups for the Value Type.
  20. In the Filter field, select Matches regex and enter .* in the field next to that.
  21. Click Create.

Note: You will need to map the "first_name" and "last_name" fields returned from OKTA accordingly 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 "OpenId Connect (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.
    1. You may choose to toggle "Exact Match" for this mapping.
  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.
    1. You may choose to toggle "Exact Match" for this mapping.
  3. Select which Organization this claim should be mapped to upon a successful match.
  4. Click Save.
Mapping Locations (optional)

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.
    1. You may choose to toggle "Exact Match" for this mapping.
  3. Select which Location this claim should be mapped to upon a successful match.
  4. Click Save.
Mapping Departments (optional)

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.
    1. You may choose to toggle "Exact Match" for this mapping.
  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:

Claim Name User Field Can Modify? Can Delete?
preferred_username User ID No No
given_name First Name Yes No
family_name Last Name Yes No
email Email Yes Yes

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, by default, 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

If your OKTA tenant has the "API Access Management" feature and you chose to perform the additional steps in the OKTA section above, you can modify the default mappings for the First Name and Last Name fields to use the claims added in those steps (first_name and last_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.