Working With Secure Credentials
Last updated
Last updated
Transaction script workflows often include authentication in order to connect to secure resources such as shared folders or similar. To facilitate these scenarios in your ThousandEyes transaction tests, you can store and access login credentials, while keeping secure strings, such as passwords, hidden. With the right permission settings, you can even allow users create or update credentials, without actually being able to view the credential values themselves.
There are two ways to get credentials into the repository: add them manually, or export them from the ThousandEyes Recorder.
To manage login credentials, go to Cloud & Enterprise Agents > Test Settings > Credentials Repository tab.
To add a credential, click Add New Credential (1).
To delete a credential, hover over it in the list and click the trash icon (2). Then confirm that you want to delete this credential.
To edit a credential, click its row in the list.
The credentials you list here are available for use in transaction tests within the current account group, and do not extend to the entire organization that the account group is part of.
To view saved credentials, your account must have the View sensitive data in web transaction scripts permission. However, if you lack this permission, you can still update the credential. For general information on account permissions, see Working with Account Settings.
To use credentials from your ThousandEyes credentials repository in a transaction test, you must first enable them in the test's settings.
To enable the credentials, go to Cloud & Enterprise Agents > Test Settings > Tests tab. Open the transaction test in which you’d like to use this credential. Click the key icon and check the box next to your credential to enable it, as shown below:
In your transaction script, credential entries are accessed with the function credentials.get('credentialName'). For example, you can use this within a typeText() function like so:
await typeText(credentials.get('myPassword'), By.id('passwordId'));
An alternative to creating credentials on the platform is to create and export the credentials from the ThousandEyes Recorder IDE when you create a test from there, as described in Creating a Test From the Recorder
Typically when you record a transaction test that uses credentials, those credentials are created in the Recorder and can be exported directly to the credential repository, along with the transaction test itself.
You can disallow all users, regardless of their permissions, from accessing transaction test credentials after they have been entered into the credentials repository. By default, users with the Organization Admin or Account Admin roles can access credentials. Users with custom role definitions may also be able to do so. However, if you choose to disable credential retrieval entirely, that setting overrides any other permissions that are active for each user role.
To disallow user credential access via the Web or API, users with the Edit security & authentication settings permission (i.e., the Organization Admin user role) can navigate to Account Settings > Organization Settings > Security and Authentication > Credentials Repository and toggle Disable global credential retrieval to override the View sensitive data in web transaction scripts permission setting.
Additional notes:
This isn’t just obfuscating the password value. If you check this setting, the entire Credentials Repository tab will be inactive for all users. Users will still be able to select the credential from the Test Configuration tab on the Test Settings window when creating a transaction test, but they won’t be able to view the list, and they won’t be able to use the ThousandEyes API to retrieve credentials, either.
This action also prevents ThousandEyes support personnel from accessing user credentials.
Changes to the Disable global credential retrieval setting are logged under Account Settings > Activity Log.
Unlike all the other permissions, the Disable global credential retrieval setting is under Organization Settings rather than Users and Roles. If you don’t have permission to edit this setting, the Organization Setting screen displays this setting as Credential retrieval and isn’t editable.
Keep in mind the following guidelines when you use credentials in your transaction tests:
Create a dummy user with minimal permissions, dedicated only to transaction tests. This avoids potential interference caused by simultaneous logins.
Give each credential entry a descriptive name for easy recognition, rather than just a credential name like "test" or "testUser". This means that you’ll have to create the credential on the target system with the same descriptive name as you’d like your test credential to have. Even if the number of users editing transactions tests is small, having clear, organized credentials can be key to preserving clarity in your scripts. Note that the username doubles as the credential name.
For added security, consider also saving username strings to the credentials repository.
The ever-changing array of authentication protocols, techniques, and practices that are currently in use can be broadly classified into “something you know” like a password, “something you have” like a mobile phone, and “something you are” (biometric retina scan, voice recognition). ThousandEyes transaction tests support some of these user authentication mechanisms, including some forms of two-factor authentication (2FA), multi-factor authentication (MFA), and single sign-on (SSO).
Password
PIN
Challenge response
Software tokens via app, SMS, or email
ThousandEyes currently doesn’t support authentication that relies on physical hardware tokens, push notifications, or biometrics directly within a transaction test script.
For sample scripts illustrating different user-authentication methods, see the ThousandEyes Transaction Scripting Examples public-facing repository on GitHub.
If you have further questions about how to adapt transaction tests for the authentication mechanisms that you already have in place, contact support as described in Getting Support from ThousandEyes.
This section contains additional information on the use of credentials in ThousandEyes transaction tests.
If you have further questions on the use of secure user credentials in ThousandEyes transaction tests, contact ThousandEyes support as described in Getting Support from ThousandEyes.
The following permission settings apply to transaction tests:
Create web transaction tests. If you want to create a new transaction test, you must have this permission.
Edit tests. If you want to edit a previously created test of any type, you need separate permissions for that.
View sensitive data in web transaction scripts. Even if you can’t create transaction tests yourself, or even edit tests, you might have the ability to peek at the password for verification purposes if this permission is set. Thus, a user can create and save a test without being able to view the credential value itself.
An additional setting can be used to disable anyone from retrieving saved credentials. See Disallowing Access to the Credentials Repository on this page.
If you have permission to create tests, you’ll see a button titled Add New Test on the Cloud & Enterprise Agents > Test Settings window.
When you use the ThousandEyes Recorder to create a transaction test that includes a sign-in as part of the workflow, the Recorder obfuscates passwords, so that the actual values are never displayed or saved openly in a script. Locally, in the scripting window, the Recorder displays the password as a random string, while it stores the actual password information on the ThousandEyes platform in your Organization's private credentials repository. You can still replay the transaction in the Recorder.
On the ThousandEyes platform, the password portion of the credential is obfuscated on the Credentials Repository tab. Only users with special permissions can open a credential list item, and even then, they’ll have to click the eye icon inside the credential text box in order to view the password in plain text.
By default, the credential entry that you see on the ThousandEyes platform in the Credentials Repository is named after the login name that you used when recording the transaction script. For example, if you entered “username@gmail.com” as the username, then that is how the credential will be named as well. If the system you’re trying to test uses only the first part of an email address, then “username” would be the credential name.
As an example, suppose you use the ThousandEyes Recorder to record a browser interaction where the user manually logs into a portal as a user named “moo”, using the password “password123”.
After you hit the Stop button to stop recording in the Recorder, the Chromium browser disappears and you’ll see a line similar to this one added to the script:
This example generates a second line in the script, which might be a few lines away depending on how the login sequence is structured on the portal:
The credential shown is a dummy password, not the real one that you entered. When you click Export to ThousandEyes, the Recorder prompts you to create a test for this script. Enter a test name, time interval, and other basic information and click Create Test.
You’ll see a message that the credentials for the dummy password are not persisted. When you go to the ThousandEyes platform, reload the Cloud & Enterprise Agents > Test Settings screen to see your new test.
For this example, if you did not see the new credential in your credentials repository, you would click Add New Credential and enter “moo” as the Credential Name, and then “password123” as the Value, and make sure the credential is enabled for the transaction test that you wanted to use. See Using Credentials in a Transaction Test elsewhere on this page.
