KB441531: Setup Guide for MicroStrategy Library and Collaboration: Enabling TLS/SSL and Clustering

Description

This knowledge base article outlines requirements, considerations, and steps to take when enabling Strategy Library and Strategy Collaboration Server for secure communication and/or load balanced service. Here at Strategy, we want to ensure that our users have the information they need to get their platform up and running.

Strategy Library and Collaboration Server Infrastructure Overview

Considerations

When configuring the application server that hosts Strategy Library for HTTPS (SSL/TLS), Collaboration Server must be configured for HTTPS (SSL/TLS) also. If this condition is not met, no Collaboration Services will be available to Strategy Library users.

1. When configuring the application server that hosts Strategy Library for HTTPS (SSL/TLS), Collaboration Server must be configured to trust the certificate chain of the application servers server certificate. If this condition is not met, no Collaboration Services will be available to Strategy Library users and Collaboration Server will not start correctly. When starting, Collaboration Server will attempt to connect to the URL specified under authorizationServerURL and will not start correctly if Strategy Library’s server certificate is not trusted and cause the error “err=self signed certificate in certificate chain” in Collaboration Server logs when logging is enabled in config.json configuration file.
2. When configuring Collaboration Server for HTTPS (SSL/TLS), Strategy Library must be configured to trust the certificate chain of Collaboration Servers server certificate. If this condition is not met, no Collaboration Services will be available to Strategy Library users and the Collaboration Server test on the Strategy Library Administration page will fail with error “ERR006: Unable to connect to service”.
3. The end user machine must be configured to trust the server certificate of Strategy Library and Collaboration Server.

Server Certificates

Certificate trust is typically established when the following conditions are met:

• The server certificate’s issued to attribute corresponds to the machine name/domain used to access the server.
• The server certificate’s validity period has not expired.
• The server certificate’s issued by attribute is a trusted Certificate Authority (CA).

Server certificates can be reviewed from any browser by navigating to the site and viewing the server certificate through the browser. It is highly recommended to use Firefox, which has the explicit download “as chain” option. Full instructions on how to obtain a copy of server certificates is found at KB441533 .

Configuring Collaboration Server for Secure Communication

As seen on the diagram, Collaboration server must be able to connect to Strategy Library on start up. While network connectivity to the Library server is required, the Collaboration server must also be configured to trust the Library server certificate. Full instructions on how to obtain a copy of server certificates and generate the .pfx keystore file is found at KB441533 .

1. Obtain copy of Library SSL Certificate chain. It is suggested to place it into same directory as config.json.
2. Generate a .pfx keystore file.
3. Modify config.json at C:\Program Files (x86)\Strategy\Collaboration Server (Windows) or [MSTR_INSTALL]/Collaboration Server (Linux). The config.json file is used to configure various properties of Collaboration Server. The following example snippet shows one possible configuration setup.
   

   
   {
     "scaling" : "none",
     "secretKey" : "iz8n33333aZueUq48Wjj",
     "authorizationServerUrl" : "http://<fullyqualifieddomainname>:8443/StrategyLibrary/api",
     "dataSource" : {
       "password" : "t48ZAL2TJ/rifbq+crbVw8dluY74444s9dwr/QBrAu2RHLBrF8zeuX4gw==\n",
       "username" : "mstr_collab",
       "port"     : 5433
     },
     "port" : 3000,
     "enableTls": true,
     "keystoreFile": "collabsvc.pfx",
     "passphrase": "myPassphrase",
     "trustedCerts": ["c:/ssl certs/libraryCertificates.pem" ]
     }

   
   Key Fields:
   
• authorizationServerUrl: The URL must correspond to the actual scheme (HTTPS), server name and port (if applicable) that is used by the end users to connect to Strategy Library, followed by /api.
• enableTls: This parameter enables TLS communication for port 3000 and allows accessing Collaboration Server using https://servername:3000.
• secretKey: An additional layer of authentication can be enabled in Strategy Library Admin but setting a password. This param must match that password value.
• keystoreFile: The path and name of the key store/trust store file containg the server certificate for the Collaboration Server machine. Note that on Windows as well as on Linux, forward slashes must be used for the file path. In this example, the file was copied to same directory as config.json so no path information is needed.
• port: The port collaboration service will be running on. Default value is 3000. Be sure to place this field under the dataSource field or you may encounter "Port X is already in use. Aborted.” error!
• passphrase: The password to read the keystore.
• trustedCerts: The path and name of the certificate containing the root and intermediate certificates of the authorizationServerUrl. Note that on Windows as well as on Linux, forward slashes must be used for the file path. Most often the file is obtained as .pem but it can also be .cer. In this example, the certificate file is a chain pem file and placed to separate directory and thus the absolute path is given. If your certificates are not in chain format, insert all paths into the this array and use commas to separate the strings.
4. Save and restart Collaboration Server.
5. Verify that Collaboration Server is running correctly:
   
