Implementing SSO in Transaction Scripts

Implementing Single Sign-On (SSO) in a ThousandEyes test might require special dummy user accounts and exemptions for that dummy user, as well as bypassing or skipping some authentication steps that would normally be required of real human users.

The best approach is to ask the target website owner, or the application developer, to share the authentication policies that are currently in use. For example, is the policy ACL-based, certificate-based, or or session-based (for example, limit of 10 logins on the same account per day). You’ll need to understand the default behavior as much as possible to reduce the amount of trials.

Code examples in this section are JavaScript, for use in ThousandEyes transaction test scripts. See the ThousandEyes transaction scripting examples repository for examples and excerpts that address specific conditions, including different types of authentication.

When creating a new transaction test, you may have to try different test configurations until you find the right combination of settings that allows the test to complete successfully. Initially, you should expect the test to fail. Meanwhile look for error messages in the ThousandEyes test view in order to determine what type of authentication is actually in use on the target website.

One way to approach this development task might be:

  1. Manually open the site as a “real user” i.e., yourself. Use your browser’s Developer Tools and Console to see what is happening under the hood, knowing that you might still miss some things that are invisible even to the browser itself. See Working With Web Development Tools for guidance.

  2. Create a dummy user on the target site, with the same permissions that you want your test user persona to have. Verify with the site administrators what steps are included in the authentication process and as much as possible about back-end protocols that are in use.

  3. Create a test configuration in ThousandEyes and start implementing the test one step at a time, using the scripting suggestions below.

The instructions below assume that, for simplicity’s sake, the target website’s SSO authentication uses a Security Assertion Markup Language (SAML) generated token. It's also assumed that you are running a ThousandEyes transaction test from a ThousandEyes agent to go through the steps below. See Test Settings for Page Load and Transaction Tests for information on browser-specific test configuration options.

Step 1 Open the Target Website

