SAML JIT Provisioning

SAML (Security Assertion Markup Language) just-in-time (JIT) provisioning offers SAML’s traditional authentication standard to verify who’s trying to log in. Importantly, it also creates users in a service provider (in this case, ThousandEyes), who may not have been provisioned (given authorized access) through any other method yet. This is called just-in-time provisioning because it does not require any user list to be pre-loaded into the system before authentication can happen, but provisions (authorizes) them on the spot.

SAML JIT provisioning, by its nature, overrides any previous user record, as it freshly provisions a user every time they log in. This means that if your organization previously used SCIM, or any other method to provision users, and switches to SAML JIT provisioning, SAML JIT will override any previous user records, and will continue to do so with every login. This helps to keep user records up-to-date.

Who SAML JIT Provisioning Is For

Anyone can use SAML JIT provisioning but it is best leveraged by organizations who have a large user base, have users in many and varied roles or account groups, and who need the flexibility to define different permissions for different roles across different account groups. Large organizations with a shifting workforce (e.g. seasonal workers) or with large customer support centers might fit this bill, for example.

Prerequisites

Before configuring, here's what you need:

A ThousandEyes account assigned a role with the following permissions:
- Edit security & authentication settings
- Edit users in all account groups
- View security & authentication settings
- View all account groups settings OR View agents in account group OR View all users
- View roles OR View all users
An account or subscription to the IdP (identity provider) of your choice.
SSO authentication enabled. See How to Configure Single Sign-On (SSO) for instructions on implementing SSO.

When you enable SAML JIT provisioning, you must also switch the Enable SSO toggle to “on” in the Single Sign On (SSO) section within Manage > Account Settings > Organization Settings > Security and Authentication if not already done so. You may switch the Force SSO toggle on and off, but you cannot disable SSO entirely while using SAML JIT provisioning.

If not already done so, you must configure your SSO settings first before configuring your SAML JIT settings.

You must also assert role information from your IdP alongside identity information.

When SSO and SAML JIT provisioning are enabled and configured correctly in ThousandEyes, there are two ways to initiate provisioning and login for first-time users of ThousandEyes.

IdP-initiated. This method works for any new user.
a. Log in to your IdP first; this verifies the credentials you need to log in to ThousandEyes.
b. “Launch” ThousandEyes from your IdP; this sends the IdP’s SAML assertion to ThousandEyes, which we then validate, provision you, and grant you an active session.
Automatic SP-initiated. This method is ideal for partners or multi-service providers (MSPs), for example, to smooth the process for their customers, who can click the pre-filled link and automatically be redirected to their IdP for authentication into ThousandEyes.
a. Type or paste https://app.thousandeyes.com/login/sso?fwd=/account/switch/<AID>&idp=<IdpIssuer> into your browser.
b. Replace <AID> with your ThousandEyes account group ID, which can be found via the List account groups API call, and replace <IdpIssuer> with the Identity Provider Issuer URL found within your SSO Configuration panel. (These are likely to be pre-filled for you by, for example, your partner or MSP.)
c. When you hit Enter, we will redirect you to login/authenticate with your IdP.
d. Your IdP will then redirect you back to ThousandEyes, having been validated, provisioned and logged in.

Once you have been provisioned the first time into ThousandEyes, you can re-enter ThousandEyes through the above user-flows, or you can provide your email address into the ThousandEyes login screen directly. If you are not already authenticated with your IdP, we will redirect you to your IdP to authenticate, and your IdP will send you back to ThousandEyes, re-provisioned and logged in.

Role Mapping

SAML JIT provisioning relies on the mapping of roles within your IdP to roles within ThousandEyes. There are typically three parts to setting up this mapping:

If not already done so, setting up relevant attributes and roles within your IdP.
- You can also use attributes and roles that you have already set up in your IdP.
Setting up equivalent roles in ThousandEyes.
Linking the two sets of roles.

Creating Attributes and Roles in Your IdP and ThousandEyes (Steps 1 and 2)

While different IdPs might allow you to group individuals in different ways (some may use the term “group”, some “role”, some a combination), the common thread across all IdPs is the idea of grouping. Your aim is to decide which group(s) of individuals you want to have access to ThousandEyes and distinguish those groups through an overarching attribute.

An attribute is like the key in a key:value pair – it defines the range of allowable values for that data type. Examples of attributes might include “cost center” or “department”, which defines a grouping and possibly even a location of employees. For an attribute like “department”, the roles (or values) could include “IT”, “account management”, and “call center”. You may only define one attribute whose roles map to ThousandEyes roles.

