Docs » Advanced test configurations » Authentication

Authentication đź”—

The following authentication methods are available for you to configure in your Synthetics tests:

Test type

Authentication method

Browser

Basic authentication through HTML login forms

Basic authentication through HTTP headers

Multifactor authentication through SMS

Multifactor authentication through email

Multifactor authentication through SSO and Active Directory

Uptime

None

API

Basic authentication through API request headers

Basic authentication through HTML login forms đź”—

Note

This authentication method applies to browser tests only.

If your test target provides an HTML form for entering username and password, configure your browser test as follows.

Screenshot showing how to set up a synthetic test with basic authentication through an API request header.

  1. Create global variables for this test target’s username and password. Best practice is to conceal the global variable you create for the password. For more information, see Global variables.

  2. On the browser test’s configuration page, select the Simple toggle.

  3. Select Edit steps or synthetic transactions.

  4. Add a step of type Fill in field, and set it up as follows:

    1. In Selector, enter the ID, name, XPath, CSS, link, or JS path of the target page’s username field. For more information on element selectors on Chrome, see Chrome DevTools .

    2. In Value, enter the name of the global variable you stored the username in, prefixed with env. and enclosed in double curly braces. For example, {{env.test1_username}}.

  5. Add a step of type Fill in field, and set it up as follows:

    1. In Selector, enter the ID of the target page’s password field.

    2. In Value, enter the name of the global variable you stored the password in, prefixed with env. and enclosed in double curly braces. For example, {{env.test1_password}}.

  6. Add a step of type Click, and set it up as follows:

    1. In Selector, enter the ID of the target page’s login button.

    2. (Optional) Set Wait for navigation** to the number of milliseconds to wait.

  7. To verify that the login succeeded, add a step of type Assert text present, and set it up as follows:

    1. In Text, enter a string that should be visible on the test target page only when login is successful.

    2. (Optional) Set Wait for up to to a large enough value, in milliseconds, to ensure that the page loads.

  8. Select Submit.

To verify that the login is working, select Try now. Results may take a while. The Try now result pane should display each screen that your test navigated to on the target page, plus the message Success.

Basic authentication through HTTP headers đź”—

Note

This authentication method applies to browser tests only.

If your test target expects login credentials to be included in an HTTP header, configure your browser test as follows.

  1. Create global variables for this test target’s username and password. Best practice is to conceal the global variable you create for the password. For more information, see Global variables.

  2. On the browser test’s configuration page, select the Advanced toggle.

  3. Scroll down to the Security section.

  4. On the row for Authentication, set values as follows:

    1. In the left field (with hint text Username), enter the username for the target page.

    2. In the right field, enter the name of the global variable in which you stored the password for this target page, prefixed with env. and enclosed in double curly braces. For example, {{env.test1_password}}. To see the list of available global variables, expand the pane on the right.

  5. On the browser test’s configuration page, select the Simple toggle.

  6. select Edit steps or synthetic transactions.

  7. Add a step of type Go to url, and in URL, enter the URL of the target’s authentication page.

  8. To verify that the login succeeded, add a step of type Assert text present, and set it up as follows:

    1. In Text, enter a string that should be visible on the test target page only when login is successful.

    2. (Optional) Set Wait for up to to a large enough value, in milliseconds, to ensure that the page loads.

  9. select Submit.

To verify that the login is working, select Try now. Results may take a while. The Try now result pane should display each screen that your test navigated to on the target page, plus the message Success.

Basic authentication through API request headers đź”—

Note

This authentication method applies to API tests only. The steps below are for targets that support “Basic auth”, in other words, API methods like curl -G https://api.twilio.com/2010-04-01/Accounts.json -u <YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN>. You can modify these steps for targets that support a bearer token.

If your test target expects login credentials to be included in an an API request header, configure your browser test as follows.

