Credential vault for synthetic monitors

The credential vault is a centralized repository where you securely store and manage all synthetic monitoring credentials (username/password pairs, certificates, or tokens) for browser as well as HTTP monitors.

The credential vault is accessible from the navigation menu at Settings > Web and mobile monitoring > Credential vault.

Credential security

Credentials are stored in Advanced Encryption Standard–encrypted form (AES-256). Access to the data is encrypted using TLS 1.2. This means that the content of credentials in the vault are not visible to any user, including the creator; they are visible only to the synthetic monitors that reference them. Credential content can be overwritten by users who have access to the credential vault.

Access to the credential vault

To view and write to the credential vault, a user must have the Change monitoring settings environment-level permission.

If you do not have this permission:

  • You cannot access the credential vault from global settings.
  • You cannot create a credential (as shown below) when creating/editing a browser monitor in script or UI mode. No permission to create credentials

However, users who do not have access to the vault can still:

  • Create credentials from within HTTP monitors and store the credentials to the vault.
  • Capture credentials as part of a recorded clickpath, with the option to store the credentials to the vault.
  • Use/insert available credentials in synthetic monitors.

Users with access to the vault can access it via a link from synthetic monitors.

Access credential vault from a synthetic monitor

Note
Saving changes to synthetic monitors requires the Change monitoring settings permission at the environment or management-zone level.

See Credential vault API below for the token scope required to access the credential vault via API.

Owner-only versus public credentials

Each credential is access controlled for use in synthetic monitors. When a credential is initially created (in the vault or in the course of synthetic monitor creation or editing), it's designated as Owner only. The owner/creator may choose to change a credential's permissions in the vault to All. Other users with access to the credential vault can change a credential's access level by becoming the new owner of the credential and overwriting it with new authentication details (see Create credentials in the vault and Credential permissions below).

Whether a credential is "owner only" or "public" determines who can use it in a synthetic monitor. An "owner-only" credential is one that only the credential owner can use to create or edit a synthetic monitor. A "public" credential is available to all users to create or edit a synthetic monitor. Read more below in Credential permissions.

View the credential vault

You can see all credentials created in your environment in the credential vault— go to Settings > Web and mobile monitoring > Credential vault. The available credential types are username/password pairs, certificates, and tokens.

Each credential is listed with an icon identifying the Type, Name, Owner, Access level, and controls to edit and Delete it.

Filter the list by Type, Name, Owner, or Access.

Credential vault

You can see the ID and properties of a credential, but the sensitive information is available only for overwriting. The content of credentials are visible only to the synthetic monitors referencing them.

If you are not the owner of a credential, you'll see a message about using or overwriting the credential. See Who can edit or overwrite a credential below.

Credential properties

Select HTTP or Browser next to a credential to see the associated monitors on the Synthetic monitors page. The list is automatically filtered by the credential name and the credential owner.

Synthetic monitors filtered for credentials

Create credentials in the vault

Credentials can be created directly in the vault or in the course of synthetic monitor creation and editing. (See Synthetic Monitoring for creating and using credentials during monitor creation.)

You can create these types of credentials:

Username and password pairs

Username and password pairs can be used for basic as well as web form authentication, in single-URL browser monitors, browser clickpaths, and HTTP monitors.

To create login credentials in the vault

  1. Select Add new credential at the top right.
  2. Select User and password as the Credential type.
  3. Enter the Username and Password. The password is automatically masked as you type.
  4. Provide a Credential name and optional Description.
  5. Credentials are set to Owner access only by default. Disable this control to make the credential public. Read more below in Credential permissions.
  6. Save your credential. Note that, once created, the contents of credentials are no longer visible to anyone; they can only be overwritten.

Create a username and password pair in the vault

Certificate credentials

Certificate credentials are used in HTTP monitors—you can add a client certificate to an HTTP request.

To create a certificate credential in the vault

  1. Select Add new credential at the top right.

  2. Select Certificate as the Credential type.

  3. Upload a Certificate file. Allowed file formats are PFX, P12, and PEM.

    Note
    If you run into issues with using a PEM certificate, see Convert PEM certificates below.

  4. Provide a Credential name and optional Description.

  5. Credentials are set to Owner access only by default. Disable this control to make the credential public. Read more below in Credential permissions.

  6. Save your credential. Note that, once created, the contents of credentials are no longer visible to anyone; they can only be overwritten.

Create a certificate credential

Convert PEM certificates

If you run into issues when creating a certificate credential using the PEM certificate, consider converting the certificate file to P12 or PFX formats, which are endorsed for Java standards.

Use the openssl command-line utility to convert the certificate file. For example, the following command converts a PEM certificate to the P12 format.

openssl pkcs12 -export -in /path/to/certificate.pem -out /path/to/certificate.p12

Token credentials

A token is a generic credential type with a single value. You can create tokens in the credential vault and insert references to them from HTTP monitors, in request URLs, HTTP header values, and in the request body. In clickpaths, you can insert a token ID in the Keystroke event.

To create a token credential in the credential vault

  1. Select Add new credential at the top right.
  2. Select Token as the Credential type.
  3. Enter a Token value.
  4. Provide a Credential name and optional Description.
  5. Credentials are set to Owner access only by default. Disable this control to make the credential public. Read more below in Credential permissions.
  6. Save your credential. Note that, once created, the contents of credentials are no longer visible to anyone; they can only be overwritten.

