KB484336: Upgrading your TLS certificate in MicroStrategy 2020

Description

After upgrading from Strategy 2019 to Strategy 2020, you may encounter the following error message when attempting to use bookmarks in Strategy Library.
In Strategy versions prior to 2020 Update 2:
 
Unable to execute I-Server REST API. This might be caused by limitations on socket port for IServer REST API.

In Strategy 2020 Update 2 and later versions:
Due to the security enhancements in Strategy 2020, you must regenerate and replace the certificate and key files for a successful TLS connection. 

Why is this happening?

You receive this error because a new set of SSL standards require your certificate to include a subjectAlternativeName, or SAN. This was not previously required in Strategy 2019.

Solution  

You need to properly and safely generate a new certificate which includes a SAN. 
If you have been using Strategy with self-signed certificate and key files, or are using the certificate and key files created via the Configuration Wizard, generate a self-signed certificate. 
If your workplace manages certificates through an RCA, a self-signed certificate may not meet your organization’s safety and security needs. Please speak to your network administrator to prepare a proper certificate. It is important that your new certificate contains a subjectAltName field, and that the value of this field matches the fully qualified domain name (FQDN) of your Intelligence Server. Once you have a certificate from your network administrator prepared, generate a certificate from a Root Certificate Authority (RCA).
 

Generating a Self-Signed Certificate 

• Shut down Apache Tomcat.
• Delete the existing certificate (

  .pem

  file) from LibraryWeb's

  WEB-INF

  folder. The default locations for each operating system are:
  
• Linux on AWS:

  /opt/apache/tomcat/latest/webapps/MicroStrategyLibrary/WEB-INF

• Windows:

  C:\Program Files (x86)\Common Files\MicroStrategy\apache-tomcat-9.0.30\webapps\MicroStrategyLibrary\WEB-INF

• In the Configuration Wizard, select Configure Intelligence Server and click Next
  

• On the SSL Configuration step, deselect the Configure SSL checkbox and go through the other configuration steps with your standard settings.
  

• After the Configuration Wizard finishes running, delete the certificate and key files, located in the following default locations:
  
• Linux on AWS:

  /opt/mstr/MicroStrategy/install/Intelligence Server/TLS

• Windows:

  C:\Program Files (x86)\MicroStrategy\Intelligence Server\TLS

• Re-run the Configuration Wizard and enabled TLS. This will generate a new certificate and key pair and start the Intelligence Server.
  

• Copy the new certificate to StrategyLibrary's

  WEB-INF

  folder (in the same location from step 2).
• Start Apache Tomcat.

Generating a Certificate from a Root Certificate Authority (RCA)

• Shut down Apache Tomcat. 
• Run the Configuration Wizard and enabled TLS.
• Change the certificate and key locations to point o the new certificate and key filed created by your network administrator.
  

• Copy the new certificate to StrategyLibrary's

  WEB-INF

  folder, replacing the existing certificate file in the following default location:
  
• Linux on AWS:

  /opt/apache/tomcat/latest/webapps/MicroStrategyLibrary/WEB-INF

• Windows:

  C:\Program Files (x86)\Common Files\MicroStrategy\apache-tomcat-9.0.30\webapps\MicroStrategyLibrary\WEB-INF

• Start Apache Tomcat.