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. See Create credentials in the vault to see which credential types can be used in browser monitors or HTTP monitors and how.

The credential vault is accessible from the Dynatrace menu at Manage > Credential vault.

External vault integration

Username-password credentials can be synchronized with external vault systems such as Azure Key Vault and HashiCorp Vault—read about how to set up synchronization in External vault integration.

Credential security

Credentials are stored in Advanced Encryption Standard–encrypted form (AES-256) in the credential vault. Access to the data is encrypted using TLS 1.3. The contents 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.

Credential vault security architecture and communication

The credential vault is developed entirely by Dynatrace and resides on the Dynatrace Cluster. See the key components involved in credential vault security and communication below. All communication among key components is encrypted.

Dynatrace Cluster

Function: The Dynatrace Cluster hosts the credential vault in the Cluster database as part of your Dynatrace monitoring environment.

Credential access and security: All credentials are created, changed, and deleted on the Cluster. The credential vault is environment specific and is not shared across environments. Only the Cluster has access to the credential vault and resolves credential IDs to actual values when preparing monitors for execution.

Communication: All communication among key components is encrypted. If a monitor needs to be executed from a private Synthetic location, the Cluster resolves and sends credentials as part of the monitor configuration to the Synthetic engine on creation and update (when monitors or referenced credentials are created or updated), not before every execution. In the same way, if a monitor needs to be executed from a public Synthetic location, the Cluster resolves and sends credentials as part of the monitor configuration to the public Synthetic infrastructure on creation or update.
Synthetic engine

Function: The Synthetic engine executes synthetic monitors on both private and public Synthetic locations and has access to monitor configurations and any resolved credentials in order to do so.

Communication: The Synthetic engine does not communicate directly with the credential vault or see its contents. On private Synthetic locations, the Synthetic engine requests and retrieves the schedule of monitors to be executed and their configurations (with resolved credentials) from the Cluster on creation or update, that is, when monitors or referenced credentials are created or updated. On public Synthetic locations, this same communication takes place with the public Synthetic infrastructure. All communication among key components is encrypted.

Credential access and security: The Synthetic engine has access only to those resolved credentials that are part of the monitors it needs to execute; it cannot retrieve or view any other credentials. All monitor configurations are stored in Synthetic engine memory (with no persistence layers involved) for as long as the monitors need to be executed. If a monitor is disabled or deleted, its configuration is flushed from Synthetic engine memory.

All credential data is exchanged via internal API secured with API token, and access is highly restricted at the network-protocol level. Each individual monitor execution is isolated; no memory or scripts are shared among executions.
Public Synthetic infrastructure

Function: This includes all infrastructure required to execute monitors from public locations. The public Synthetic infrastructure stores and communicates information to public Synthetic locations for the execution of synthetic monitors.

Communication: If a monitor needs to be executed from a public Synthetic location, the Cluster sends the monitor configuration (with resolved credentials) to the public Synthetic infrastructure on creation or update (when monitors or referenced credentials are created or updated), not before every execution. The public Synthetic infrastructure then serves the same information to public Synthetic locations as the Cluster does to private Synthetic locations. All communication among key components is encrypted.

Credential access and security: Monitor configurations with resolved credentials are encrypted and persisted in the Synthetic database. Credentials aren't persisted directly as credentials but only as part of monitor configurations.

The entire public Synthetic infrastructure and public Synthetic locations are managed and secured by Dynatrace. Access is only possible from within the Dynatrace corporate network and is secured by SSH key-based authentication. Access to private keys is limited only to a small group of Dynatrace employees.

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.

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 browser clickpath, with the option to store the credentials to the vault.
Use/insert available credentials in synthetic monitors.

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

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 when creating or editing synthetic monitors), it's designated as Owner only. The owner/creator may 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).