• Using a browser, access https://servername:3000.
• Click here to see information on the runtime status of the server.
• The state should be running.

How to Configure Library for Secure Communication

As seen on the diagram, the Strategy Library must be able to directly connect to Collaboration Server. While network connectivity to the Collaboration server is required, Strategy Library server must also be configured to trust the Collaboration server certificate. Full instructions on how to obtain a copy of server certificates and generate the .pfx keystore file is found at KB441533 .

1. Obtain copy of .pfx trust store of Collaboration Server. The trust store must be copied to the machine hosting Strategy Library under [LIBRARY_DEPLOYMENT_FOLDER]/WEB-INF. Be sure to adjust file permissions for the account running the application server to be able to read the trust store file.
2. Modify configOverride.properties from [LIBRARY_DEPLOYMENT_FOLDER]/WEB-INF/classes/config. The configOverride.properties file is used to configure various properties of the Strategy Library deployment. The following parameters must be set:
   

   
   services.collaboration.baseURL = https://servername:3000
   services.collaboration.enabled = true
   services.collaboration.tlsEnabled = true
   trustStore.path = /WEB-INF/collabsvc.pfx
   trustStore.passphrase = mstr123

   
   Key Fields:
   
• services.collaboration.baseURL: Specify the HTTPS URL to connect to Collaboration Server.
• services.collaboration.enabled: Set to true to enable Collaboration Server.
• services.collaboration.tlsEnabled: Set to true if Collaboration server has been enabled for TLS.
• trustStore.path: The relative path and name to the trust store containing the root and intermediate certificates of the services.collaboration.baseURL. The trust store must exist in [LIBRARY_DEPLOYMENT_FOLDER]/WEB-INF.
• trustStore.passphrase: Specify the password used to create the trust store.
3. Note:The first three entries can also be generated using the Strategy Library administration page. To configure the trust store, configOverride.properties must be modified. It is required to restart the application server after making any change to configOverride.properties.
   
4. Verify that you connected to the Collaboration Server succesfully.
   
• .Open https://servername/MicroStrategyLibrary/admin and authenticate with the application server's administrator username and password.
• Click Collaboration Server.
• .Click Test connection.

Load Balanced/SSL Offloading Proxy Infrastructure

A common use case might be to operate application servers hosting Strategy Library behind a HTTPS enabled load balancer or SSL/TLS offloading proxy server as entry point for clients. The principals of trust are identical to the simple setup explained above--in this scenario Strategy Library and Collaboration Server must be able to connect to the load balancers or proxy servers domain and trust its certificate.

Considerations

When configuring a secure load balancer or secure proxy server entry point to access Strategy Library, Collaboration Server must be configured for HTTPS (SSL/TLS) also. If this condition is not met, no Collaboration Services will be available to Strategy Library users.

1. When configuring a secure load balancer or secure proxy server entry point to access Strategy Library, Collaboration Server must be able to connect to Strategy Library through the load balancer URL and must be configured to trust the certificate chain of the load balancers server certificate. If this condition is not met, no Collaboration Services will be available to Strategy Library users and Collaboration Server will not start correctly. When starting, Collaboration Server will attempt to connect to the URL specified under authorizationServerURL and will not start correctly if the load balancer's server certificate is not trusted and cause the error “err=self signed certificate in certificate chain” in Collaboration Server logs when logging is enabled in config.json configuration file.
2. When configuring Collaboration Server for HTTPS (SSL/TLS), Strategy Library must be configured to trust the certificate chain of Collaboration Servers server certificate. If this condition is not met, no Collaboration Services will be available to Strategy Library users and the Collaboration Server test on the Strategy Library Administration page will fail with error “ERR006: Unable to connect to service”.
3. The end user machine must be configured to trust the server certificate of the load balancer.
4. While clients communicate through HTTPS with the load balancer, the load balancer might communicate with the application web server hosting Library and Collaboration server with HTTP. In this case it is not required to configure the application web server and Collaboration server with a keystore. Nevertheless, a trust store is required for Strategy Library and Collaboration Server to be able to connect to each other via the load balancer URL (steps 1 and 2).

Guide to setup load balancer for Library .
Guide to setup clustering for Collaboration Server

Considerations When Configuring a Load Balanced Environment with Secure Communication

Since the load balancer serves as the proxy for both Library and Collaboration Server, the certificates and trust store information must come from the load balancer, not the direct Library or Collaboration Server. Follow the same steps above and in KB441533 . above but perform the actions on the server hosting load balancer instead.