FootPrints 11. - How to enable SSL/HTTPS for Executive Dashboard

Knowledge Article

FootPrints 11. - How to enable SSL/HTTPS for Executive Dashboard
FootPrints 11. - How to enable SSL/HTTPS for Executive Dashboard
FootPrints
FootPrints
FootPrints 11.6
FootPrints
FootPrints
FootPrints 11.6
How do I enable SSL/HTTPS for the Executive Dashboard
This procedure explains how to configure the Tomcat server and the Executive Dashboard to use https/SSL in FootPrints Service Core 11.6 or later, installed on Windows Servers 2003/2008.

Prerequisites:
  • PREPARATION:
    • It is advisable to read through this article in its entirety at least once before beginning the process in order to have any questions answered or steps clarified by FootPrints Service Core Technical Support.
  • CREDENTIALS:
    • Administrator access to the application/web server where FootPrints Service Core is installed.
  • TECHNICAL:
    • FootPrints Service Core version 11.6 or later must be installed. If FootPrints Service Core version 11.5.1 or earlier is currently installed, it must be upgraded to version 11.6 or later.
    • The website used for FootPrints Service Core 11.6 must be configured to use https/SSL prior to configuring the Tomcat server and the Executive Dashboard to use https/SSL.
    • The certificate used to secure the Footprints Service Core 11.6 website will need to be exported from Internet Information Services (IIS).

