Single Sign-On

TrackJS supports Single Sign-On (SSO) via SAML 2.0. We support both “Service Provider” (SP) initiated and “Identity Provider” (IdP) initated login flows. There are no additional fees required to configure and begin using our SSO functionality.

Configuring SSO

Please follow the steps below to configure TrackJS and your identity provider.

1. Obtain an Organization ID

To begin the SSO configuration process, please email us at hello@trackjs.com. We will enable SSO for your account and provide you with an Organization ID. This is a unique key in our system which will identify your SAML assertion requests and also allow your users to login via our Single Sign-On login UI (if you’re using SP-initiated flows).

2. Visit TrackJS SSO Account Settings

Once you have received your Organization ID from us, you can navigate to your Account Settings page and look for the Single Sign On section:

There are several fields which may be important depending on your use case and identity provider.

  1. Your organization ID is displayed in a read-only textbox. This is necessary if you want to use SP-initiated login flows (more below).
  2. The Assertion Consumer Service URL (sometimes abbreviated ACS or called a SAML consumer service URL). This will be required by your identity provider. SAML assertions are sent to this URL, and it’s important that your organization ID is on the query string.
  3. This value is sometimes required by identity providers to further restrict access, but it’s also the SP-initated login flow URL.
  4. Once you’ve created the application/login configuration for TrackJS in your identity provider, you’ll paste the public metadata URL in this box so we can finish wiring things up.

3. Create the TrackJS Application in Your Identity Provider

The steps to configure your identity provider will vary, but in the most general case you’ll usually create an “application” within your identity provider called TrackJS. You can add and remove users from this application to control access to TrackJS. While the specifics will depend on the provider, there are a few common things that should be noted:

  • Ensure you are using SAML 2.0 for the application
  • Use email address as the username identifier, not an opaque ID or Active Directory username
  • You will need to paste the TrackJS Assertion Consumer Service URL (#2 in the screenshot above) somewhere in your identity provider.
  • Once configured in the identity provider, you will need to find the metadata URL for your application.

4. Finish SSO Configuration

Once you’ve configured your identity provider, the last step is to paste the metadata URL from your identity provider in to the TrackJS account settings page and click Save. We will automatically retrieve the redirect URI and X509 certificate from the metadata endpoint and save it for your account.

Your account settings will now look like this:

There are several changes you may notice.

  1. The identity provider metadata URL is now stored in the textbox, but can be changed if necessary.
  2. We will automatically process the identity provider’s redirect URL and security certificate from the metadata URL. These are displayed in read-only text boxes but are useful for debugging purposes.

Converting Existing Users

The final step is to convert any existing TrackJS user(s) to have access controlled via your identity provider. Once your configuration is complete we will convert an existing account for testing. After you’ve confirmed the integration is working, we will convert any other existing users. This is a process that must be done on the back-end currently, so please email us at hello@trackjs.com and we will take care of it.

New Users Are Automatically Provisioned

Once you’ve configured SSO, you do not need to invite new users to TrackJS. You can simply add them to the TrackJS application in your identity provider and they will be automatically provisioned the first time they login. Only previously existing users with access controlled via password need to be manually converted.

Identity Provider vs. Service Provider Initiated Login

Most identity providers have some way to log you in directly to TrackJS from the identity provider’s site. This is accomplished by sending a SAML assertion directly to TrackJS. This is commonly called IdP-initiated login. We fully support this and generally recommend it if it’s available.

If your identity provider does not support this mechanism or you’d prefer to use our UI to route the authentication attempt to your identity, you can login directly through our UI with your Organization ID. There is a link to the SSO login screen on the TrackJS homepage, but you can also directly access it here.

Currently Supported Identity Providers

  • Okta
  • OneLogin
  • Azure AD
  • Google
  • Auth0
  • Many others

The vast majority of authentication solutions that support SAML 2.0 will work with TrackJS. If you have specific questions about it please reach out to us!