How to Configure Single Sign-On

For the security of your cloud-based infrastructure and the convenience of users in your organization, ThousandEyes offers login via single sign-on (SSO). ThousandEyes supports logins that are both service-provider-initiated (i.e., from the ThousandEyes login page) and identity-provider-initiated (i.e., from the customer’s IdP login). ThousandEyes supports SAML (Security Assertion Markup Language) 2.0-based SSO.

There are two steps to set up single sign-on with any identity provider (IdP):

1. The IdP configuration, done within your SSO system of choice.

2. The service provider (SP) configuration, which is done within ThousandEyes.

In general, it is better to configure your IdP first, then ThousandEyes, as the ThousandEyes setup usually requires a URL that you create and/or file that you download during IdP configuration.

You can choose to enable SSO, or to force it. Enabling SSO allows your users to choose whether to use local login or SSO. Forced SSO gives you some added confidence that your users are authenticating in a more secure way. See Enabled vs. Forced SSO for more information.

Prerequisites

Before configuring, here's what you need:

• A ThousandEyes account assigned a role with the Edit security & authentication settings permission.

• An account or subscription to the IdP of your choice.

• Information (parameter settings) for both service provider and identity provider configurations, as set out in the "Configuration Details" sections for the IdP and for ThousandEyes. This information is used in one of three ways:

  • Static configuration: each parameter must be supplied manually, including verification certificate(s).

  • Imported metadata configuration: ThousandEyes will parse a user-supplied metadata XML file and load the parameters.

  • Dynamic configuration: ThousandEyes will parse a metadata file from a provided URL on demand (for each user login).

Note: Not all IdPs offer all three options; some only offer one.

Identity Provider-Side Setup

Log in to your chosen IdP and follow the prompts to configure a new service provider (SP).

Below are links to SP configuration documentation for popular SAML 2.0-based IdPs:

• Duo

• Microsoft Azure Active Directory

• Microsoft Active Directory Federation Services

• PingOne

• Okta

• Google Workspace

• OneLogin

• miniOrange

Every IdP will have a different process for setting up SSO on their system. However, the following steps are common among the above IdPs:

1. Find and select ThousandEyes listed within the IdP’s application/SP directory.

   Some IdPs may require you to manually add the ThousandEyes application.

2. For static configuration, type in the parameter settings in the relevant fields (see IdP Configuration Details), and note down any SSO URL and Entity IDs that may be created during this process (they will be used in the SP configuration).

3. Download a verification certificate (for static configuration) or metadata file (for imported metadata configuration) to upload to ThousandEyes.

4. Configure the new SSO for your users.

   This step might happen at any point during IdP configuration, even after you have configured ThousandEyes.

IdP Configuration Details

If your IdP supports XML metadata loading, you can use our SP metadata file available at https://app.thousandeyes.com/saml-metadata.

Alternatively, you can opt for manual configuration of your IdP. The following information lists the characteristics of ThousandEyes as a SAML SP:

• ThousandEyes post callback URL: https://app.thousandeyes.com/login/sso/acs

• SAML Assertion NameID (unspecified or emailAddress format): The email address of the user to be authenticated (must be already a registered user in the ThousandEyes platform).

  • If a valid email address (as registered in ThousandEyes) is not found in the NameID field, the assertion will be parsed for additional name claims.

• Connection details:

  • Request Compression: Yes

  • Assertion: Unsigned

  • Response: Signed

  • Destination: https://app.thousandeyes.com

  • AuthnContextClassRef: PasswordProtectedTransport

  • Audience Restriction: https://app.thousandeyes.com

Note: When using static configuration, the Audience Restriction configured in your identity provider's configuration must exactly match the value set for the Service Provider Issuer field in ThousandEyes. Any mismatch, including a protocol mismatch and trailing slashes (http:// versus https://) will cause the request to be rejected.

• When using dynamic or imported metadata configurations, make sure you configure your IdP to use https://app.thousandeyes.com as the Audience Restriction.

• Recipient: https://app.thousandeyes.com

• AssertionConsumerService URL: https://app.thousandeyes.com/login/sso/acs

Key Points in ThousandEyes Assertion Validation

• ThousandEyes parses the email (our primary identifier of users) on the SamlResponse created by your IdP. We require that you configure your IdP to supply a registered user's email address in one of the following attributes of the assertion (failure to find a registered email address in any of these attributes will break the SSO process):

  • NameID in the format "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified”

  • NameID in the format "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"

  • Attribute "emailaddress"

  • Attribute "name"

  • Attribute "Email"

• Make sure that at least one of the uploaded verification certificates corresponds to the private key that signs the SAML assertion.

ThousandEyes-Side Setup

To get SSO working, you'll need the following information from your IdP:

• Login URL for your SAML provider.

• Logout URL for your SAML provider (optional).

• Identity Provider Issuer.

• Service Provider Issuer.

• Verification certificate(s).

See ThousandEyes Configuration Details for examples.

General image of SSO configuraton page with enable and forced SSO both toggled on

Enabled vs. Forced SSO

In order to successfully set up SSO in ThousandEyes, you must either enable or force SSO for your users. While enabling SSO gives your users more choice about how to log in, forcing SSO is a more consistently secure way to log in, and is recommended by ThousandEyes (see Customer Security and Privacy Responsibilities for further explanation).

