Certificate Management

Note:

All commands can be run as the assure1 user unless specified that root is required.

Unified Assurance leverages SSL certificates for security, trust, and authentication in parts of the product. It includes a root CA bundle and a certificate generation tool in order to secure connections between internal components. Should you wish to use an externally signed web certificate, a pre-packaged CSR is included. Certificates and corresponding keys can be found in:

$A1BASEDIR/etc/ssl

Dependencies

When running commands as root, one of the following must be done.

Potential Impact

  1. Expired or untrusted web certificates will display a warning to users of the web UI.

  2. Applications that rely on certificates may stop functioning (Docker, SVN, etc.)

Replace Unified Assurance Generated Certificates

Host and User certificates have an expiration time of four years after creation. Once they expire, they must be regenerated for specific functionality to continue working. Each server has its own host certificate, so not all certificates will expire at the same time depending on when the initial installation was performed. However, certificates can be regenerated on multiple servers at the same time. Web Certificates should be regenerated every 13 months (397 days), 2 year certificates issued before September 2020 will continue to work on all major browsers until their original expiration date.

Identification

Certificates that are soon-to-be expired (within 30 days) or are already expired will be notified to users in two places.

You can see the specific certificate expiration by selecting a server and looking in the details form.

Resolution

Certificates can be renewed by following these resolution steps.

  1. On each server, run the following command to regenerate the Host certificate:

    $A1BASEDIR/bin/CreateSSLCertificate --Type Host --CN $HOSTFQDN --Force

    Note:

    Set $A1BASEDIR to the appropriate installation directory (usually /opt/assure1) and $HOSTFQDN to the appropriate server FQDN (e.g. hostname.example.com)

  2. If your Web certificate is not signed by an external third-party, on Presentation servers only, run one of the following commands to regenerate the Web certificate:

    $A1BASEDIR/bin/CreateSSLCertificate --Type Web --CN $WEBFQDN --Force

    OR

    $A1BASEDIR/bin/CreateSSLCertificate --Type Web --CN $WEBFQDN --AltCN $HOSTFQDN1 --AltCN $HOSTFQDN2 --Force

    Note:

    Set $A1BASEDIR to the appropriate installation directory, $WEBFQDN to the appropriate web FQDN (e.g. presentation.example.com), and $HOSTFQDN{1,2} to the appropriate server FQDNs of the Presentation servers (e.g. hostname1.example.com & hostname2.example.com). The value for $WEBFQDN would be the load balancer or shared fqdn used for redundancy, normally the address visited by users of Unified Assurance. The values for $HOSTFQDN{1,2} can be found in the Servers section of the Unified Assurance UI or the Unified Assurance Servers table on the primary presentation server.

    source $A1BASEDIR/.bashrc
a1mysql
select ServerHostFQDN, WebFQDN, ServerID, PrimaryServerID from Servers where IsPresentation=1;
select ServerHostFQDN, WebFQDN, ServerID, PrimaryServerID from Servers where PrimaryServerID in (select ServerID from Servers where IsPresentation=1);

  3. Restart the web server any time the Web certificate is regenerated with the following command:

    # as root
service assure1-web restart

  4. Finally, on each server, reload the Broker to update the new certificate expirations:

    $A1BASEDIR/bin/BrokerControl --batch reload

    Note:

    Set $A1BASEDIR to the appropriate installation directory.

Using an Externally Signed Web Certificate

Web certificates by default are automatically signed by the Unified Assurance Global CA. This CA is not known to major web browsers and will display a warning to users. Without the CA being trusted, users must either allow an exception to the certificate or import the Unified Assurance Global CA. Most organizations will instead prefer users have a seamless experience by signing the web certificate with a trusted vendor known by default to all major web browsers.

Most commands here can be run as the "assure1" user. The ones that must be run as root are marked as such below.

  1. Gather the certificate request from the primary presentation server.

    $A1BASEDIR/etc/ssl/Web.csr

  2. Send the certificate request to the external authority for signing.

  3. After the external authority has signed the certificate, a few files will be sent back. Copy the signed certificate to $A1BASEDIR/etc/ssl/Web.crt overwriting the existing file.

  4. (Optional) If the certificate request and key were not generated from Unified Assurance (e.g. using a wildcard certificate for your domain), you will need to update the associated key too. Copy the key file to $A1BASEDIR/etc/ssl/Web.key overwriting the existing file.

  5. Identify the intermediate chain file and add the contents to both the signed certificate file and the bundle CA certificates file.

    cat intermediate.pem >> $A1BASEDIR/etc/ssl/Web.crt
cat intermediate.pem >> $A1BASEDIR/etc/ssl/BundleCA.crt

  6. Copy the updated BundleCA.crt to every existing Unified Assurance server. New Unified Assurance servers will automatically get the new BundleCA.crt when they join.

  7. Update the Docker trusted CA file on every existing server with the Presentation.Internal or Cluster.* roles. New Unified Assurance servers will automatically use the correct CA file during installation.

    Note:

    That may fail if there is more than one directory in /etc/docker/certs.d/; if so, you'll need to replace the ca.crt in the directory of the hostname used by the assure1-docker system.

    # as root
cp $A1BASEDIR/etc/ssl/BundleCA.crt /etc/docker/certs.d/*/ca.crt

  8. Update the BundleCA.crt for Elasticsearch on all Elastic servers, restart Telegraf, Elasticsearch and Kibana.

    cp $A1BASEDIR/etc/ssl/BundleCA.crt $A1BASEDIR/vendor/elasticsearch/config/certs/BundleCA.crt

  9. Restart Apache to start using the new certificate:

    # as root
systemctl restart assure1-web

  10. Verify the new certificate works.

  11. In the UI, go to the Global Properties UI:

    Configuration -> Global Properties

  12. Select the CertificateAuthorityWarning entry.

  13. In the form, change Property Value to 0, then click on the Submit button. This will prevent a blue banner appearing asking you to install the Unified Assurance global certificate.

Troubleshooting Existing Certificates