Screenshot showing how to set up a synthetic test with basic authentication through API request headers.

  1. Get the base64-encoded string of the username and password combination for your test target. There are several ways to get a base64-encoded string. For example:

    • Run the JavaScript function btoa from your browser’s console: btoa("myusername:mypassword")

    • Run this command in a Linux terminal: echo -n 'myusername:mypassword' | base64

  2. Store the base64 value in a concealed global variable. For more information, see Global variables.

  3. On the API test’s configuration page, select an existing request in the test or select Add requests.

  4. Expand the Request section, and enter the following information:

    1. In URL, enter the test target’s URL.

    2. Select Add request header.

    3. Select the Authorization header, and for its value, enter the word Basic followed by a space and then the name of the global variable containing your base64-encoded combined username and password. The variable must be prefixed with env. and enclosed in double curly braces. For example, {{env.est1_base64_auth}}. To see the list of available global variables, expand the pane on the right.

  5. Select Submit.

To verify that the login is working, select Try now. Results may take a while. The Try now result pane should display each screen that your test navigated to on the target page, plus the message Success.

Multifactor authentication through SMS đź”—

Note

This authentication method applies to browser tests only.

If your test target sends a one time passcode (OTP) through SMS for multifactor authentication, your browser test must retrieve the OTP from the SMS message and enter it into the input field on the target’s page. To do this, configure your browser test as follows.

Prerequisites đź”—

  • Virtual phone number

    To authenticate through SMS, you must have a virtual phone number that can receive one time passcodes through SMS. Several services offer virtual phone numbers and provide SMS content through an API, such as the Sinch service . For instructions on receiving messages through this service, see the Sinch API .

    Certain services, such as Twilio, may block incoming SMS messages containing OTPs. For more information, see Twilio’s OTP Message Body Filtered documentation.

  • SMS notifications

    To enhance the authorization process, you must have a service that sends SMS notifications, such as GitHub .

Limitations đź”—

Some services may not be accessible during Synthetics tests due to violations of Content-Security-Policy (CSP). In such instances, a workaround is to implement third-party services on your server and provide an endpoint configured with CSP to allow connect-src.

  1. On the browser test’s configuration page, select the Simple toggle.

  2. Select Edit steps or synthetic transactions.

  3. Add a step of type Go to url, and in URL, enter the URL of the target’s authentication page.

  4. Add a step of type Save return value from JavaScript, and in the code field, paste the following JavaScript. This script retrieves data from a specified URL using XMLHttpRequest and extracts the OTP from that data. You configure your test to save this OTP in a global variable named otp.

    Note

    In the script, set the variable url to the URL of your own virtual phone number’s SMS service.

    function getOtp() {
  const url = "https://api.alfa.smartlook.cloud/sms";
  var request = new XMLHttpRequest();
  request.open("GET", url, false);
  request.send();
  if (request.status == 200) {
    return parseOtp(JSON.parse(request.responseText));
  }
return;
}

function parseOtp(jsonResponse) {
  const firstInbound = jsonResponse.inbounds[0];
  if (firstInbound && firstInbound.body) {
    // Extract the number using a regular expression
    const match = firstInbound.body.match(/\\b\\d{6}\\b/);
    if (match) {
      return match[0]; // Return the first matched number
    }
   }
   return;
}
return getOtp();

  5. Add a step of type Wait, and specify a wait time in milliseconds. This time needs to be long enough for the target to send the OTP code to your virtual phone number, and for your JavaScript to process the OTP.

  6. Add a step of type Fill in field, and set it up as follows:

    1. In Selector, enter the ID of the element on the target page where the user must enter the OTP.

    2. In Value, enter the name of the custom variable your JavaScript stored the OTP in, prefixed with custom. and enclosed in double curly braces. For example, {{custom.otp}}.

    Screenshot showing the

  7. To verify that the login succeeded, add a step of type Assert text present, and set it up as follows:

    1. In Text, enter a string that should be visible on the test target page only when login is successful.

    2. (Optional) Set Wait for up to to a large enough value, in milliseconds, to ensure that the page loads.

  8. Select Submit.

To verify that the login is working, select Try now. Results may take a while. The Try now result pane should display each screen that your test navigated to on the target page, plus the message Success.

Multifactor authentication through email đź”—

Note

This authentication method applies to browser tests only.

If your test target sends a one-time passcode (OTP) through email for multifactor authentication, your browser test must retrieve the OTP from the email message and enter it into the input field on the target’s page. To do this, configure your browser test as follows.

Prerequisites đź”—