To enable or force SSO:

1. Go to Manage > Account Settings > Organization Settings > Security and Authentication to view the Set Up Single Sign-On (SSO) Authentication section.

2. Toggle Enable SSO to on.

   This step allows your users to choose between logging in directly through ThousandEyes and logging in using your SSO.

3. To force SSO, you must toggle on both Enable SSO and Force SSO. You cannot force SSO without enabling it first.

Once you save changes, all users in all your organization’s account groups must thereafter use SSO to authenticate with the ThousandEyes platform. If you add new users to the platform, they will automatically be asked to log in using SSO only.

Only enabled sso toggled on, forced SSO grayed out

If during or after forcing SSO you encounter an error that means you and your users cannot log in using SSO (for example, you save your SSO configuration before the Run Single Sign-On Test has passed), you will need to:

• Raise a support ticket with us. See Getting Support from ThousandEyes for help with this process.

• Provide us with your email address to verify your identity.

User Permissions

For a user to log in using SSO, they must be assigned a role with the Login via Single Sign-On permission. As another way of restricting users to log in only via SSO, you can remove the Login via ThousandEyes login page permission. This is useful for Managed Service Providers, for example, who may not want to force SSO for all the organizations they manage.

For users with management permissions, it is not possible to remove the Login via ThousandEyes login page permission. This feature ensures that administrators cannot be prevented from logging in when they have issues with an identity provider.

ThousandEyes Configuration Details

1. Log in to ThousandEyes at https://app.thousandeyes.com.

2. Go to Manage > Account Settings > Organization Settings > Security and Authentication.

3. Turn on the Enable SSO toggle, or for added security toggle on the Force SSO option as well.

For static configuration:

1. In the Configuration Type field, select Static.

   

   Showing static tab selected
2. Fill in the fields according to the settings below.

   Field	Value
   Login Page URL	Use the URL created or displayed during your IdP configuration
   Logout Page URL	https://app.thousandeyes.com/login/sso NOTE: The Logout Page URL is optional. If used, the URL should point to the page you wish your users to see when logging out of ThousandEyes.
   Identity Provider Issuer	Often an EntityID in the form of a URL generated or displayed while setting up the IdP, for example http://www.your-IdP.com/service-provider-key
   Service Provider Issuer	https://app.thousandeyes.com IMPORTANT: Ensure that the Service Provider Issuer field matches the "service provider entityId" provided when you set up your IdP. Any mismatch, including a protocol mismatch (http:// vs https://) will cause the request to be rejected.
   Verification Certificate	Use the certificate file downloaded when you set up your IdP

3. Click Save.

For those customers who work across multiple organizations, you may need to make more than one instance for ThousandEyes in your IdP. To do this, you can define a different EntityID for each instance in your IdP by adding “/[text]” at the end of the EntityID URI. For example, you might add "/organization1" to one instance and "/organization2" to the other; the entire EntityID for the first instance would therefore read "https://www.thousandeyes.com/organization1". This value must match precisely the EntityID value in the ThousandEyes SSO configuration page by overriding the value of the Service Provider Issuer field.

For imported metadata configuration:

1. In the Configuration Type field, select Metadata File.

   

   Showing metadata tab selected
2. Click Import File.

   A new window opens, where you can browse to the metadata file you downloaded from your IdP.

   

   Showing import file window
3. Click Upload configuration file.

   The Configuration section populates with the SSO parameters, including the verification certificate.

   

   Showing populated configuration section
4. Check the Override box for Logout Page URL and clear the field.

   

   Showing override check boxes

For dynamic configuration:

1. In the Confguration Type field, select Dynamic.

   

   Showing dynamic tab selected
2. Type in the URL that you created or was displayed during your IdP configuration.

3. Click Save.

Testing SSO

Once you have configured both your IdP and ThousandEyes, you can test that your settings have worked in both places.

ThousandEyes SSO Test

1. Go to Manage > Account Settings > Organization Settings in ThousandEyes.

2. Click Run Single Sign-On Test.

3. If the SSO is configured properly, you will get a message indicating success in the section below Configuration.

   

   Showing test success

IdP SSO Test

Some IdPs allow you to test the SSO login from the site where you configured your SSO with them. For those that do, log back in to your IdP and follow the prompts to test SSO once both configurations are complete. For those that don’t, or to check SSO login in a live environment:

1. Go to https://app.thousandeyes.com.

2. For customers who have toggled on Enable SSO only:

   Click the Single sign-on link on the login page.

   

   Showing login page with SSO link
3. For customers who have toggled on Force SSO:

   The ThousandEyes login page will automatically default to SSO login.

   

   Showing SSO-only login page
4. Type in an SSO-enabled email address, and click Log in. This will redirect you to the login page of your IdP.

5. Type your username and password. You should now be logged in to ThousandEyes.

To Return to the Local Login Page

For organizations that have enabled but not forced SSO (see Enabled vs. Forced SSO), you can return to the local (ThousandEyes) login page by using this special login URL: https://app.thousandeyes.com/login?breakSso

This will return you to the non-SSO login page.

Note: When Forced SSO is toggled on, all users, including Organization Admins, cannot log in locally using the above URL. To break SSO while Forced SSO is on, you must raise a support ticket with us. See Getting Support from ThousandEyes.