Basic authentication through HTML login forms

If your test target provides an HTML form for entering username and password, 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 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

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

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

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

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://your-page.example.com/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}}.

   

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

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 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}}.

   

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 that uses SSO or Active Directory (AD), 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 of 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:

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.

Multifactor authentication through TOTP

If your test needs to send a time-based one-time passcode (TOTP) to its test target, configure your test as follows.

Get the secret key for generating a TOTP

The secret key is a shared value which both your test target and your test’s authenticator app (such as Okta) will use to generate the same unique TOTP. You can get this secret key from:

• The test target’s QR code (an image).

• The plain-text secret key, which is visible as an embedded string in the test target’s QR code when you view the QR code as a URL string. For example, if the QR code is otpauth://totp/Slack:<username>@<somedomain>?secret=<long-string>&issuer=<app-name>&algorithm=SHA1&digits=6&period=30, the secret key is <long-string>.

Save the secret key in a global variable of type TOTP

There are two ways to create a global variable:

• From the Splunk Synthetic Monitoring landing page:

  1. From the Splunk Synthetic Monitoring landing page, select the settings icon, and then select Global variables.

  2. Select Create variable.

• From an existing test’s page:

  1. Select Edit test.

  2. Expand the Variables panel on the right, scroll to Global variables and select Add.

In the Add variable dialog box, enter the following:

1. In the Variable type pull-down menu, select TOTP.

2. In the Variable name field, enter the name of the variable. You will use this name to access your variable within a test.

3. Save the secret key either by:

   • Selecting the QR code tab and dragging the QR code image to it.

   • Selecting the Manual input tab and pasting the <long-string> you retrieved from the QR code.

4. (Optional) In the Description field, enter a description to explain the purpose of the variable for future reference. A description is particularly helpful when you conceal the variable and cannot reveal its value.

5. (Optional) Expand Advanced Settings and specify optional settings:

   • (Optional) Set digits to the number of digits in the generated TOTP. Valid values: 4-8. Default: 6.

   • (Optional) Set TOTP expiration to the the duration of the validity of the TOTP, in seconds. Valid values: 10s-90s. Default: 30s.

6. (Optional) To validate the secret key you entered, select Generate TOTP.

7. Select Add.

Configure a browser test with TOTP

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 Fill in field, and in Value, scroll down to the TOTP section (or type totp into the search field) and select the name of the TOTP variable you created. You can also enter this variable name directly as {{totp.<variable-name>}}.

   

4. 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.

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.

mTLS authentication

Mutual TLS (mTLS) authentication is a method for a client (your private or public runner) and a web server (your test target) to both validate their connection. In mTLS, both the client and the server have a certificate, and both sides authenticate using their certificate's public/private key pair. Follow these steps to make sure that the mTLS authentication succeeds:

1. Save the client certificate in a global variable of type CERT.

2. Upload the client certificate to your private runner.

3. Configure your browser, uptime, or API test to reference the CERT variable.

Save the client certificate in a global variable of type CERT

These steps assume that you've already downloaded the client certificate that matches the one on the test target.

There are two ways to create a global variable:

• From the Splunk Synthetic Monitoring landing page:

  1. From the Splunk Synthetic Monitoring landing page, select the settings icon, and then select Global variables.

  2. Select Create variable.

• From an existing test’s page:

  1. Select Edit test.

  2. Expand the Variables panel on the right, scroll to Certificates and select Add.

In the Add variable dialog box, enter the following:

1. In the Variable type pull-down menu, select CERT.

2. In the Variable name field, enter the name of the variable. You will use this name to access your variable within a test.

3. In the Domain field, enter the exact domain of the test target. For example, if the test target is client.badssl.com, set Domain to client.badssl.com. If you set Domain to badssl.com the mTLS authentication will fail with a timeout error in browser tests. The error might take up to two minutes to appear.

   You can use wildcards in Domain, such as:

   • *.example.com
   • example.*
   • *.example.*
   • *.*.*
   • *.*.*.example/*
   • *.*.*/*

4. If your client certificate is in PCKS#12 format, convert it into .pem format first.

5. Upload the client certificate using the method that matches your certificate:

   • If your certificate has separate files for its public key and private key, select the Upload Public Key tab and drag the public key file into the widget. Then select Upload Private Key and drag the private key file into the widget.

   • If your certificate is a combined file containing both its public and private keys, select the Upload Combined Key tab and drag the combined file into the widget.

6. If the combined file or private key that you uploaded in the previous step was encrypted, you must paste its decryption password into the Private key password field. Splunk Synthetics uses this password to open the file once; it does not retain your decryption password.

7. (Optional) In the Description field, enter a description to explain the purpose of the variable for future reference. A description is particularly helpful when you conceal the variable.

8. Select Add.

The client certificate is securely stored in the Splunk Synthetics database in an encrypted format.

Convert .p12 to .pem

1. Install OpenSSL on your system:

   • On Linux, it's typically pre-installed. If not, use your package manager to install it. For example, on Ubuntu, run the command apt install openssl

   • On macOS, run the command brew install openssl

   • On Windows, download the OpenSSL binary or use a package manager like Chocolatey.

2. Run the command below that matches your certificate's encryption algorithm:

   • If your certificate was encrypted with a standard (non-legacy) algorithm, run this command:

     openssl pkcs12 -in input.p12 -out output.pem -aes256 -passin pass:your-p12-password

     where:

     • input.p12 is the input PKCS#12 file.
     • output.pem is the output PEM file.
     • new-password is the password that was generated when the .p12 file was created.

     For example:

     openssl pkcs12 -in in-cert.p12 -out out-cert.pem -aes256 -passin pass:ABC123@GL

   • If you're using OpenSSL 3.0+ but your certificate was encrypted with a legacy algorithm such as RC2-40-CBC, run the openssl command with the -legacy option. This option enables support for older encryption algorithms which are deactivated by default in OpenSSL 3.0 and later:

     openssl pkcs12 -legacy -in input.p12 -out output.pem -nodes

     where:

     • input.p12 is the input PEM file.
     • output.pem is the output PEM file.

   The resulting .pem file contains both the private key and the certificate.

3. If you need to save the private key and the certificate separately, run these commands to extract them:

   • To extract the private key:

     openssl pkey -in output.pem -out private-key.pem

   • To extract the certificate:

     openssl x509 -in output.pem -out certificate.pem

Upload the client certificate to your private runner

Configure a browser test with mTLS

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

2. Scroll down to the Security section.

3. Set the TLS/SSL validation toggle to On.

4. In the Certificate pull-down menu, select the CERT global variable you created for the client certificate. For example, {{cert.Badssl_com-test2}}.

Configure an uptime (HTTP) test with mTLS

1. On the HTTP test’s configuration page, scroll down to the Security section.

2. Set the TLS/SSL validation toggle to On.

3. In the Certificate pull-down menu, select the CERT global variable you created for the client certificate. For example, {{env.est1_base64_auth}}. To see the list of all CERT variables, expand the pane on the right.

4. Select Submit.

Configure an API test with mTLS

You can add a client certificate to each API request that needs one. To do this, follow these steps:

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

2. Expand the Request section.

3. Select Add request header.

4. In the Select certificate drop-down menu, select a CERT variable you've already created. For example, {{env.est1_base64_auth}}. To see the list of all CERT variables, expand the pane on the right.

5. Select Submit.