Procedure:
  1. Install or upgrade to (if an earlier version is already installed) FootPrints Service Core version 11.6.
     
  2. If it is not already, configure the website FootPrints Service Core runs on to use https/SSL. A commercially obtained certificate, such as that from Verisign or Thawte may be used, or a self-signed certificate can be used.
     
  3. In IIS, export the certificate with Private Key (PKCS #12 format - .pfx) used to secure the FootPrints Service Core website. Name the file IISToTomcat.pfx and make note of the location where the file was saved to. Also make note of the password you provided when exporting the certificate. NOTE: It is recommended the same password be used throughout the remainder of the steps below in order to avoid confusion. For the purposes of this procedure, assume a password of "MyTCpass1" (without doublequote characters) is used.
     
  4. Download and install the OpenSSL Light toolkit (v1.0.1e was available at the time of this writing):
    1. Access http://slproweb.com/products/Win32OpenSSL.html.
       
    2. Download the correct Visual C++ 2008 Restributables version for the bitness (32 or 64) of the FootPrints Service Core application server.
       
    3. Install the downloaded Visual C++ 2008 Restributables package.
       
    4. Download the correct OpenSSL Light toolkit for the bitness (32 or 64) of the FootPrints Service Core application server.
       
    5. Install the downloaded OpenSSL Light toolkit.
  5. Extract the certificate using OpenSSL - Open a command prompt on the server (use Run as Administrator) and cd to the bin folder of where OpenSSL was installed. By default, this would be C:\OpenSSL-Win32\bin (32 bit version) or C:\OpenSSL-Win64\bin (64 bit version).

    NOTE 1: When running commands below, a warning WARNING: can't open config file: /usr/local/ssl/openssl.cnf which may be displayed, can be safely ignored.

    NOTE 2: It will be assumed all files referenced below will be read from and created in the current directory (i.e. C:\OpenSSL-Win32\bin for 32 bit version or C:\OpenSSL-Win64\bin for the 64 bit version. If it is desired to read from or create the files in a different folder (such as C:\CERTFILES), create the folder and place the IIStoTomcat.pfx file in that folder. In this case, be sure to reference the full path to the file for the "-in" and "-out" options (i.e. -in C:\CERTFILES\IIStoTomcat.pfx, -out C:\CERTFILES\tomcat.cer, etc).
     
  6. Run the following command to extract the certificate using the exported IISToTomcat.pfx file as input and creating a file named tomcat.cer as output:
    • openssl.exe pkcs12 -in IIStoTomcat.pfx -clcerts -nokeys -out tomcat.cer
    When prompted for the password, use the one provided when the certificate was exported from IIS.
     
  7. Extract the encrypted private key by running the following command, using the exported IISToTomcat.pfx file as input, and Tomcat_Encrypted.key as output:
    • openssl.exe pkcs12 -in IIStoTomcat.pfx -nocerts -nodes -out Tomcat_Encrypted.key
    When prompted for the password, use the one provided when the certificate was exported from IIS.
     
  8. Decrypt the key by running the following command, using Tomcat_Encrypted.key as input and tomcat_private.key as input:
    • openssl.exe rsa -in Tomcat_Encrypted.key -out tomcat_private.key
    When prompted for the password, use the one provided when the certificate was exported from IIS.
     
  9. Combine the decrypted key and certificate into a PKCS12 keystore, using tomcat_private.key and tomcat.cer as input and tomcatStore.p12 as the output:
    • openssl.exe pkcs12 -export -inkey tomcat_private.key -in tomcat.cer -out tomcatStore.p12
  10. Import the PKCS12 keystore into a Java keystore:
    1. cd to C:\FootPrintsServiceCore\bin\Java\bin (NOTE: if FootPrints Service Core is installed to a location other than C:\FootPrintsServiceCore, adjust the path accordingly, i.e. D:\FPSC\bin\Java\bin, etc)
       
    2. Run the keytool utility to create a tomcat.jks file in the Tomcat\conf folder, located in FootPrints Service Core's bin folder, using the PKCS12 keystore file as input (both lines below should be entered as part of the same command - NOTE: the command below implies the "tomcatStore.p12" file is in the current working directory in which the command is being run from. In this case that is C:\FootPrintsServiceCore\bin\Java\bin. It is suggested to move the file into this directory or specify the path to it):
      • keytool.exe -importkeystore -srckeystore tomcatStore.p12 -srcstoretype PKCS12
        -destkeystore C:\FootPrintsServiceCore\bin\Tomcat\conf\tomcat.jks
  11. Change the alias in the java keystore from "1" to "Tomcat" (both lines below should be entered as part of the same command):
    • keytool.exe -changealias -alias 1 -destalias Tomcat -keystore C:\FootPrintsServiceCore\bin\Tomcat\conf\tomcat.jks
  12. Run the ConfigureTomcat.pl script to have FootPrints Service Core and Tomcat use SSL on port 8443 (a different port may be used if available):
    1. cd to C:\FootPrintsServiceCore\bin\Utilities\ExecutiveDashboard.
       
    2. run the following (both lines below should be entered as part of the same command):
      • C:\FootPrintsServiceCore\bin\perl\bin\perl ConfigureTomcat.pl --networkInterface *
        --networkPort 8443 --x64 --sslEnabled –openFirewall
      (NOTE: The "--x64" option should only be used on 64bit systems)
  13. Edit the C:\FootPrintsServiceCore\bin\tomcat\conf\fpServerConfig.xml file using a text editor such as notepad, Wordpad etc, and add the two parameters listed below to the "Connector":
    • keystoreFile="conf/tomcat.jks"
      keystorePass="MyTCpass1"

    port="8443"protocol="org.apache.coyote.http11.Http11Protocol"SSLEnabled="true"maxThreads="150"scheme="https"secure="true"connectionTimeout="20000"keystoreFile="conf/tomcat.jks"keystorePass="MyTCpass1"/>
    Ensure the value for the "keystorePass" parameter is the password that was used during the extraction/creation of the certificate when running the commands above.

    NOTE: When ConfigureTomcat.pl is run after having entered the keystoreFile="conf/tomcat.jks" and keystorePass="MyTCpass1" parameters in the fpServerConfig.xml file, the file will need to be re-edited to enter the parameters again. Therefore it is recommended to keep a backup copy of the file readily available with those parameters entered in the connector, so it can be used to easily replace the fpServerConfig.xml file overwritten by running ConfigureTomcat.pl
     
  14. Save the file.
     
  15. Restart the Tomcat Service on the server.

Verification:
At this point it should be possible to access the Executive Dashboard using a secure connection (https/SSL) by selecting Reports | Executive Dashboard from the Homepage's toolbar. Evidence of the secure connection being used can be verified by the following steps:
     
    • Select Reports | Executive Dashboard from the Homepage's toolbar.
       
    • When the dashboard loads, choose one of the actions below depending on the browser being used:

      Firefox:
      • Within the area where the Executive Dashboard displays, right-click and choose This Frame -> View Frame Info.

        The Address as shown in the "Frame Info" window should begin with "https://FPservername:8443/ExecutiveDashboard".
      Internet Explorer 8/9:
      • Within the area where the Executive Dashboard displays, right-click and choose Properties. This will display information about the frame.

        The Address (URL) should begin with "https" instead of "http".
      Chrome:
      • Press the F12 key to display the Developer Tools.

        Select the Sources tab in the Developer Tools console at the bottom of the page.
        FPservername:SecureTomcatPort should be seen on the left hand side of the Developer Tools panel, where FPservername:SecureTomcatPort is the server and port where FootPrints Service Core is accessed and the port used to secure Tomcat (i.e 8443).

      Allowing the browser to use self-signed certificates:
      The browser may present a warning about a self-signed certificate if one is used. Firefox will display: The certificate is not trusted because it is self signed. The following steps will add an exception:

      Firefox:
      1. Access Tools | Options
      2. Select the Advanced tab.
      3. Select Encryption.
      4. Press the View Certificates button.
      5. In the Certificate Manager window, select the Servers tab.
      6. Press the Add Exception button.
      7. Enter https://FPservername:8443 (replace "FPservername" with the hostname of the FootPrints Service Core site and "8443" with the actual port used in the steps above to secure Tomcat) in the Location field and press Get Certificate.
      8. Press the Confirm Security Certificate button.
      9. Press the OK button on the Certificate Manager window.
      10. Press the OK button on the Options window.
      11. Refresh the Executive Dashboard area or access it again.
      The warning should not appear again.

      Internet Explorer 8/9:
      Internet Explorer may display the following message in the area where the Executive Dashboard should display when a self-signed certificate is being used:

      Content was blocked because it was not signed by a valid security certificate.

      For more information, see "Certificate Errors" In Internet Explorer Help.

      The following will allow the browser to accept the certificate and display the dashboard.
         
        • Click the words Certificate error as it appears with a red background near the address bar of the browser.
        • Click View Certificates.
        • Press the Install Certificate... button in the Certificate dialog.
        • Press Next.
        • Select Place all certificates in the following store
        • Press the Browse... button
        • Select Trusted Root Certification Authorities and press the OK button.
        • Press Next.
        • Press Finish.
        • Press the Yes button on the Security Warning.
        • Press the OK button on the window with the The import was successful. message.
        • Press the OK button on the Certificate window.
        • Close the browser window and re-open it.
        • Log back in to FootPrints Service Core and access the Executive Dashboard and it should be accessible without any security related warnings.
        FootPrints
        FootPrints
        FootPrints 11.6
        Attachment(s):