• Home
  • Platform modules
  • Digital Experience
  • Synthetic Monitoring
  • General information about Synthetic Monitoring
  • External vault integration

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.

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

Create Azure synchronization - token

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.

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 as an attribute of the synchronized credential defined above; the tenant ID is not displayed.

      Azure KV request 1 URL

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

      Azure KV request 1 request body

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

      Azure KV request 1 post script

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

      Azure KV request 2 URL

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

      Azure KV request 2 request header

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

      Azure KV request 2 post script

  3. The third request (GET) fetches the password value. It also uses api.saveCredential() in a post-execution script 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 credential; the vault URL is not displayed. The request URL also references the key mapped to the password value in Azure Key Vault.

      Azure KV request 3 URL

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

      Azure KV request 3 post script

The synchronization monitor contains two 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 credential defined above; the tenant ID is not displayed.

      Azure KV request 1 URL

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

      Azure KV request 1 request body

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

      Azure KV request 1 post script

  2. The second request (GET) fetches the token value.
    Request configuration details
    • The request URL references the vault URL as an attribute of the synchronized credential defined above; the vault URL is not displayed. The request URL also references the key mapped to the token value in Azure Key Vault.

      Azure KV request 2 URL

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

      Azure KV request 2 request header

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

      Azure KV request 2 post script

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.

    • 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:

    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.

    Create HashiCorp AppRole synchronization - token

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

    Create HashiCorp certificate synchronization - UID

  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.

  1. The first request (POST) fetches a client token.
    Request configuration details
    • The request URL references the vault URL as an attribute of the synchronized credential; the vault URL is not displayed. The request URL also contains the authentication method approle.

      HashiCorp AppRole request 1 URL

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

      HashiCorp AppRole request 1 header

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

      HashiCorp AppRole request 1 body

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

      HashiCorp AppRole request 1 post script

  2. The second request (GET) fetches the username and password values. It also uses api.saveCredential() in s post-execution script 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 as attributes of the synchronized credential; the vault URL and path to credentials are not displayed.

      HashiCorp AppRole request 2 URL

    • 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 credential) is also passed as a request header.

      HashiCorp AppRole request 2 headers

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

      HashiCorp AppRole request 2 post script

  1. The first request (POST) fetches a client token.
    Request configuration details
    • The request URL references the vault URL as an attribute of the synchronized credential; the vault URL is not displayed. The request URL also contains the authentication method approle.

      HashiCorp AppRole request 1 URL

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

      HashiCorp AppRole request 1 header

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

      HashiCorp AppRole request 1 body

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

      HashiCorp AppRole request 1 post script

  2. The second request (GET) fetches the token value. It also uses api.saveToken() in a post-execution script to write the fetched values to the synchronized token credential defined above.
    Request configuration details
    • The request URL references the vault URL and the path to the credentials as attributes of the synchronized credential; the vault URL and path to credentials are not displayed.

      HashiCorp AppRole request 2 URL

    • 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 credential) is also passed as a request header.

      HashiCorp AppRole request 2 headers

    • The token value is returned in the JSON response. A post-execution script saves the value in a global variable. It also uses api.saveToken() to write the retrieved value to the synchronized token credential.

      HashiCorp AppRole request 2 post-script to save token

HashiCorp Vault TLS certificate synchronization monitors

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

  1. The first request (POST) fetches a client token.
    Request configuration details
    • The request URL references the vault URL as an attribute of the synchronized credential; the vault URL is not displayed. The request URL also contains the authentication method cert.

      HashiCorp certificate request 1 URL

    • The request uses the TLS certificate for authentication.

      HashiCorp certificate request 1 certificate

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

      HashiCorp certificate request 1 post script

  2. The second request (GET) fetches the username and password values. It also uses api.saveCredential() in a post-execution script 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 as attributes of the synchronized credential; the vault URL and path to credentials are not displayed.

      HashiCorp AppRole request 2 URL

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

      HashiCorp certificate request 2 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.

      HashiCorp certificate request 2 post script

  1. The first request (POST) fetches a client token.
    Request configuration details
    • The request URL references the vault URL as an attribute of the synchronized credential; the vault URL is not displayed. The request URL also contains the authentication method cert.

      HashiCorp certificate request 1 URL

    • The request uses the TLS certificate for authentication.

      HashiCorp certificate request 1 certificate

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

      HashiCorp certificate request 1 post script

  2. The second request (GET) fetches the token value. It also uses api.saveToken() in a post-execution script to write the fetched value to the synchronized token credential defined above.
    Request configuration details
    • The request URL references the vault URL and the path to the credentials as attributes of the synchronized credential; the vault URL and path to credentials are not displayed.

      HashiCorp AppRole request 2 URL

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

      HashiCorp certificate request 2 header

    • The token value is returned in the JSON response. A post-execution script saves the value in a global variable. It also uses api.saveToken() to write the retrieved value to the synchronized token credential.

      HashiCorp certificate request 2 post-script to save token

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.