Skip to content

Configuring Custom TLS Certificates

By default, CAS Manager is deployed using self-signed TLS certificates. Teradici recommends using a custom TLS certificate for using CAS Manager in production. You should renew and maintain these certificates as required. CAS Manager supports X509 certificates in PEM format, the certificate file must only include a single certificate, the CA bundle is not supported. The TLS key must not require Password.

To configure CAS Manager to use custom TLS certificates, or to update CAS Manager to use a new TLS certificate, follow the steps outlined below:

  1. Create a file called tls-config.json with the following contents:
      "tls-key-file": "<path to a file containing your TLS certificate key>",
      "tls-cert-file": "<path to a file containing your TLS certificate>"
  2. Update the TLS configuration by running the following command:
    sudo /usr/local/bin/cas-manager configure --config-file tls-config.json
    This command will update the CAS Manager services automatically, and this will take a few minutes to complete.

Internal TLS Certificates

When you are using internal MongoDB and Vault for data storage, in order to keep CAS Manager's internal communication secure, the installer will also generate a set of self-signed TLS certificates to be used for encrypting internal communication within CAS Manager. By default these certificates will expire 2 years from when they are generated.

In order to ensure that the CAS Manager uptime is not interrupted unexpectedly it is important to ensure that these certificates do not expire. This can be done by:

  • Upgrading CAS Manager regularly. These certificates will be regenerated by the installer during the upgrade process if they are close to expiring so upgrading at a regular cadence (eg, once or twice a year) will ensure everything remains operational.
  • If you do not want to upgrade CAS Manager and only want to use a version that you have qualified yourself, and that may exceed the TLS certificates expiration time, you can either:
    • Periodically re-deploy the CAS Manager instance you are running so that new certificates are generated regularly.
    • Run the command to re-generate certificates periodically. See Internal Certificate Generation below for steps on how to do this.
  • Monitor when the certificates are going to expire and plan to regenerate them beforehand. You can do this by either running the CAS Manager diagnose command or checking the CAS Manager health probe's logs. Run the following command to generate this health check:
    /usr/local/bin/cas-manager diagnose --health
    This health check will assess the Mongo Database and Vault connections. A warning message will be logged if the certificates are close to expiring and an error will be logged if they have expired. For example,
    INFO .. Connections:
    INFO .... MongoDB=Healthy
    WARN ...... Mongo Certificate Valid From=2021-08-17 19:35:42 Mongo Certificate Valid Until=2021-09-18 19:35:42
    INFO .... vault=Healthy
    WARN ...... Vault Certificate Valid From=2021-08-17 19:35:42 Vault Certificate Valid Until=2021-09-18 19:35:42
    In order to check the logs for the CAS Manager health probe, run
    /usr/local/bin/kubectl get jobs -o jsonpath='{.items[?("casm-health-probe")]}' --sort-by=.metadata.creationTimestamp | rev | cut -d' ' -f 1 | rev | xargs -I % /usr/local/bin/kubectl logs jobs/%
    This command will return the last completed CAS Manager health probe's logs and will state when the certificates will be expiring. For example:
    Secret Provider type is Vault
    Vault certificate is valid from Tue Aug 17 19:35:42 2021 until Sat Sep 18 19:35:42 2021
    Vault status - Initialized: True, Sealed: False
    Vault is healthy
    MongoDB certificate is valid from Tue Aug 17 19:35:42 2021 until Sat Sep 18 19:35:42 2021
    MongoDB is healthy
    CASM is healthy
    These commands will show the expiration date for the Mongo Database and Vault in both the default MongoDB/Vault mode or external MongoDB/Vault mode. For external MongoDB/Vault modes, you need to manually change the certificates yourself on the external instances since CAS Manager does not have the necessary permissions or functionality to do that for you.

Internal Certificate Generation

In the case where the certificate has expired or is about to expire, and you do not wish to upgrade your CAS Manager instance, you can generate internal certificates by running the following command:

/usr/local/bin/cas-manager configure --generate-certs
Once you have run this command, check the output of the diagnostics health command or the CAS Manager health probe as shown in point 3 above. Please note that this will only update the certificates within CAS Manager, so if you are using an external MongoDB and/or external Vault with TLS enabled, this command will not affect the external Database or Vault's certificates.