You must have an email service that supports connecting to your email account and managing your emails through an API. The steps below feature an example using the Nylas service . For detailed information on how to retrieve messages from this service, refer to its API documentation .

Additionally, the steps below demonstrate the use of GitHub to send an authorization email, which is essential for extracting the OTP from it.

Limitations đź”—

Your email service must be accessible through an API. Some services may not be accessible during Synthetics tests due to violations of Content-Security-Policy (CSP). In such instances, a workaround is to implement third-party services on your server and provide an endpoint configured with CSP to allow connect-src.

  1. On the browser test’s configuration page, select the Simple toggle.

  2. Select Edit steps or synthetic transactions.

  3. Add a step of type Go to url, and in URL, enter the URL of the target’s authentication page.

  4. Add a step of type Save return value from JavaScript, and in the code field, paste the following JavaScript. This script retrieves data from a specified URL using XMLHttpRequest and extracts the OTP from that data. You configure your test to save this OTP in a custom variable named otp.

    Note

    In the script, set the variable url to the URL of your own email inbox API endpoint.

    Note

    If you are utilizing the Nylas service, you can locate unread emails by searching for specific text in the subject line or other parameters. For more information, please refer to the Nylas API documentation for messages .

    function getOtp() {
  const grantId = "<NYLAS_GRANT_ID>";
  const jwToken = "<NYLAS_API_KEY>";
  const from = "noreply@github.com";
  const subject = "Your GitHub launch code";
  const unread = "true";
  const url = "https://api.us.nylas.com/v3/grants/" + grantId + "/messages?limit=1&unread=" + unread + "from=" + from + "&subject=" + subject;
  var request = new XMLHttpRequest();
  request.open("GET", url, false);
  request.setRequestHeader('Authorization', 'Bearer ' + jwToken)
  request.send();
  if (request.status == 200) {
    return parseOtp(JSON.parse(request.responseText));
  }
  return "ERR";
}

function parseOtp(jsonResponse) {
  const firstInbound = jsonResponse. data[0];
  if (firstInbound && firstInbound.snippet) {
    // Extract the number using a regular expression
    const match = firstInbound.snippet.match(/\\b\\d{8}\\b/);
    if (match) {
      return match[0]; // Return the first matched number
    }
  }
  return "NO-OTP";
}
return getOtp();

  5. Add a step of type Wait, and specify a wait time in milliseconds. This time needs to be long enough for the target to send the OTP code to your email service, and for your JavaScript to process the OTP.

  6. Add a step of type Fill in field, and set it up as follows:

    1. In :guilabel:Selec`tor, enter the ID of the element on the target page where the user must enter the OTP.

    2. In Value, enter the name of the custom variable your JavaScript stored the OTP in, prefixed with custom. and enclosed in double curly braces. For example, {{custom.otp}}.

  7. To verify that the login succeeded, add a step of type Assert text present, and set it up as follows:

    1. In Text, enter a string that should be visible on the test target page only when login is successful.

    2. (Optional) Set Wait for up to to a large enough value, in milliseconds, to ensure that the page loads.

  8. Select Submit.

To verify that the login is working, select Try now. Results may take a while. The Try now result pane should display each screen that your test navigated to on the target page, plus the message Success.

Multifactor authentication through SSO and Active Directory đź”—

Authentication through Single Sign-On (SSO) is similar to basic authentication. To create a test of that uses SSO or Active Directory (AD) login, you must configure a series of steps that include opening the webpage, selecting the SSO authentication link, and entering the required information for SSO authentication. Additional webpages may load during this process, so it’s crucial that you include steps to confirm that all the components of each webpage have fully loaded before proceeding.

SSO authentication frequently involves additional authentication factors. If the identity provider (such as Google, Microsoft, Okta, Duo, and so on) does not mandate an extra login factor, your test might only need the authentication steps that are illustrated in the example below:

Screenshot showing steps to create in a synthetic test that authenicates with SSO or Active Directory.

Limitations đź”—

Identity providers often require various additional factors for login, such as verification via email, SMS, or TOTP. In such cases, it is essential to modify or add steps to accommodate these additional login factors.

This page was last updated on Feb 04, 2025.