Skip to content

Configuring a Secret Storage Application

The following section outlines the steps involved in configuring specific secret storage applications to work with CAS Manager. You must have prepared the secret storage applications prior to installing CAS Manager.

Data Migration between Secret Stores Prohibited

CAS Manager does not support any data migration between secret stores. If CAS Manager is originally configured with another secret store application, for example Hashicorp Vault, and is then configured to use Azure Key Vault, CAS Manager will not have access to the data stored in the original Vault. CAS Manager will not be able to retrieve any stored passwords, so login requests will fail. Teradici recommends using the same secret store throughout the lifetime of a CAS Manager instance.

Configuring Azure Key Vault

Follow the steps below to configure CAS Manager to use the Azure Key Vault as its secret storage application. CAS Manager must be installed before the command can be run:

  1. SSH to the target machine where you installed CAS Manager.
  2. Create a config file that contains the following parameters and information:
    {
    "vault-type": "azure",
    "key-vault-url": "<URL of Azure Key Vault>",
    "azure-client-id": "<client id of Azure service principal>",
    "azure-client-secret": "<client secret of Azure service principal>",
    "azure-tenant-id": "<tenant id of Azure service principal>"
    }
    
  3. Run the following command to implement the config file:
    sudo /usr/bin/local/cas-manager configure --config-file <config file name>
    

Configuring Hashicorp Vault

Follow the steps below to configure CAS Manager to use Hashicorp Vault as its secret storage application. CAS Manager must be installed before the command can be run:

  1. SSH to the target machine where you installed CAS Manager.
  2. Create a file that contains the following data:
    {
            "vault-type": "vault",
            "vault-url": "https://<vault_address>",
            "vault-token": "<vault_token>",
            "vault-secret-path": <in this example: secret/data>
    }
    
  3. Replace the following place holders with your own values:
    • vault_address: IP address or domain name of the Vault server.
    • vault_token: The access token generated on the Vault server that will be used by CAS Manager to access the Vault.
  4. Run the following command to configure CAS Manager to use Vault:
    sudo /usr/local/bin/cas-manager configure --config-file path-to-your-config-file
    
    After running this command, CAS Manager will validate the configuration by attempting to query the Vault's health status. If the request is successful, then CAS Manager will be configured to use this Vault. The configure command should only take a few minutes to complete. To verify that the connection to the Vault is healthy, run the following command:
    sudo /usr/local/bin/cas-manager diagnose --health
    
    ## It will show the following if Vault is healthy:
    [2021-01-25T22:49:02Z]  INFO .. Connections:
    [2021-01-25T22:49:02Z]  INFO .... Vault=Healthy
    
    ## It will show the following if Vault is unhealthy:
    [2021-01-26T01:47:10Z]  INFO .. Connections:
    [2021-01-26T01:47:10Z] ERROR .... Vault=Vault service is unreachable
    [2021-01-26T01:47:10Z] ERROR .. Overall Health=CAS Manager is in Unhealthy state because Vault is unhealthy
    

Connecting to a Vault server with Self-Signed TLS Certificates

Tested on CentOS Only

The following steps have been tested on CentOS. These steps may not work, or work differently, on different systems.

The following steps outline how to connect to a Vault server that uses self-signed TLS certificates:

  1. Create a file called vault-config.json that contains the following:
    {
            "vault-type": "vault",
            "vault-url": "https://<vault_address>",
            "vault-token": "<vault_token>",
            "vault-ca-cert-file": "<vault_ca_cert_file>",
            "vault-skip-verify-cert": false,
            "vault-secret-path": "secret/data"
    }
    
  2. Replace the following place holders with your own values:

    • vault_address (string): IP address or domain name of the Vault server.
    • vault_token (string): The access token generated on the Vault server that will be used by CAS Manager to access the Vault.
    • vault_ca_cert_file (string): The path to the file containing the CA certificate for your self-signed certificate.
  3. Run the following command to update CAS Manager to use Vault:

    sudo /usr/local/bin/cas-manager configure --config-file path-to-your-config-file
    

  4. If you want to skip certificate verification, include "vault-skip-verify-cert":true in your configuration file. Please note that this is not secure and is not recommended for production use cases:
    {
            "vault-type": "vault",
            "vault-url": "https://<vault_address>",
            "vault-token": "<vault_token>",
            "vault-ca-cert-file": "<vault_ca_cert_file>",
            "vault-skip-verify-cert": true,
            "vault-secret-path": "secret/data"
    }
    

Vault Token Auto-Renewal

CAS Manager does not renew the Vault token by default. You can manually set-up auto-renewal by configuring the vault-config.json file. For more information on renewing Vault tokens, see Vault Token Renewal.

CAS Manager can automatically renew the Vault token. You need to enable the setting in the vault-config.json file, and set the interval you wish the token to renew at. To enable this feature, add the Vault token auto-renew settings as follows:

  1. Edit the vault-config.json file with the following settings:
    {
            "vault-type": "vault",
            "vault-url": "https://<vault_address>",
            "vault-token": "<vault_token>",
            "vault-secret-path": <in this example: secret/data>
            "vault-enable-token-renew": true,
            "vault-token-renew-interval": "<crontab expression: eg @hourly, @daily, @weekly, @monthly>"
    }
    
  2. Set the auto-renew token setting appropriately. The vault-token-renew-interval is a cron tab string. It can either be in a descriptor format as outlined in the above example, or you can set it to your own custom cron tab expression. The cron tab expression needs to be in the following format:
"<minute> <hour> <day-of-month> <month> <day-of-week>"

Vault Token Renewal Interval

To ensure that the Vault token is kept alive, the renewal needs to be able to occur multiple times before the token expires. If the token expires in a week, then you need to renew at least twice a week, if it expires every day, it needs to be renewed every few hours.

Vault Data Migration

CAS Manager does not do any data migration between different Vault configurations. If CAS Manager is updated to use a new Vault configuration, it will no longer be able to access the data from the previous configuration. If the admin user's password had been updated using a prior Vault configuration, you will no longer be able to login. To fix this, do one of the following:

  • If you have access to the old Vault, migrate the data from the old Vault to the new Vault.
  • Find the key that CAS Manager is using to look for the admin password in the Vault and then manually store the password in the Vault at that location. To find the key, stream the logs for the secretmgmt service by running the following command:
    /usr/local/bin/kubectl logs -l app=secretmgmt -f
    
    Log in to CAS Manager using the adminUser account and look for the log that includes the route /internal/secrets/admin-XXX. The password is expected to be at <secret path>/admin-XXX in the Vault, where secret path is the path defined by "vault-secret-path" in your CAS Manager config-file.
  • Update to use a new MongoDB, or drop the standaloneAdmins collection in your MongoDB. WARNING: this will cause you to lose all of your CAS Manager data.