Overview
This articles provides a step-by-step guide for configuring Okta SSO authentication with TrackVia, as well as troubleshooting tips for the most common errors that may be encountered with SSO configuration and how to resolve them.
Before You Begin
Confirm your account has a custom subdomain configured.
Step 1: Pulling TrackVia's Metadata
- Before configuring SSO in Okta, you’ll need TrackVia’s metadata and Service Provider Name. Both pieces of information are found under the “Single Sign On” tab of your account settings (see the red boxes in the screenshot below).
- Download the metadata by clicking the “Download” button (see green arrow in screenshot below).
Step 2: Create a New App Integration
- In your Okta instance, navigate to the applications area (red box on lefthand side of screenshot below) and select “Create App Integration” (blue button highlighted by red box in screenshot below).
- Select “SAML 2.0” for your sign-in method (see red box in screenshot below).
Step 3: General Settings
- Name your application and optionally provide an image (see red boxes in screenshot below).
Step 4: Configuring SAML
- Fill out the fields using your TrackVia metadata and the table below.
- Attribute statements will be used if you plan to use Okta to provision users using Just in Time Provisioning. After this is configured, click “Next” at the bottom right.
| Field | Value | Notes |
| Single sign-on URL | Reference your metadata file for the “location” attribute of the AssertionConsumerService section. The value for TrackVia’s general environment is: https://go.trackvia.com/saml/SSO |
This value will be different depending on your hosting environment. |
| Audience URI (SP Entity ID) | TrackVia | |
| Default RelayState | Leave blank | |
| Name ID format | Unspecified | |
| Application username | Customer Dependent |
The value here depends on your Okta configuration. The value passed in the SAML assertion must match the email address of the user account in TrackVia. The value chosen should allow users to receive emails. |
| Update application username on | Create and Update | |
| Attribute Statements (optional) | ||
| Name | Name format | Value |
| FIRSTNAME | Unspecified | user.firstName |
| LASTNAME | Unspecified | user.lastName |
- When prompted for feedback, you can select “This is an internal app that we have created”. Click the finish button.
Step 5: Retrieve Okta's Metadata
- To retrieve Okta’s metadata, go to the “Sign On” tab of your new application.
- Under the “Metadata details” section, copy the Metadata URL and go to the website. You will see XML with all the required information.
- Copy the “entityID” value for later (see red box in screenshot below). Save this webpage as a .xml file.
Step 6: Configuring TrackVia
- Return to the Single Sign On page of your TrackVia Application.
- Paste the entityID into the “Identity Provider Entity ID” field (see red box in screenshot below) and upload the xml file you saved earlier (see blue box in screenshot below).
- If you’re using Just In Time Provisioning, put “FIRSTNAME” in the “First Name Attribute” and “LASTNAME” in the “Last Name Attribute” fields and check the "Unknown user will automatically be added to TrackVia” box.
- Check the “Enable Single Sign On” option (see red box in screenshot below) and Click “Save” (see red arrow in screenshot below).
SSO is now live and ready for testing!
Troubleshooting Okta SSO Configuration Errors
Errors in an SSO configuration appear in a few places. Some errors will display a message on screen (like “User not found for this account”), while others will require looking in the URL. At the end of your URL, you will find an error code and error message.
A collection of errors, causes, and corrections is below.
User Not Found
🚫ERROR:
errorCode=656&errorMessage=User%20not%20found.
❗CAUSE:
- This error appears when a SAML assertion is directed to the incorrect URL.
🛠️FIX:
- Review the configured username in the identity provider and confirm it matches an existing user, or
- Turn on “Unknown users will be automatically added to TrackVia” and ensure that all the required attributes are set up both in TrackVia and the identity provider.
SAML Configuration is Incorrect
🚫ERROR:
errorCode=655&errorMessage=SAML%20Configuration%20is%20incorrect.
❗CAUSE:
- This error appears when a SAML assertion is directed to the incorrect URL.
🛠️FIX:
- Review and update the “Single Sign On URL” in the identity provider.
Failed to Decode Assertion Response
🚫ERROR:
errorCode=654&errorMessage=Failed%20to%20decode%20assertion%20response.
❗CAUSE:
- This appears when TrackVia is unable to correctly respond to a SAML assertion.
🛠️FIX:
- Check the “Identity Provider Entity ID” configuration in TrackVia. Update it to the correct entity id from the identity provider.
Users cannot initiate Single Sign On From TrackVia
🚫PROBLEM:
- To initiate a Single Sign On attempt from TrackVia, users go to the configured customer subdomain.
- They are then automatically redirected to your identity provider to complete the log in using SSO. Users may report going to the custom subdomain and being prompted for a password.
🛠️FIX:
- Ensure the “Enable Single Sign On” setting is checked on the Single Sing On setting page.
Comments
0 comments
Please sign in to leave a comment.