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.
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.
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.
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.
Supported username formats
- Browser monitors:
<username>
and<domain>\<username>
- HTTP monitors:
<username>
- NTLM authentication in browser and HTTP monitors:
<username>
- Browser monitors:
-
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.
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.
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:
- Create a new synthetic monitor or associate an existing monitor with a credential.
- Edit a monitor that has an associated credential.
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.
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.