How to Configure Single Sign-On (SSO)
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):
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.
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.
- 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.
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:
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.
Alternatively, you can opt for manual configuration of your IdP. The following information lists the characteristics of ThousandEyes as a SAML SP:
- 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.
- 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.
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).
General image of SSO configuraton page with enable and forced SSO both toggled on
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 Account Settings > Organization Settings > Security and Authentication, then scroll to 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:
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.
- 2.Go to 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.
- 1.In the Configuration Type field, select Static.Showing static tab selected
- 2.Fill in the fields according to the settings below.
- 3.Click Save.
- 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
- 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.
Once you have configured both your IdP and ThousandEyes, you can test that your settings have worked in both places.
- 1.Go to 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
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:
- 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.
This will return you to the non-SSO login page.