Configure OneClick for Secure Sockets Layer

Contents
casp1041
OneClick supports the Secure Sockets Layer (SSL) protocol to encrypt communications between the OneClick web server and OneClick clients. OneClick clients can access information securely across unsecured networks, such as the Internet. In addition to encryption, SSL uses certificates for authentication. Authentication protects users from downloading and running applications from suspicious or "untrusted" sources.
Both Certificate Authority-signed certificates and self-signed certificates provide secure connections using SSL encryption. However, certificates signed by a Certificate Authority provide an additional level of security. These certificates verify the creator of the certificate and certify that the product is truly from that vendor. Certificates that are signed by a Certificate Authority protect servers by making it difficult to impersonate a trusted entity (the certified vendor). However, self-signed certificates are appropriate if you require the encryption that an SSL certificate provides without requiring proof of the certificate source.
After upgrading to
DX NetOps Spectrum
10.3, when you configure OneClick for SSL, you will see a warning message to migrate JKS to PKCS12 format. Please ignore this warning and do not migrate to PKCS12 format.
The tomcat bundled with
DX NetOps Spectrum
10.3, requires at least one trusted cert in a keystore, for it to work.
Follow these steps:
  1. On the OneClick web server host, change to the
    $SPECROOT
    /Java/bin directory.
  2. Generate a private self-signed certificate in the custom cacerts file by issuing the following command:
    ./keytool -genkey -alias tomcatssl -keyalg RSA -keystore c:/win32app/Spectrum/custom/keystore/cacerts
    The keytool prompts with a series of questions and uses the values that you specify to perform the following actions:
    • Create an issuer name for your organization (This name is an X.500 Distinguished Name that is intended to be unique across the Internet. For more information, see the keytool utility at http://java.sun.com).
    • Generate the self-signed certificate using the issuer name.
      In case the keystore is not saved to $SPECROOT/custom/keystore, it is overwritten during an upgrade.
  3. Enter your answers to the following questions:
    Enter keystore password:
    If you change the default password for the Tomcat web server, specify the custom password in the
    $SPECROOT
    /tomcat/conf/server.xml configuration file.
    What is your first and last name?
    Enter the common name (with the fully qualified domain name) of your website. For example, www.ca.com.
    What is the name of your organizational unit?
    Enter a small organization name, such as the name of a division, business unit, or department. For example, Purchasing.
    What is the name of your organization?
    Enter a large organization name, such as ABCSystems, Inc.
    What is the name of your City or Locality?
    Enter your city name, such as Hyderabad.
    What is the name of your State or Province?
    Enter the full name, such as Andhra Pradesh.
    What is the two-letter country code for this unit?
    Enter the two-letter country code. For example, IN.
    Is CN=www.ca.com, OU=Purchasing, O="ABCSystems, Inc.", L=Hyderabad, ST=Andrapradesh, C=IN correct?
    Enter Yes.
    Enter key password for <tomcatssl> (RETURN if same as keystore password):
    Enter key password for <tomcatssl>. Press Enter to use the same password as the keystore password.
    After adding the tomcatssl key, ensure you take a backup of the $SPECROOT/custom/keystore/cacerts file, in case the keystore gets corrupted.
  4. (Optional) If you require a certificate that is signed by a Certificate Authority, request the certificate from the Certificate Authority and then import it.
    Before proceeding with this step (Step 4), as a best practice, skip to Step 5 and set up SSL. You can then test to determine whether the information that you provided in the previous step was correct. If HTTPS works, you can continue with this step.
    As part of certificate configuration, generate a Certificate Signing Request (CSR) file from the system that runs the secure OneClick web server. The Java Development Kit (JDK) that is included with OneClick provides a keytool utility that you can use to generate the CSR file. Use the information that you provided in the previous step. Use the same alias name as tomcatssl.
  5. Request and import the Certificate Authority-signed certificate as follows:
  6. On the OneClick web server host, change to the
    $SPECROOT
    /Java/bin directory.
    1. Generate the CSR file by entering the following command:
    ./keytool -certreq -alias tomcatssl -keystore $SPECROOT/custom/keystore/cacerts -file filename.csr
    You are prompted for a password. Use the same password that you provided earlier.The contents of the .csr file that is generated are used to request the secure certificate from the Certificate Authority (the next step).
    Request a secure certificate from a Certificate Authority. Verify the following examples:
    VeriSign: http://www.verisign.com
    TrustCenter: http://www.trustcenter.de
    thawte: http://www.thawte.com
    Instructions are available at these websites.
    Import the Certificate Authority-signed certificate into the keystore that is used by the OneClick web server. For more information, see Import a Certificate Authority-Signed Certificate.
  7. Configure the secure socket on the server that hosts the OneClick web server. For more information, see Configure the Secure Socket on the OneClick Web Server Host.
  8. If you are running Report Manager, configure OneClick to be launched from Report Manager using SSL. For more information, see Configure OneClick and Report Manager for Secure Sockets Layer.
Import a Certificate Authority-Signed Certificate
If you have obtained a Certificate Authority-signed SSL certificate, import it into the keystore that the OneClick web server uses.
A chain (root) certificate from the Certificate Authority must also exist in the keystore. By default, OneClick includes chain certificates from many popular vendors. Click List on the SSL Certificates administration page to view the aliases for these certificates. This information helps you determine whether to obtain one and import it.
Follow these steps:
  1. If necessary, download a chain (root) certificate from the Certificate Authority from which you obtained the signed certificate.
  2. If you downloaded a chain certificate in the previous step, import it into the keystore used by the OneClick web server:
    1. On the OneClick web server host, change to the
      $SPECROOT
      /Java/bin directory.
    2. Enter the following command:
      ./keytool -import -alias root -keystore $SPECROOT/custom/keystore/cacerts -trustcacerts -file root_chain_certificate_filename
      You are prompted for a password for the Tomcat web server. The alias name does not have to be 'root'. You can supply a more descriptive name for the type of root certificate that you are importing. The alias name cannot already exist.
  3. Import the Certificate Authority-signed SSL certificate into the keystore used by the OneClick web server:
    1. If necessary, on the OneClick web server host, change to the
      $SPECROOT
      /Java/bin directory.
    2. Enter the following command:
      ./keytool -import -alias tomcatssl -keystore $SPECROOT/custom/keystore/cacerts -trustcacerts -file your_certificate_filename
      You are prompted for a password for the Tomcat web server. Use the same alias that you used when you generated the private self-signed certificate. See Name Resolution Requirements for more information.
      keytool can import X.509 v1, v2, and v3 certificates, and PKCS#7 formatted certificate chains consisting of certificates of that type.  Please verify that the certificate from CA is of this type.
(Optional) Log in Using Non-Fully Qualified Domain Name
SSL security forces you to use the fully qualified domain name of your OneClick server for login. For example:
https://oneclick.ca.com/spectrum
. To log into the non-fully qualified domain name (for example:
https://oneclick/spectrum
), or a DNS entry that is different than the local OneClick server name, use a SAN (Subject Alternate Name) with the -ext option:
./keytool -genkey -alias tomcatssl -keyalg RSA -keysize 2048 -ext SAN=dns:oneclick -keystore c:/win32app/Spectrum/custom/keystore/cacerts
Modify JVM Arguments when SSL is Enabled
Perform the procedure described in the Post Upgrade Tasks section on the OneClick WebApp (Beta) page, in case you enabled SSL in OneClick or changed the OneClick ports after you upgraded to
DX NetOps Spectrum
10.4 or higher.
To disable the non-HTTPS connector port, see the KB Article: Block access to HTTP on port 80 (Windows) or port 8080 (Linux) in Spectrum OneClick.
Configure the Secure Socket on the OneClick Web Server Host
Configure the secure socket on the server that hosts the OneClick web server. Consider this task as the final step in configuring the OneClick web server for SSL.
DX NetOps Spectrum
supports the use of SSL v3.
Follow these steps:
  1. Shut down the OneClick web server.
  2. Open $SPECROOT/tomcat/conf/server.xml in your preferred text editor.
  3. Locate the following section in the server.xml file:
    <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 --> <!-- <Connector port="8443" enableLookups="true" disableUploadTimeout="true" tcpNoDelay="true" acceptCount="100" scheme="https" secure="true" SSLEnabled="true" clientAuth="false" sslProtocol="TLS" sslEnabledProtocols="TLSv1.2" ciphers="TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_DHE_RSA_WITH_AES_128_GCM_SHA256, TLS_DHE_RSA_WITH_AES_256_GCM_SHA384, TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_256_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA256, TLS_DHE_RSA_WITH_AES_256_CBC_SHA256" keystoreFile="custom/keystore/cacerts" keystorePass="changeit"> </Connector> -->
    By default, the <Connector> element in the section is commented out.
    The preceding XML fragment is Windows-specific, with 443 as the default port where the OneClick web server listens for SSL communications. End users can omit the port from the URL for accessing the OneClick home page:
    https://<fully_qualified_host_name>/spectrum
    On a UNIX-based installation, the OneClick web server is not run as root, and the default port is 8443 (because it must be greater than 1024). As a result, end users must specify the port number in the web browser when they enter the URL to access the OneClick home page:
    https://<fully_qualified_host_name>:8443/spectrum
  4. Remove the comments around the Connector definition. Perform the following actions:
    1. Remove "<!--" from the line preceding to <Connector.
    2. Remove "-->" from the end of the section (after </Connector>).
  5. Replace the <
    SPECROOT
    > variable in the value for the keystoreFile attribute with the fully qualified path to the directory where
    DX NetOps Spectrum
    is installed. You can use the cacerts file for the keytool commands to generate the certificates. Verify the following examples:
    • Windows
      C:/win32app/SPECTRUM/custom/keystore/cacerts
    • UNIX
      /usr/SPECTRUM/custom/keystore/cacerts
  6. Save and close the server.xml file.
  7. If you have
    DX NetOps Spectrum
    integrated with CA Performance Center, perform the following steps to enable the communication between SSL enabled OneClick and CA Performance Center:
    1. Open the "axis2.xml" file in an editor from "$SPECROOT/tomcat/webapps/axis2/WEB-INF/conf".
    2. Locate the following section in axis2.xml:
      <transportReceiver name="http" class="org.apache.axis2.transport.http.AxisServletListener"> <parameter name="port">8080</parameter> </transportReceiver>
    3. Change the section as follows:
      <transportReceiver name="https" class="org.apache.axis2.transport.http.AxisServletListener"> <parameter name="port">8443</parameter> </transportReceiver>
      If you need to configure both HTTP and HTTPS, it is necessary to explicitly configure the port numbers in axis2.xml, such as in the following example:
      <transportReceiver name="http" class="org.apache.axis2.transport.http.AxisServletListener"> <parameter name="port">8080</parameter> </transportReceiver> <transportReceiver name="https" class="org.apache.axis2.transport.http.AxisServletListener"> <parameter name="port">8443</parameter> </transportReceiver>
  8. Start the OneClick web server.
    You can find instructions on configuring SSL and configuration parameters. For more information, see http://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html.
To disable the non-HTTPS connector port, see the KB Article: Block access to HTTP on port 80 (Windows) or port 8080 (Linux) in Spectrum OneClick.
Configure OneClick and Report Manager for Secure Sockets Layer
If you are running Report Manager and you have configured OneClick to use the Secure Sockets Layer (SSL) protocol to encrypt communications between OneClick clients and the OneClick web server, you must also configure OneClick to be launched from Report Manager using SSL.
Report Manager allows you to create reports on the inventory, performance, change history, and fault history of the network assets managed by
DX NetOps Spectrum
. For more information, see Report Manager.
Follow these steps:
  1. Enable write permissions on the following file:
    <$SPECROOT>\tomcat\webapps\spectrum\repmgr\js\repmgr.js
  2. Open the file that you modified in the previous step, and locate the launchOneClick function.
  3. Locate the following line in the launchOneClick function:
    url = "http://"+servername+contextApp+"/oneclick.jnlp";
  4. Change "http" to "https" as follows:
    url = "https://"+servername+contextApp+"/oneclick.jnlp";
  5. Save and close the file.
    This file is overwritten during an upgrade. Repeat this procedure after an upgrade.
You can launch OneClick in the context of a specific report (for example, in the context of a device that is listed in an asset report). However, this type of launch cannot be configured to use SSL.
Unable to connect to OneClick using https after upgrading to 10.3
Symptom:
After upgrading to
DX NetOps Spectrum
10.3, unable to connect to OneClick using the https connection.
This problem occurs due to the migration of JKS to PKCS12 format. After generating the SSL key, the following message appears, which recommends to migrate JKS to PKCS12 format:
The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS 12 which is an industry standard format using "keytool -importkeystore -srckeyst ore c:/win32app/SPECTRUM/custom/keystore/cacerts -destkeystore c:/win32app/SPECT RUM/custom/keystore/cacerts -deststoretype pkcs12".
Solution:
We recommended to ignore this warning message and do not migrate to PCKS12 format. In case you have already migrated, then replace the backed up keystore while migrating to PKCS12 format and restart Tomcat.
Follow these steps:
  1. While migrating to PKCS12 format, the old keystore gets backed up as /usr/Spectrum/custom/keystore/cacerts.old
  2. Remove or backup the file /usr/Spectrum/custom/keystore/cacerts and rename cacerts.old to cacerts at /usr/Spectrum/custom/keystore/
  3. Restart tomcat.
Error when logging into OneClick web configured for SSL
Symptom:
After configuring the
DX NetOps Spectrum
OneClick server for SSL, an error is thrown when attempting to connect from a browser (Chrome, FireFox, IE or Safari).
This error occurs due to the URL being used to point the browser at the OneClick server. The URL contains either an IP address or hostname that does not match that which was used to generate the certificate that was added to the OneClick server keystore. Or alternately, the DNS lookup does not resolve to the correct name/IP.
Solution:
Follow these steps:
  1. When generating the private, self-signed certificate, you use the following command:
    ./keytool -genkey -alias tomcatssl -keyalg RSA -keystore $SPECROOT/custom/keystore/cacerts
    This command then asks a number of questions, the second of which is:
    What is your first and last name?
    This refers to the common name (singular hostname) or the FQDN of the OneClick server . So when logging in with the browser, you need to refer to this hostname in the URL (not the IP address) for the HTTPS connection to work and the certificate to be validated by the browser.
  2. Import the certificate signed by your CA:
    $SPECROOT/Java/bin> ./keytool -import -alias tomcatssl -keystore $SPECROOT/custom/keystore/cacerts -trustcacerts -file <PATH>/<FILENAME.cer>
  3. Enter the keystore password. The certificate reply was installed in the keystore. If your DNS is not resolving the hostname of the OneClick server, then modify your hosts file (In Windows: ~\win32\drivers\etc\hosts, in Linux/etc/hosts) file to include both the singular and FQDN hostnames of the OneClick server so as to get around the problems with your DNS. Then in the browser, target the OneClick server URL using:
    https://<HOSTNAME>:443/spectrum
Errors Connecting to the Secure OneClick Web Server from a OneClick Client Using SSL
Symptom:
I am encountering errors when I try to connect to the secure OneClick web server from a OneClick client using SSL.
Solution:
Verify the following:
  • The fully qualified domain name of the host on which the OneClick web server is running was specified in the private key you generated for signing the security certificate used for authentication. When you generated the key, you should have entered the fully qualified domain name at the following prompt: “What is your first and last name?”
  • Both the Certificate Authority chain (root) certificate
    and
    the security certificate were imported into the cacerts file in the custom directory on the secure OneClick web server.
Errors Launching OneClick Client from Report Manager Using SSL
Symptom:
I am encountering errors when I launch a OneClick client from Report Manager using SSL.
Solution:
Verify that you have completed the configuration procedure described in Configure OneClick and Report Manager for Secure Sockets Layer.