The above IdP roles might easily map to ThousandEyes’ three built-in roles: Organization Admin, Account Admin, and Regular User, as they have respectively restrictive permission sets that reflect the account access needs of each type of user. However, the role names in your IdP and those in ThousandEyes must match exactly. A role name of “IT” in your IdP will not be able to map to the role name of “Organization Admin” in ThousandEyes.

SAML JIT provisioning requires role designations in both your IdP and ThousandEyes because SAML JIT provisioning requires a step to authorize your users (differentiating it from SAML SSO which only authenticates them). Authorization implies a specific set of permissions. In ThousandEyes, permissions are attached to a role.

Therefore, you must, if you have not already done so:

Define in your IdP one attribute for everyone who needs access to ThousandEyes.
Define in your IdP the different roles for your users within your defined attribute.
Replicate in ThousandEyes those exact role names and apply the relevant permissions to each role. See Creating a Custom Role and Built-In Roles for more about how to create new, or clone current, roles.

You can name the attribute and roles in your IdP anything you like. They must, however, be replicated exactly in ThousandEyes, which is sensitive to case, spacing and special characters.

Linking Your IdP and ThousandEyes Roles (Step 3)

Once you have set up SSO in ThousandEyes and created matching roles within your IdP and ThousandEyes, you’re ready to link them.

Go to Manage > Account Settings > Organization Settings > Security and Authentication.
Scroll to User Provisioning > SAML Justi-In-Time Settings.
Switch the Enable toggle on.
- Note: As SAML JIT overwrites provisioning at every login, we do not recommend using SAML JIT and SCIM provisioning at the same time.
Select the SAML Role Name Attribute you want to map across.
- If the role name attribute is not listed in the dropdown, choose “Custom…” to type in a new role name attribute.
In the Role dropdown, choose a role you want to add.
In the Account Groups dropdown, check all the account groups you want your role to have access to.
Click the “+ Add mapping” or “-“ buttons to add or remove as many roles/account groups as you need.

Every organization should have at least one person with the equivalent of the ThousandEyes Organization Admin role – often, the first registered user gets this role by default. This role contains all the management permissions and SAML JIT permissions that enables the organization to continue to manage its users and the SAML JIT feature. Deleting the mapping for the Organization Admin role, or its equivalent, can prevent users from accessing the permissions needed to do these vital management tasks. We recommend not deleting the mapping for any role containing the management and SAML JIT permissions unless there is another role available with the same permissions.

Click Save.

Editing SAML JIT Settings

Once you have successfully set up your SAML JIT provisioning, you can edit your settings at any time.

Return to to Manage > Account Settings > Organization Settings > Security and Authentication > User Provisioning > SAML Just-In-Time Settings.
To change attributes, select or type in a new attribute name.
To change roles, choose a new role from the dropdown. (Hint: you must first have created a new role within Manage > Account Settings > User and Roles > Roles before it will appear in the dropdown.)
To change the number of account groups your roles have access to, check or uncheck the relevant account groups in the Account Groups dropdown.
Click Save.

Removing SAML JIT Settings

To stop using SAML JIT provisioning, slide the Enable toggle to the left to disable it. All your settings remain in place, but are simply disabled.

Troubleshooting SAML JIT

Often, trouble logging in through SAML JIT provisioning is caused by a configuration error in either the SAML JIT or SSO sections of the ThousandEyes platform. We list below the most common errors.

SAML JIT or SSO not enabled. If no new users can log in with either of the methods outlined in First Login, check that both SSO and SAML JIT provisioning are Enabled.
IdP Issuer or SP Issuer don’t match. If both toggles are enabled as per error #1, above, check in the ThousandEyes SSO configuration that the Identity Provider Issuer exactly matches your IdP’s Entity ID and that the Service Provider Issuer exactly matches the “service provider entityId” that you set up in your IdP. The SAML response assertion that ThousandEyes receives after you authenticate with your IdP contains these fields. Any error will cause authentication to fail in ThousandEyes.
Role names don’t match. The SAML response assertion also contains the attribute name and role for the user. If the attribute name or role in ThousandEyes does not exactly match those of the IdP, authentication will fail.
No email address. The email address of the user is also passed through the SAML response assertion. In most cases, this is passed via the NameID assertion. However, if it is not passed through this assertion, it must be assigned to an attribute that contains the email address of the user, such as emailAddress, name or Email. The authentication will fail if an email address cannot be found somewhere within the response body. If you’re uncertain how to check the response body, email support@thousandeyes.com.