Create a token credential

Credential permissions

Whether a credential is designated "owner only" or "public" determines who can use the credential to:

Users with access to the credential vault can delete/overwrite credentials and change credential access levels.

Who can use a credential with a monitor

When creating a synthetic monitor or when editing an existing monitor that does not have associated credentials, you can:

  • Use an existing credential stored in the vault in the monitor—you can only select public credentials or owner-only credentials that you've created. These credentials are available in drop-down lists in synthetic monitor fields where they can be inserted.

  • Create a new credential as part of the monitor creation/editing workflow. The credential is automatically designated as "owner only" and stored in the vault. Following monitor creation, users with access to the credential vault can then change the access level of the credential to "public."

    Note
    Users can create UID/password and certificate credentials in HTTP monitors even if they don't have permissions to access the credential vault in global settings.

  • You have the option to store passwords captured in recorded clickpaths to the vault (with a companion username or as a single-value token). These are stored as "owner only." Alternatively, you can edit the recorded event to use an existing credential from the vault or create one of your own. See how to use the Keystroke event.

Who can edit a monitor that has an associated credential

  • If a monitor is associated with a public credential, anyone on your team can enable/disable, edit, or save any changes to the monitor.
  • If a browser monitor (clickpath or single URL) is associated with an owner-only credential, any user can make changes to certain fields, even if they don't have access to the credential used. You can edit monitor frequency, locations, outage alerting, performance thresholds, metrics, connected applications, validation, and HTTP status codes that are to be ignored. And, of course, you can change a token or user ID/password credential—you'll need to change all credentials in the monitor to ones that you have access to. Controls that you cannot edit such as the URL, adding or deleting clickpath events, data entry in Keystroke, and Advanced setup in monitor settings are grayed out or display an error message when you attempt to save changes in either script or UI mode.
  • If an HTTP monitor is associated with an owner-only credential, any user can make changes to certain fields, even if they don't have access to the credential used. You can edit monitor frequency, locations, add or change the order of requests, post-execution scripts, validation, and, of course, change a certificate or a UID/password pair. Fields that you cannot edit such as the request URL, HTTP method, pre-execution script, additional HTTP headers, request body, and the follow redirects option are grayed out or display an error message when you attempt to save changes in either script or UI mode.
  • To enable/disable a synthetic monitor that's secured by another user's owner-only credentials, you must provide a credential that you have permission to use.

If you're unable to edit a monitor that has an associated credential, you can search for the owner of the credential to discuss changes or request access.

Who can edit or overwrite a credential

The content of credentials are visible only to the synthetic monitors referencing them. You can see the ID and properties of a credential, but the sensitive information is available only for overwriting.

Users with access to the credential vault can take over ownership and overwrite, delete, or change the access level of a credential (whether "public" or "owner only").

Select Overwrite credential or Overwrite certificate to provide new contents. You can also enable/disable Owner access only.

Overwrite a credential

  • Credential owners can change authentication details and/or access level of a credential.
  • If you are not the owner of a credential:
    • You see a cautionary message about using or overwriting the credential.
    • You become the new owner of a credential if you overwrite it. You may want to notify the previous owner in this case.
    • You can change a credential's access level only by overwriting it completely with new authentication details and becoming the new owner.

You can delete credentials—if you delete a credential that's being used in a monitor, that monitor is disabled.

Delete a credential

How to search for the owner of a credential

The credential vault displays all credentials in your environment with owner name and access level. You can sort and filter credentials by Owner in the credential vault.

You can search for credential owners in the Synthetic monitors page. You can filter for monitors using a specific credential (Associated credential) and/or the credential owners (Associated credential owner). Note that these filters are only available when at least one credential from the vault is used in a monitor. The filters show you all the credentials (and their owners) currently used in monitors, regardless of whether the credentials are "public" or "owner access only."

Synthetic monitor filters for credentials

When you open a monitor using an owner-only credential, the owner's name is highlighted in the script event or HTTP requests.

Credential owner name in HTTP monitor

Credential vault API

You can access the credential vault by API, which lets you integrate it with external credential storage systems. This lends itself to a vast range of automation use cases.

  • Reading the credential vault requires the Read credential vault entries API token scope. You can also use the broader Read configuration token scope.
  • Writing to the credential vault requires the Write credential vault entries API token scope. You can also use the broader Write configuration token scope. Note that write scopes do not include read scopes, which must be granted separately (see above).
  • Updating synthetic monitors via API requires the Create and read synthetic monitors, locations, and nodes API token scope.
  • If you use the API to edit or update a monitor with a credential, the API token should be owned by someone who has access to the credentials assigned to the monitor.

Read more about token scopes in the API authentication help page.

Best practices for credentials

  • We recommend that you use dedicated test credentials for synthetic monitors.
  • When editing a synthetic monitor with credentials, make sure the person who created the monitor can still access it. Make your credentials public or else your changes may need to be replaced by someone else’s. If many people modify a script, it's better to make the associated credential public.
  • If you overwrite a credential, notify the previous owner. If you delete a credential, notify the owner.
  • If you use the API to edit or update a monitor with a credential, the API token should be owned by someone who has access to the credentials assigned to the monitor.
  • Whenever possible, use the narrow API token scopes limiting read and write access just to the credential vault.