Replacing the Default Brainspace Self-Signed SSL Certificates

The Brainspace application is installed with self-signed SSL certificates on all interfaces ("front side" user interface, as well as intra-server communications) to encrypt all communications. Some Brainspace customers choose to replace the default Brainspace self-signed SSL certificate with a commercial SSL certificate to have more control over the domain name and encryption level and to meet organization-specific security policy requirements.

Brainspace SSL Certificate Requirements

Important

SSL Certificate validation requires that the certificate's CN (common name) and/or one of its SANs (Subject Alternate Names) match a resolvable host name that also matches what is specified in the Services tab in the Brainspace Admin console.

For example, consider a three-server deployment of Brainspace with the following hosts and environment:

If you were ordering an SSL certificate that will be used on all three hosts, you will need to include all of the following in your certificate request:

Brainspace Version SSL Configuration Changes

The location for the SSL certificates, certificate format, and the HAProxy service name has changed. Please use the following table to identify the appropriate variables for your Brainspace instance.

Note

During upgrades, the /etc/brainspace/ssl directory is archived into a brainspace_ss-backup.10-16-2019_2116.tar file. This file can be un-archived with tar -xvf brainspace_ss-backup.10-16-2019_2116.tar, and the contents will have your brainspace_ss.pem file that can be moved back in place in /etc/brainspace/ssl. Once done, the brainspace-haproxy service will need to be restarted with service brainspace-haproxy stop && service brainspace-haproxy start.

Replacing the Brainspace User Interface (HAProxy) SSL Certificate on the Application Server

The default Brainspace user interface (UI) SSL certificate is configured in HAProxy on the Application server.

Important

Run all commands as the root user.

To replace the Brainspace UI (HAProxy) SSL certificate on the Application server:

1. Convert the pfx file to crt:
   openssl pkcs12 -in <your_new_pfx_file>.pfx -clcerts -nokeys -out <your_cert_file>.crt

2. Convert the pfx to an 'encrypted' pem file:
   openssl pkcs12 -in <your_new_pfx_file>.pfx -out <your_encrypted_pem>_encrypted.pem -nodes

3. Convert the private key to an RSA private key:
   openssl rsa -in <your_encrypted_pem>_encrypted.pem -out <your_new_rsa_pem_file>.pem

4. Write the new pem and crt files into the pem file haproxy will use:
   cat <your_new_rsa_pem_file>.pem <your_cert_file>.crt > /etc/brainspace/ssl/brainspace_ss.pem

5. Restart haproxy:
   systemctl restart brainspace-haproxy

If you have issues loading the UI, contact Brainspace Support.

Replacing the Brainspace Platform Service SSL Certificate on the Application Server [Not Recommended]

The service SSL certificate is used to encrypt intra-server communications (between the Application server and Analytics/On-Demand Analytics servers).

It is not recommended to change this certificate.

If you have any questions regarding changing this certificate, please contact Brainspace Support.

Important

Run all commands as the root user.

Obtaining a replacement SSL Certificate for Brainspace Services

Request your new certificate from the issuing authority in `pfx` certificate store format with the certificate, private key and intermediate (signing information or CA bundle) included. With most certificate providers, you can request the certificate pre-formatted for IIS to receive this format. If your certificate is received in another format, you may be able to find a conversion utility on the internet to convert it to `pfx` format.

To obtain a replacement SSL certificate for Brainspace services:

1. Copy your new certificate to a location that will not be overwritten during a Brainspace upgrade (Make the directory if it does not exist).
   [[ -d /etc/brainspace/ssl ]] || mkdir /etc/brainspace/ssl
   install -o brains <your new certificate file> /etc/brainspace/ssl

2. Modify the /var/lib/brains/app/apache-tomcat8/conf/server.xml file to replace the KeystoreFile and KeystorePass values with the full path to the new certificate and the password used to generate the certificate.
   Sample:
   <connector port="8081" protocol="HTTP/1.1" sslenabled="true"... keyAlias="discovery" keystoreFile="/etc/brainspace/ssl/brainspace.pfx" keystorePass="BrainzChangeMe!".../>

3. Modify the /var/lib/brains/.brainspace/brainspace.properties file to replace the keystore values with the full path to the new certificate and the password used to generate the certificate.
   Sample:
   server.port=8081
   keystore.file.name=/etc/brainspace/ssl/brainspace.pfx
   keystore.password=BrainzChangeMe!
   network.security=SECURE_SELFSIGNED_CERTS

4. Restart the Tomcat service:
   systemctl stop tomcat
   ps aux | grep tomcat (make sure it actually is not running)
   systemctl start tomcat

5. Verify that the Application service is not in an error state.

If the server is in an error state, contact Brainspace Support.

Updating the Brainspace-Analysis Service SSL Certificates on the Analytics and On-Demand Analytics Servers [Not Recommended]

The default Brainspace SSL certificate is configured for the Brainspace-Analysis service on the Analytics and On-Demand Analytics servers.

It is not recommended to change this certificate.

Important

Run all commands as the root user.

To update the Brainspace-Analysis Service SSL Certificates on the Analytics and On-Demand Analytics servers:

1. Copy your new certificate to a location that will not be overwritten during a Brainspace upgrade (Make the directory if it does not exist).
   [[ -d /etc/brainspace/ssl ]] || mkdir /etc/brainspace/ssl
   install -o brains <your new certificate file> /etc/brainspace/ssl

2. Modify the /var/lib/brains/.brainspace/analysis.properties file to replace the keystore values with the full path to the new certificate and the password used to generate the certificate. Sample:
   keystore.file.name=/etc/brainspace/ssl/brainspace.pfx
   keystore.password=BrainzChangeMe!
   network.security=SECURE_SELFSIGNED_CERTS

3. Restart the Analysis service:
   systemctl stop brainspace-analysis
   ps aux | grep brains (make sure it actually is not running)
   systemctl start brainspace-analysis

4. Verify that the Analytics and On-Demand Analytics services are not in an error state.

If either of the servers is in an error state, contact Brainspace Support.