The access level of a credential ("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 for synthetic monitoring are username-password pairs, certificates, and tokens. Username-password pairs can be synchronized with external vault systems—read more in External vault integration.

Each credential is listed with an icon identifying the Type, Name, the monitors it's Used by, Owner, Access level, Scope (Synthetic Monitoring or Extensions 2.0), and controls to edit and Delete it.

You can filter the list by Type, Name, Access, or Owner, or Scope (select Synthetic).

You can see the ID and properties of a credential, but credential content cannot be viewed; it can only be overwritten. The contents of credentials are visible only to the synthetic monitors referencing them.

If you're 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.

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

optional Enable local playback of Synthetic browser monitors without entering credentials so that your users can play back browser monitors locally without having to enter any associated credentials that they have access to. If disabled, the user needs to enter any associated credentials, public or owner only, in order to play back browser monitors locally. In effect, this means that only users with access to the credentials in a browser monitors can play it back.

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 for synthetic monitoring:

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.

Username-password pairs in the Dynatrace credential vault can be synchronized with an external vault (Azure Key Vault or HashiCorp Vault). Synthetic monitors containing these credentials use the synchronized values obtained from the external vaults—read more in External vault integration.

To create login credentials in the vault

Select Add new credential in the upper-right corner.
Select User and password as the Credential type. (The Credential scope is automatically set to Synthetic.)
Edit the default Credential name to properly identify your new credential.
If synchronizing this username-password pair with an external vault (Synchronization with external vault), follow instructions in External vault integration.
Enter the Username and Password. The password is automatically masked as you type. Note that these fields do not appear for synchronized credentials.
Note
Supported username formats
- Browser monitors: <username> and <domain>\<username>
- HTTP monitors: <username>
- NTLM authentication in browser and HTTP monitors: <username>
optional Provide a Description.
Credentials are set to Owner access only by default. Disable this switch to make the credential public. Read more below in Credential permissions.
Save your credential. Note that, once created, the contents of credentials are no longer visible to anyone; they can only be overwritten.

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

Select Add new credential in the upper-right corner.
Select Certificate as the Credential type. (The Credential scope is automatically set to Synthetic.)
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.
Enter the Certificate password.
Provide a Credential name and optional Description.
Credentials are set to Owner access only by default. Disable this switch to make the credential public. Read more below in Credential permissions.
Save your credential. Note that, once created, the contents of credentials are no longer visible to anyone; they can only be overwritten.

Convert PEM certificates

If you run into issues when creating a credential using a PEM certificate, consider converting the certificate file to the 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.

bash
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

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

Credential permissions

The access level of a credential (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 monitor or editing an existing monitor that doesn't 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 lists in the 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 credential creation, any user with access to the credential vault can change a credential's access level by becoming the new owner and overwriting it with new authentication details.

Note
Users can create UID/password and certificate credentials in HTTP monitors even if they don't have permissions to access the credential vault from 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. This operation does not require permission to access the credential vault. See how to use the Keystroke event.

Alternatively, you can edit the recorded event to use an existing credential from the vault (does not require permission to access the credential vault) or create one of your own from within the clickpath (requires permission to access the credential vault).

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, delete, or edit 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 name, device emulation settings, wait conditions, frequency, locations, outage alerting, performance thresholds, metrics, connected applications, validation, and HTTP status codes 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. Note that replacing another user's owner-only credential with one you have access to is irreversible.

Controls that you cannot edit such as the URL, enabling/disabling HTTP authentication, 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, whether in 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 name, locations, validation, thresholds, and, of course, change a certificate or a UID/password pair. You can edit and change the credentials in a URL, header value, or request body. You'll need to change all credentials in the monitor to ones that you have access to. Note that replacing another user's owner-only credential with one you have access to is irreversible.

Controls that you cannot edit such as the request URL, HTTP method, pre-execution script, post-execution script, HTTP headers, request body, the follow redirects option, and adding/deleting HTTP requests are grayed out or display an error message when you attempt to save changes, whether in script or UI mode.

You can enable/disable or delete a synthetic monitor that's secured by another user's owner-only credentials.

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

Who can edit or overwrite a credential

The contents of credentials are visible only to the synthetic monitors referencing them. You can see the ID and properties of a credential in the vault, but the credential content can only be overwritten.

Users with access to the credential vault can overwrite a credential, and, thereby, take over ownership. In the course of overwriting (or anytime after), they can then also change the access level of the credential (whether public or owner only).

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

In order to overwrite a credential, you must provide the full set of authentication details. This means that you can only overwrite a credential (and take ownership) by providing a new username and password set, a new certificate, or a new token. In the case of username-password pairs, if you leave the password blank, the old password value is not retained.

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

Users with access to the credential vault can delete credentials—if you delete a credential that's used in a monitor, that monitor will be disabled.

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

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

Credential vault API

You can access the credential vault by API, which 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 Documentation topic.

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 might need to be replaced by someone else’s. If many people need to modify a monitor, it's better to make the associated credential public.
If the account of a credential owner no longer exists in your system, the execution of associated synthetic monitors is not affected; the monitors will be executed as before. However, we recommend that the credential be overwritten by another user, making them the new owner. Without doing so, you will not be able to use owner-only credentials in new monitors, or edit existing monitors that use owner-only credentials.
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 to just the credential vault.