Reveal Help Center

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:

Role

Host Name

IPv4 Address

IPv6 Address

Application

brains-app

10.1.1.10

fe80::250:56ff:feb8:cdfc

On-Demand Analytics

brains-oda

10.1.1.11

fe80::250:56ff:feb8:ccfd

Analytics

brains-ana

10.1.1.12

fe80::250:56ff:feb8:ced2

DNS Domain:

example.com

Application URL:

https://brains.example.com/

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:

Request Field

Value

CommonName

brains.example.com

subjectAltName

DNS: brains-app

subjectAltName

DNS: brains-app.example.com

subjectAltName

IP: 10.0.0.10

subjectAltName

IP: fe80::250:56ff:feb8:cdfc

subjectAltName

DNS: brains-oda

subjectAltName

DNS: brains-oda.example.com

subjectAltName

IP: 10.0.0.11

subjectAltName

IP: fe80::250:56ff:feb8:ccfd

subjectAltName

DNS: brains-ana

subjectAltName

DNS: brains-ana.example.com

subjectAltName

IP: 10.0.0.12

subjectAltName

IP: fe80::250:56ff:feb8:ced2

subjectAltName

DNS: localhost

subjectAltName

DNS: localhost.localdomain

subjectAltName

IP: 127.0.0.1

subjectAltName

IP: ::1

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.

Version

HAProxy Service Name

HAProxy Certificate File

6.0 - 6.0.x

haproxy

/etc/haproxy/brainspace_ss.pem

6.1 - 6.1.x

haproxy

/etc/haproxy/brainspace_ss.pem

6.2+

brainspace-haproxy

/etc/brainspace/ssl/brainspace_ss.pem

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 your `pfx` store certificate format to a `pem` format using the following command:

    openssl pkcs12 -in <cert.pfx> -out newcert.pem -nodes

  2. Replace the default certificate with the new certificate with the following command:

    install -b newcert.pem <ssl certificate file> (see Brainspace Version SSL Configuration Changes table above for certificate file name)

  3. Restart Brainspace HAProxy:

    systemctl restart <haproxy service name> (see Brainspace Version SSL Configuration Changes table above for haproxy service name)

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