External vault integration

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

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

Autocreated synchronization monitors are named with the credential ID of the synchronized username-password 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 last execution).

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

A username-password credential for use in synthetic monitors can be synchronized with Azure Key Vault key-value pairs containing the username and password.

1. In the credential vault, create a User and password credential. You can also select an existing credential > Overwrite 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 tokens created earlier for the Client (application) ID and Client secret.
7. 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.
8. 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.
9. optional Provide a Description.
10. Credentials are set to Owner access only by default. (Read more about credential ownership.)
11. Save your credential.

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

Azure Key Vault synchronization monitors

When you have set up your synchronized username-password 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 credential.
• Token containing the client ID.
• Token containing the client secret.

The synchronization monitor contains three requests. Azure Key Vault requires splitting the retrieval of the username and password into two separate requests.

1. The first request (POST) fetches an access token.
   Request configuration details

   • The request URL references the tenant ID, which is stored as an attribute of the synchronized username-password credential defined above; the tenant ID is not displayed.

     

   • The client ID and client secret, referenced as attributes of the synchronized username-password credential, are passed as key-value pairs in the request body; the client ID and client secret are not displayed.

     

   • A client token is returned in the response body. A post-execution script saves the token in a global variable.

     

2. The second request (GET) fetches the username value.
   Request configuration details

   • The request URL references the vault URL as an attribute of the synchronized username-password credential defined above; the vault URL is not displayed. The request URL also references the key mapped to the username value in Azure Key Vault.

     

   • The Authorization header contains the access token retrieved in the first request.

     

   • The username value is returned in the response body. A post-execution script saves the value in a global variable.

     

3. The third request (GET) fetches the password value. It also uses api.saveCredential() to write the fetched values to the synchronized username-password credential defined above.
   Request configuration details

   • The request URL references the vault URL as an attribute of the synchronized username-password credential; the vault URL is not displayed. The request URL also references the key mapped to the password value in Azure Key Vault.

     

   • The Authorization header contains the access token retrieved in the first request.

   • The password value is returned in the response body. A post-execution script saves the value in a global variable. It also uses api.saveCredential() to write the retrieved values to the synchronized username-password credential.

     

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

HashiCorp Vault

A username-password credential for use in synthetic monitors may be synchronized with HashiCorp Vault key-value pairs containing the username and password. You can use either AppRole-based or certificate authentication.

1. In the credential vault, create a User and password credential. You can also select an existing credential > Overwrite 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).

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

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

8. 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 token created earlier for the Secret ID.
   4. Enter the Vault namespace.

   

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

   Note

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

   

9. optional Provide a Description.

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

11. Save your credential.

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

HashiCorp Vault synchronization monitors

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

The synchronization monitor contains two requests.

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

AppRole-based synchronization monitors

This autocreated HTTP monitor is automatically associated with the:

• Synchronized username-password credential.
• Token containing the secret ID.

1. The first request (POST) fetches a client token.
   Request configuration details

   • The request URL references the vault URL, which is stored as an attribute of the synchronized username-password credential defined above; the vault URL is not displayed. The request URL also contains the authentication method approle.

     

   • The vault namespace, referenced as an attribute of the synchronized username-password credential, is passed as a request header; the vault namespace is not displayed.

     

   • The role ID and secret ID, referenced as attributes of the synchronized username-password credential, are passed as key-value pairs in the request body; the role ID and secret ID are not displayed.

     

   • A client token is returned in the response body. A post-execution script saves the token in a global variable.

     

2. The second request (GET) fetches the username and password values. It also uses api.saveCredential() to write the fetched values to the synchronized username-password credential defined above.
   Request configuration details

   • The request URL references the vault URL and the path to the credentials, which are stored as attributes of the synchronized username-password credential; the vault URL and path to credentials are not displayed.

     

   • A request header contains the client token retrieved in the first request. The vault namespace (not displayed, but referenced as an attribute of the synchronized username-password credential) is also passed as a request header.

     

   • The username and password values are returned in the JSON response. A post-execution script saves the values in global variables. It also uses api.saveCredential() to write the retrieved values to the synchronized username-password credential.

     

TLS certificate-based synchronization monitors

This autocreated HTTP monitor is automatically associated with the:

• Synchronized username-password credential.
• Certificate credential used for authentication.

1. The first request (POST) fetches a client token.
   Request configuration details

   • The request URL references the vault URL, which is stored as an attribute of the synchronized username-password credential defined above; the vault URL is not displayed. The request URL also contains the authentication method cert.

     

   • The request uses the TLS certificate for authentication.

     

   • A client token is returned in the response body. A post-execution script saves the token in a global variable.

     

2. The second request (GET) fetches the username and password values. It also uses api.saveCredential() to write the fetched values to the synchronized username-password credential defined above.
   Request configuration details

   • The request URL references the vault URL and the path to the credentials, which are stored as attributes of the synchronized username-password credential; the vault URL and path to credentials are not displayed.

     

   • A request header contains the client token retrieved in the first request.

     

   • The username and password values are returned in the JSON response. A post-execution script saves the values in global variables. It also uses api.saveCredential() to write the retrieved values to the synchronized username-password credential.

     

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 last execution in HTTP monitor details.
• We recommend editing the default names of synchronization credentials (synchronized username-password pairs, tokens, certificates) and synchronization monitors for easy identification.
• We do not recommend reusing tokens (for example, for the HashiCorp secret ID) required for synchronization monitors in other synthetic monitors for testing purposes.

Edit or delete synchronization 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 or password 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 other tokens/certificates)—they can all be public or all owned by the same owner.
• You cannot delete 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.