Skip to main content

How To Configure Okta for SSO Authentication with TrackVia

  • Updated

Overview

This article provides a step-by-step guide for configuring Okta as a Single Sign-On (SSO) identity provider for TrackVia using SAML 2.0. It also covers troubleshooting steps for the most common SSO configuration errors.

Completing this configuration requires access to both your Okta administrator account and your TrackVia account settings.

Before You Begin

Confirm that your TrackVia account has a custom subdomain configured. SSO requires a custom subdomain to redirect users to your identity provider. If you are unsure whether your account has a custom subdomain, contact TrackVia Support before proceeding.

Jump to Section

Step 1: Download TrackVia's Metadata

Before configuring SSO in Okta, you need TrackVia's SAML metadata file and Service Provider Name. Both are available in TrackVia's account settings.

  1. In TrackVia, open Account Settings and navigate to the Single Sign On tab.
  2. Note the Service Provider Name value — you will need this in Step 4.
  3. Click the Download button to download TrackVia's metadata file.

TrackVia Single Sign On settings tab showing the Service Provider Name field and Download button

TrackVia Single Sign On settings — Service Provider Name and metadata Download button

Step 2: Create a New App Integration in Okta

  1. In your Okta admin console, navigate to Applications in the left sidebar.
  2. Click Create App Integration.

Okta Applications page with the Create App Integration button highlighted

Okta Applications — click Create App Integration
  1. When prompted to select a sign-in method, choose SAML 2.0.

Okta Create App Integration dialog with SAML 2.0 selected

Select SAML 2.0 as the sign-in method

Step 3: Configure General Settings

  1. Enter a name for your application (for example, TrackVia).
  2. Optionally, upload an app logo.
  3. Click Next.

Okta General Settings step with App name and App logo fields

Enter a name for the app integration

Step 4: Configure SAML Settings

Fill in the SAML settings using the values in the table below. You will need the TrackVia metadata file you downloaded in Step 1.

⚠ The Single sign-on URL value depends on your TrackVia hosting environment. Always reference your downloaded metadata file for the correct value. The standard URL for TrackVia's general environment is https://go.trackvia.com/saml/SSO.
Field Value Notes
Single sign-on URL https://go.trackvia.com/saml/SSO Reference the location attribute of the AssertionConsumerService section in your metadata file. This value differs by hosting environment.
Audience URI (SP Entity ID) TrackVia
Default RelayState Leave blank
Name ID format Unspecified
Application username Customer Dependent The value passed in the SAML assertion must match the email address of the user account in TrackVia. Choose a value that allows users to receive emails.
Update application username on Create and Update

Attribute Statements (optional) — Configure these if you plan to use Just-in-Time (JIT) Provisioning to automatically create TrackVia user accounts from Okta:

Name Name Format Value
FIRSTNAME Unspecified user.firstName
LASTNAME Unspecified user.lastName

Okta SAML settings form with Single sign-on URL, Audience URI, and Attribute Statements fields filled in

Okta SAML Settings — fill in values from the table above
  1. Click Next when all fields are complete.
  2. When prompted for feedback, select This is an internal app that we have created.
  3. Click Finish.

Step 5: Retrieve Okta's Metadata

  1. In your newly created Okta application, go to the Sign On tab.

Okta application Sign On tab

Navigate to the Sign On tab of your new Okta application
  1. Under Metadata details, copy the Metadata URL and open it in a browser. You will see XML containing the identity provider configuration.

Okta Metadata details section with the Metadata URL highlighted

Copy the Metadata URL from the Metadata details section
  1. In the XML, locate and copy the entityID value — you will paste this into TrackVia in the next step.

Okta metadata XML with the entityID value highlighted

Copy the entityID value from the metadata XML
  1. Save the entire XML page as a .xml file — you will upload this to TrackVia in the next step.

Browser save dialog for saving the Okta metadata XML file

Save the metadata XML as a file to your computer

Step 6: Configure TrackVia SSO Settings

  1. Return to the Single Sign On settings page in TrackVia.

TrackVia Single Sign On settings page

TrackVia Single Sign On settings page
  1. Paste the entityID value you copied in Step 5 into the Identity Provider Entity ID field.
  2. Upload the .xml file you saved in Step 5 using the metadata upload field.

TrackVia SSO settings showing the Identity Provider Entity ID field and metadata file upload field

Paste the entityID and upload the metadata XML file
  1. If you are using Just-in-Time Provisioning: Enter FIRSTNAME in the First Name Attribute field, LASTNAME in the Last Name Attribute field, and check the Unknown users will automatically be added to TrackVia box.
  2. Check the Enable Single Sign On option.
  3. Click Save.

TrackVia SSO settings with Enable Single Sign On checked and Save button highlighted

Enable Single Sign On and click Save to complete the configuration

SSO is now configured and ready for testing. Open your TrackVia custom subdomain in a browser to verify that users are redirected to Okta for authentication.

Troubleshooting SSO Configuration Errors

SSO errors appear in two places: as an on-screen message (for example, "User not found for this account"), or as error parameters at the end of the URL. When checking the URL, look for errorCode and errorMessage parameters appended to the address bar after a failed login attempt.

Error: User Not Found

Error code: errorCode=656&errorMessage=User%20not%20found.

Cause: The username passed in the SAML assertion does not match any existing user account in TrackVia. This typically occurs when the Okta application username format does not match the email address on file in TrackVia.

Fix:

  • Review the Application username format configured in Okta and confirm it resolves to the user's email address as it appears in TrackVia.
  • Alternatively, enable the Unknown users will automatically be added to TrackVia option in TrackVia SSO settings, and confirm that all required JIT Provisioning attributes (FIRSTNAME, LASTNAME) are configured in both Okta and TrackVia.

Error: SAML Configuration is Incorrect

Error code: errorCode=655&errorMessage=SAML%20Configuration%20is%20incorrect.

Cause: The SAML assertion was sent to the wrong URL. This typically occurs when the Single sign-on URL in Okta does not match the value from TrackVia's metadata.

Fix: Open your Okta application's SAML settings and verify that the Single sign-on URL matches the location attribute of the AssertionConsumerService section in TrackVia's metadata file. Update the value if it does not match.

Error: Failed to Decode Assertion Response

Error code: errorCode=654&errorMessage=Failed%20to%20decode%20assertion%20response.

Cause: TrackVia was unable to validate the SAML assertion. This is typically caused by a mismatch between the Identity Provider Entity ID in TrackVia and the entityID in Okta's metadata.

Fix: In TrackVia's Single Sign On settings, check the Identity Provider Entity ID field and confirm it exactly matches the entityID value from Okta's metadata XML. Update the field if there is a discrepancy, then save and re-test.

Issue: Users Cannot Initiate SSO from the TrackVia Login Page

Symptom: When users navigate to your TrackVia custom subdomain, they are prompted for a username and password instead of being redirected to Okta for SSO login.

Cause: The Enable Single Sign On setting in TrackVia is not checked.

Fix: Navigate to Account Settings > Single Sign On in TrackVia, check the Enable Single Sign On option, and click Save.

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk