SSL Support for Analytics Server APIs
Beginning in ThingWorx Analytics, release 8.5.0, SSL authentication support is available to protect access to the internal ThingWorx Analytics API layer. This type of SSL support is available to secure interactions between the ThingWorx Adapter for Analytics Server, or another client, and the Analytics microservice APIs. It also secures interactions between the individual APIs themselves.
If you plan to use SSL authentication for API access, a signed SSL certificate must be in place before you deploy ThingWorx Analytics Server. You can obtain an SSL certificate from any trusted Certificate Authority, or you can follow the procedure below to generate a self-signed certificate.
Generate a Self-signed Certificate
1. Depending on your operating system, open a terminal window as the root user, or open the Windows PowerShell in Administrator mode.
2. Navigate to the JRE bin folder in your Java installation directory. The path to this installation can vary from one operating system version to another.
 |
Linux Example: /opt/java/jdk1.8.0_161/jre/bin
Windows Example: C:\Program Files\Java\jdk1.8.0_161\jre\bin
|
3. Run the following command to create a certificate using the Java Keytool utility:
keytool -genkeypair -alias <alias name> -validity <length of certificate validity> -keyalg RSA -keysize 2048 -keystore <keystore name>.jks -ext SAN=<IP or DNS>:<IP Address or FQDN of your Analytics Server Primary Adapter>
|
|
Sample command using IP address:
keytool -genkeypair -alias analytics-server -validity 365 -keyalg RSA -keysize 2048 -keystore keystore.jks -ext SAN=IP:192.168.56.101
Sample command using fully qualified domain name (FQDN):
keytool -genkeypair -alias analytics-server -validity 365 -keyalg RSA -keysize 2048 -keystore keystore.jks -ext "SAN=DNS:TWA-QA-Win-2012" TWA-QA-Win-2012 :FQDN
Note: The SAN=IP parameter must contain a specific IP address or an FQDN for the Analytics server.
|
The system prompts you for answers to a series of questions. See the sample images below.
4. The questions may vary depending on the version of your operating system, but provide the following important information:
◦ Enter a Keystore Password and re-enter it to confirm it.
◦ For the next question, which might ask for Host Name or First and Last Name, enter the SAN IP address you entered in the certificate creation command above.
◦ Confirm that all of the entries are correct.
◦ To assign the same password to the Key that you entered for the Keystore, press the Return key.
When the command is executed, a keystore file (.JKS) is created at the keystore file path you specified. Inside the keystore, the self-signed certificate is generated with the Alias Name specified in the command above.
Figure 1. Linux sample:
Figure 2. Windows sample:
During Analytics Server Installation
As part of the ThingWorx Analytics Server installation process, if you choose to enable SSL authentication for the APIs, your signed certificate will be stored in the Java Keystore. During the installation, you will be prompted to provide certain information from your authentication certificate. Be prepared to provide the following:
• Location of the Keystore file (.JKS file)
• Password assigned to both the Keystore and the Key
• Alias Name assigned to the certificate