External vault integration

Synthetic Monitoring username-password and token credentials in the Dynatrace credential vault can be synchronized with an external vault—Azure Key Vault or HashiCorp Vault. Synchronized credentials contain the keys of external key-value pairs that hold the required values.

When you set up synchronized username-password or token credentials in the vault, Dynatrace automatically creates HTTP monitors specifically for the purpose of synchronization. You can also use the api.saveCredential() or api.saveToken() methods in pre-and post-execution scripts to create your own synchronization monitors.

Autocreated synchronization monitors are named with the credential ID of the synchronized credential and are executed hourly by default from the Amazon US East (N. Virgina) public Synthetic location. Note that the request and response bodies and headers are automatically hidden from execution details (Analyze execution details).

Other synthetic monitors can call and use these synchronized credentials for testing API endpoints and websites. The monitors that call these credentials use the synchronized values obtained from the external vaults. Synchronization frequency determines how often these credentials are rotated within the synthetic monitors that use them for testing purposes.

Azure Key Vault

Username-password or token credentials for use in synthetic monitors can be synchronized with Azure Key Vault key-value pairs containing the username, password, or token value.

Prerequisites

Before setting up synchronized credentials with Azure Key Vault, you need to define the required client (application) ID and client secret as token credentials stored in the Dynatrace credential vault. We recommend naming such prerequisite tokens so they're easily identified as companion credentials for synchronization. If your vault doesn't contain any tokens that you have access to, you'll see a warning.

Set up synchronized credentials

1. In the credential vault, create a User and password or Token credential. You can also overwrite an existing credential.

2. Turn on Synchronization with external vault.

3. Select Azure Key Vault (default) as the Credential source.

4. We recommend editing the default Credential name to easily identify your new credential.

5. Enter the URL to access the vault (Vault URL) and the Tenant ID.

6. Select the companion tokens created earlier for the Client (application) ID and Client secret.

7. Enter the name of the Azure Key Vault key.

   Username-password credentialsToken credentials

   • In Secret name for username, enter the name of the Azure Key Vault key mapped to the username value; do not enter an actual username.
   • In Secret name for password, enter the name of the Azure Key Vault key mapped to the password value; do not enter an actual password.

   • In Secret name for token, enter the name of the Azure Key Vault key mapped to the token value; do not enter an actual token value.

8. optional Provide a Description for the credential.

9. Credentials are set to Owner access only by default. (Read more about credential ownership.)

10. Save your credential.

See also Best practices and what happens when you edit or delete synchronized and companion credentials.

Azure Key Vault synchronization monitors

When you have set up your synchronized username-password or token credential, Dynatrace automatically creates and executes an HTTP monitor that synchronizes the credential with Azure Key Vault. This monitor is automatically associated with the synchronized username-password or token credential.

See also Best practices and what happens when you edit or delete synchronization credentials.

HashiCorp Vault

Username-password or token credentials for use in synthetic monitors can be synchronized with HashiCorp Vault key-value pairs containing the username, password, or value. You can use either AppRole-based or certificate authentication.

Prerequisites

• Before using AppRole-based authentication, you need to define the required secret ID as a token credential stored in the Dynatrace credential vault; do not reuse other tokens as the secret ID. If your vault doesn't contain any tokens you have access to, you'll see a warning.

• Before using certificate authentication, you need to store the required TLS certificate in the Dynatrace credential vault. If your vault doesn't contain any certificates you have access to, you'll see a warning.

We recommend naming such prerequisite tokens and certificates so they're easily identified as companion credentials for synchronization.

Set up synchronized credentials

1. In the credential vault, create a User and password or Token credential. You can also overwrite an existing credential.

2. Turn on Synchronization with external vault.

3. Select HashiCorp Vault as the Credential source.

4. We recommend editing the default Credential name to easily identify your new credential.

5. Enter the URL to access the vault (Vault URL) and the Path to credentials (folders must be separated by a forward slash).

   Note

   The HashiCorp Vault URL for certificate authentication might be different from that used for AppRole-based authentication.

6. Enter the name of the HashiCorp Vault key.

   Username-password credentialsToken credentials

   • In Secret name for username, enter the name of the HashiCorp Vault key mapped to the username value; do not enter an actual username.
   • In Secret name for password, enter the name of the HashiCorp Vault key mapped to the password value; do not enter an actual password.

   • In Secret name for token, enter the name of the HashiCorp Vault key mapped to the token value; do not enter an actual token value.

7. Steps related to Authentication method:

   AppRoleCertificate

   1. Select AppRole for the Authentication method.
   2. Enter the string provided by HashiCorp in Role ID.
   3. Select the companion token created earlier for the Secret ID.
   4. Enter the Vault namespace.

   

   1. Select Certificate for the Authentication method.
   2. For Certificate, select the companion TLS certificate credential created earlier.

   

8. optional Provide a Description.

9. Credentials are set to Owner access only by default. (Read more about credential ownership.)

10. Save your credential.

See also Best practices and what happens when you edit or delete synchronized and companion credentials.

When you have set up your synchronized username-password or token credential, Dynatrace automatically creates and executes an HTTP monitor that synchronizes the credential with HashiCorp Vault.

HashiCorp Vault AppRole synchronization monitors

The autocreated HTTP monitor contains two requests and is automatically associated with the synchronized credential defined above.

HashiCorp Vault TLS certificate synchronization monitors

The autocreated HTTP monitor contains two requests and is automatically associated with the synchronized credential defined above.

Best practices and caveats

• Automatically created synchronization monitors may be edited. To edit an autocreated synchronization monitor, you must have access to the credentials referenced in the monitor. You might need to make edits if the external vault vendor makes changes. For example, you might need to edit request URLs if Microsoft changes the API version for fetching client tokens from Azure Key Vault.
  • In general, however, we recommend that you limit your changes to execution frequency or locations.
  • When changing location, be careful not to pick private Synthetic locations that don't have external network access.
  • When changing location to a private Synthetic location, ensure that the proxy configuration isn't blocking access to required resources.
• If creating a synchronization monitor manually, be sure to select Do not store and display request and response bodies and header values in execution details in any requests that fetch client tokens or credential values from external vaults. Failing to do so will expose the sensitive information when you Analyze execution details in HTTP monitor details.
• We recommend editing the default names of synchronized credentials, companion credentials (for example, TLS certificates for HashiCorp Vault), and synchronization monitors for easy identification.
• We do not recommend reusing companion tokens (for example, for the HashiCorp secret ID) required for synchronization monitors in other synthetic monitors for testing purposes.

Edit or delete synchronized and companion credentials

• Once created, synchronized credentials are no longer editable by anyone; they can only be overwritten. In order to overwrite a synchronized credential, you need to provide new synchronization details; do not provide actual username, password, or token values.
  • When you overwrite a synchronized credential, Dynatrace-created synchronization monitors are automatically updated.
• Be sure to maintain the same ownership for all credentials within a synchronization monitor (that is, the synchronized credential and companion tokens/certificates)—they can all be public or all owned by the same owner.
• You cannot delete companion tokens referenced by a synchronization monitor unless you disable or delete the synchronization monitor.
• If you delete a synchronized credential, its autocreated synchronization monitor will be deleted.
  • If there's more than one synchronization monitor, you need to delete or disable such monitors before you can delete a synchronized credential.
  • Any synthetic monitor that uses the (deleted) synchronized credential for testing will be disabled.