The first thing your transaction script must do is open the target website. If the target website can identify the user’s organization from the URL alone (i.e., https://acme.sharepoint.com) there is nothing else you need to do. Your transaction test will be automatically redirected to the identity provider’s SAML service used on the target website.

If the target website cannot identify the user’s organization from the URL (i.e., the target website is something like https://outlook.office.com) the website will present you a form in which you need to type in your email.

Some services, for example Microsoft’s services such as Microsoft 365, will not provide the username input field. Instead they will redirect you to the Microsoft Identity Platform (login.microsoftonline.com) where you will be presented with the username input field.

Solving the username input field is not overly complex. Here is a scripting example for the Microsoft Identity Platform:

const emailElement = await driver.findElement(By.xpath(`//input[@type="email"]`));
await emailElement.clear();
await emailElement.sendKeys('primoz@thousandeyes.com');
await driver.findElement(By.xpath(`//input[@type="submit"]`)).click();

The target website will then redirect you to the identity provider/SAML provider.

Step 2 Authenticate with Identity Provider / SAML Provider

The type of response or challenge sent back to the user depends on things that you might not know when starting out.

Option 1: Interactive Login Form

When a SAML provider wants you to authenticate using the web form, this is fairly straightforward. Typically you need to put in both username and password, although, if the SAML provider is Azure AD, you might only need to put in the password.

This is an example for ADFS interactive login:

const passwordElement = await driver.findElement(By.xpath(`//input[@type="password"]`));
await passwordElement.clear();
await passwordElement.sendKeys('pa$$w00rd');
await driver.findElement(By.id(`submitButton`)).click();

Option 2: NTLM / Kerberos Authentication

First of all, you need to figure out if NTLM or Kerberos authentication protocols are used at all. How do you know that? Customers will often tell you that logging into the target service from their enterprise network “just works without any login”. That’s a good indicator.

Next, you will see an HTTP 401 error (unauthorized) in the waterfall’s Response column of the test view, when connecting to the identity provider. That means that the identity provider service has challenged you to authenticate, but the authentication failed, because either the user did not respond or the user’s credentials were invalid.

You can then inspect the header details of the 401 server response to determine which type of authentication you can use. To do this, click on the [Headers] link in the waterfall, and then click Response Headers in the Headers modal popup.

WWW-Authenticate: NTLM means you need to perform NTLM. WWW-Authenticate: Negotiate means you need to perform either NTLM or Kerberos, but you cannot say which of the two. You will need to simply first try NTLM, and then Kerberos.

In the majority of cases, only one of these headers is sent. Sometimes, however, both headers are sent, in which case the order in which they are sent can matter quite a bit. See Caveats for NTLM / Kerberos Authentication for more information.

Restricted to Specific IP Addresses

If you see HTTP 401 server responses, but they do not contain the WWW-Authenticate response header, the web server may be blocking the ThousandEyes agent's browser for some other reason; for example, because the agent's IP address is not on the server's IP allow-list.

See ​​My script works in the recorder, but fails in the platform. Why? for suggestions.

ADFS URLs Contain “wia”

When ADFS is the identity provider, you can also identify NTLM / Kerberos authentication from the URL. ADFS NTLM / Kerberos authentication is always performed on a URL containing the string “wia”:

https://example.com/adfs/ls/wia?

Notice the wia in the above URL, which stands for Windows Integrated Authentication.

If you see the wia, you definitely know that your target is using ADFS together with NTLM / Kerberos. In this case, configuring NTLM authentication is simple. Just go to the test configuration’s Advanced settings tab under HTTP Authentication, enable Basic authentication, and specify a Username and a Password.

The instruction to use the test configuration “Basic” may confuse you. When Basic is selected, the browser test will do either Basic or NTLM authentication, based on what is proposed from the server end. The browser will automatically authenticate if being challenged with HTTP Basic Authentication by the IdP service. And you will be redirected back to the target website.

If you don’t see a wia in the URL, and the server response 401 header contained WWW-Authenticate: Negotiate, you’ll still need to figure out whether to perform NTLM or Kerberos authentication.

See Caveats for NTLM / Kerberos Authentication for important TL;DR notes on NTLM / Kerberos authentication.

Option 3: OTP Using an Application

ThousandEyes supports the TOTP algorithm, but not other OTP or proprietary algorithms.

If your target uses OTP and not TOTP, you could ideally ask the target website administrators to do one of the following:

  • Exempt the dummy user account that you want to use to run the transaction test from the OTP requirement.

  • Exempt the IP addresses of the ThousandEyes Cloud and Enterprise Agents that you want to run this test from, and not to enforce the OTP requirement on requests coming from ThousandEyes agents that are performing browser synthetic testing to this target.

Alternatively, you can ask the target website or identity provider to enforce the OTP requirement using the time-based one time password (TOTP) algorithm which is predominantly available on most major application platforms from Microsoft, Google, GitHub, etc. TOTP is also supported by all OTP generator applications such as Google Authenticator and Cisco Duo.

The key here is to get access to the secret token issued when a new user account is created or when OTP is enabled for a user. Then, you can configure your transaction test script to generate a one time password each time the test is run.

Note: The following 2FA methods are not supported for OTP: phone call, hardware OTP tokens, and closed-source OTP apps. See Transaction Test SSO Support for more information.

See TOTP Examples for SSO for details and scripting examples.

Option 4: Kerberos on Non-Windows Systems

From the ThousandEyes platform, you can access Kerberos configuration by navigating to Cloud and Enterprise Agents > Agent Settings > Kerberos Settings:

  • Realm is the company container that contains one or more domains, for example thousandeyes.com.

  • Username is dependent on how it is identified in the domain controller. Use the same format of domain/user or only the user. Username is case-sensitive.

  • Password is the password associated with your dummy user account that will be used running ThousandEyes transaction tests against this target.

  • KDC Host is the host name for the Kerberos Key Distribution Center. Make sure the ThousandEyes Cloud or Enterprise Agent’s can resolve the KDC host to the correct IP.

  • KDC port is usually 88 for Kerberos.

  • Whitelist allows the ThousandEyes agent to communicate with target domains as a test destination, specifically for browser synthetics testing. You can use a specific domain or use * to allow all domains.

Step 3 Wait for the Target Website To Load

Once authenticated, you will be redirected back to the target website. You need to wait for the page to be loaded before the transaction is finished. Ideally, you will wait for an element only available on that page instead of waitForPageLoad command which can be triggered even if SSO fails.

This is an example to match the initials that work in most O365 / Sharepoint target pages (replace the initials “PS” with those of the account you used to log in):

await driver.findElement(By.xpath(`//span[text()="PS"`));

If you’ve reached this point, congratulations! You’ve successfully gotten your transaction test to authenticate. But you’re not done yet! Now you are ready to move on and finish writing your transaction test script.

Review the additional information under Browser Synthetics, particularly these pages:

PreviousTransaction Test SSO SupportNextCaveats for NTLM/Kerberos Authentication

Last updated