Enabling SSL for the cluster management console using a self-signed certificate

Configure SSL for the cluster management console using a self-signed certificate for testing purposes.

Before you begin

  • The $JAVA_HOME environment variable must be set correctly on the host where the WEBGUI service is running.
  • You must be a cluster administrator.
  • You must ensure that the clock settings on the server and client are identical. Otherwise, errors may occur.
Tip: To automatically enable SSL for the cluster management console, see Enabling SSL with the SSL tool. Use the SSL tool generate SSL server certificates to encrypt information, and then configuring components to use those certificates for SSL. The SSL tool provides both of these functions.

About this task

Follow these steps if you want to complete these tasks:
  • Enable SSL for the first time (in other words, if you disabled SSL during installation by setting DISABLESSL=Y).
  • Use your own self-signed certificate that will replace the default one generated when SSL is enabled during installation.

When SSL is enabled for the cluster management console web service (WEBGUI), a trust relationship between the server and the client is established by sending a server certificate to the client. The client validates the certificates that are signed by the self-signed Platform Computing CA Root. This self-signed certificate can be used only for testing purposes. For your production environment, use a properly chained certificate that is issued or signed by a trusted certificate authority. By default WEBGUI uses the TLSv1.2 protocol.

Important: You must use the same SSL setting for the cluster management console and the RESTful web servers. If you enable SSL for one, you must also enable SSL for the other; if you disable SSL for one, SSL must be disabled for the other as well. This setting also takes effect for cloud bursting with host factory. Ensure that SSL for all these functions is configured consistently in the cluster; without a uniform configuration, errors occur. When SSL is uniformly enabled, you can use different certificates and keys as required.
Note: On a local file system, files must be generated on all management hosts. On a shared file system, the files need to be generated on a shared file system location that all management hosts can access. Also, the subjectAltName (SAN) field must contain all management hosts.

Procedure

  1. Stop the WEBGUI service: 
    egosh service stop WEBGUI
  2. If you want to manage your own certificates, use the keytool utility to clean up the certificate in the default server keystore (serverKeyStore.jks):
    Note: This step is required only if SSL was previously enabled (thus, generating the serverKeyStore.jks). In this case, you must clean up the certificate.
    1. Back up the default server keystore :
      • Linux®: $EGO_TOP/wlp/usr/shared/resources/security/serverKeyStore.jks
      • Windows: Installation_top\wlp\usr\shared\resources\security\serverKeyStore.jks
    2. Change to the /bin directory under your Java™ directory:
      • Linux: 
        cd $EGO_TOP/jre/jre_version/linux-x86_64/bin

        where the jre_version for IBM® Spectrum Symphony 7.3.1 is 8.0.6.0.

      • Windows: 
        cd Installation_top\jre\jre_version\bin

        where the jre_version for IBM Spectrum Symphony 7.3.1 is 8.0.6.0.

    3. List the certificates in the keystore and identify its alias. For example: 
      keytool -v -list -keystore serverKeyStore.jks -storepass storepass
      where storepass specifies the keystore password; for example: Liberty.
      In the following example, the generic domain certificate uses the alias srvalias:
          ...
    Alias name: srvalias
    Creation date: Nov 5, 2015
    Entry type: keyEntry    
    Certificate chain length: 2
    ...
    4. Remove the certificate from the keystore. For example: 
      keytool -delete -alias srvalias -keystore serverKeyStore.jks -storepass storepass
      where storepass specifies the keystore password; for example: Liberty.
    5. To remove the Root certificate in the keystore, list the certificates to look for the Root certificate. Look for the one whose Owner and Issuer has the value of CN=Platform Root CA (SHA256), O=Platform, C=CA. 
      keytool -v -list -keystore serverKeyStore.jks -storepass storepass
      where storepass specifies the keystore password; for example: Liberty.
      In the following example, the external certificate uses the alias caalias:
         ...
    Alias name: caalias
    Creation date: Nov 5, 2015
    Entry type: trustedCertEntry
    
    Owner: CN=Platform Root CA (SHA256), O=Platform, C=CA    
    Issuer: CN=Platform Root CA (SHA256), O=Platform, C=CA
    ...
    6. Delete the Root certificate from the keystore 
      keytool -delete -alias caalias -keystore serverKeyStore.jks -storepass storepass
      where storepass specifies the keystore password; for example: Liberty.
  3. Generate a self-signed certificate using the keytool utility:
    Important: When you run keytool, the server keystore is generated in a local directory, not in a shared directory. If the WEBGUI service is configured to use the ManagementHosts resource group or you have customized the host list, ensure that you complete these steps on all management hosts, so that the keystore is available on all management hosts.
    1. From the /bin directory under your Java directory, generate a key pair for the server keystore: 
      keytool -genkeypair -noprompt -alias srvalias -dname "CN=*.domainName,O=Platform,C=CA" -keystore serverKeyStore.jks  
-storepass storepass -keypass keypass -keyalg rsa -validity 825 -keysize  2048 -sigalg SHA256withRSA 
[-ext "san=dns:hostname1,dns:hostname2,..."]
      where:
      • -dname domainName identifies the fully qualified domain of the cluster management console web server. For example, if the cluster management console host name is myhostname.example.com, then the domainName is example.com. Ensure that the domain name does not start with a number.
      • -storepass storepass specifies the password to protect the integrity of the keystore (for example: Liberty) and -keypass keypass specifies the password for the keystore (for example: Liberty). It is recommended that you use the same password for both options.
      • -alias is set to use srvalias.
      • -ext "san=dns:hostname" specifies the host name to which the certificate must apply as the subjectAltName (SAN). The name of the primary host that is defined during installation is added automatically as the subjectAltName. If you installed your cluster to a shared file system and primary host failover is enabled, add the names of all your primary-candidate hosts (-ext "san=dns:hostname1,dns:hostname2,...").
        Note: If you add primary-host candidates after the certificate is first generated, you must generate a new certificate to include the host names of the newly added primary-host candidates.
    2. Create the certificate-signing request (.csr file): 
      keytool -certreq -alias srvalias -file srvcertreq.csr -storepass storepass -keystore serverKeyStore.jks 
[-ext "san=dns:hostname1,dns:hostname2,..."]

      where storepass specifies the keystore password; for example: Liberty.

    3. Retrieve and save the following CA key and the CA root certificates:
      • Linux:
        • $EGO_TOP/wlp/usr/shared/resources/security/cacert.pem
        • $EGO_TOP/wlp/usr/shared/resources/security/caKeyStore.jks
      • Windows:
        • Installation_top\wlp\usr\shared\resources\security\cacert.pem
        • Installation_top\wlp\usr\shared\resources\security\caKeyStore.jks
    4. Sign the certificate using the CA key: 
      keytool -gencert -infile srvcertreq.csr -outfile servercertcasigned.pem -alias caalias -keystore caKeyStore.jks_location 
-storepass storepass -validity 825 -keysize 2048 -sigalg SHA256withRSA -keyalg rsa 
[-ext "san=dns:hostname1,dns:hostname2,..."]
      where:
      • caKeyStore.jks_location is the path to the caKeyStore.jks file that you saved previously.
      • storepass specifies the keystore password; for example: Liberty.
    5. Import the CA root certificate to the server keystore: 
      keytool -importcert -noprompt -alias caalias -file cacert.pem_location -keystore serverKeyStore.jks -storepass storepass
      where:
      • cacert.pem_location is the path to the cacert.pem file that you saved previously.
      • storepass specifies the keystore password; for example: Liberty.
    6. Import the signed certificate back into the keystore: 
      keytool -importcert -noprompt -alias srvalias -file servercertcasigned.pem -storepass storepass -keystore serverKeyStore.jks
      where storepass specifies the keystore password; for example: Liberty.
    7. Copy the serverKeyStore.jks file to the /security directory:
      • Linux: $EGO_TOP/wlp/usr/shared/resources/security/
      • Windows: Installation_top\wlp\usr\shared\resources\security\
  4. Configure SSL settings in the server_gui.xml configuration file:
    1. Copy the SSL settings from server_gui.xml.ssl to server_gui.xml:
      • Linux: $EGO_CONFDIR/../../gui/conf/
      • Windows: %EGO_CONFDIR%\..\..\gui\conf\
    2. Edit server_gui.xml:
      • Linux: $EGO_CONFDIR/../../gui/conf/server_gui.xml
      • Windows: %EGO_CONFDIR%\..\..\gui\conf\server_gui.xml
    3. Define the default keystore with the password and its location in the keyStore element. 
      <keyStore id ="defaultKeyStore" password="storepass" location="${wlp.user.dir}/shared/resources/security/serverKeyStore.jks"/>
      where storepass specifies the keystore password; for example: Liberty.
    4. Optional: Encrypt the password using the securityUtility command. For more information, see Liberty profile: securityUtility command.
    5. Save your changes to server_gui.xml.
  5. Start the WEBGUI service: 
    egosh service start WEBGUI
  6. From your browser, log in to the cluster management console using SSL on port 8443 (for example: https://webguiserver.example.com:8443/platform).
  7. When the browser prompts you about an untrusted connection, download and import the web server certificate:
    1. Obtain the certificate from the server at:
      • $EGO_TOP/wlp/usr/shared/resources/security/cacert.pem
      • Installation_top\wlp\usr\shared\resources\security\cacert.pem
      Note: As the cluster administrator, ensure that you distribute this certificate to all your users who require access to the cluster management console.
    2. Import the certificate for your browser:

      The following steps apply only if you are using the default self-signed certificate with the certified browsers; the steps might be different with other browser versions.

      • If you are using Chrome on Windows, complete the following steps:
        1. From the browser, click Settings > Advanced > Privacy and Security > Manage Certificates > Import.
        2. Follow the Certificate Import Wizard, import the downloaded cacert.pem, click Place all certificates in the following store, click Browse, select Trusted Root Certification Authorities, and click OK.
        3. Complete the wizard and accept any additional prompts.
        4. Restart the browser, if required.
      • If you are using Chrome on Mac OS, complete the following steps. You are required to enter your Keychain password for some of these steps:
        1. Double-click the cacert.pem file in the Finder.
        2. In the Add Certificates window, select System from the Keychain drop-down menu.
        3. Click Add.
        4. In the Keychain Access window, select the System tab and double-click the imported certificate.
        5. Under Trust, select Always Trust for all of the drop-down options.
        6. Exit the Keychain and restart the browser.
      • If you are using Firefox on Windows or Linux, complete the following steps:
        1. Click Add Exception.
        2. In the Add Security Exception dialog, click View.
        3. In the Certificate Viewer dialog, click the Details tab.
        4. Select IBM Spectrum Computing Root CA (SHA256) and click Export.
        5. Save the certificate (IBM Spectrum ComputingRootCA(SHA256).crt) to a local directory.
        6. Click Tools > Options > Advanced.
        7. On the Certificates tab, click View Certificates.
        8. On the Authorities tab, click Import.
        9. Select the certificate from the location where it is saved on your system.
        10. When prompted to trust a new CA, ensure that you select Trust this CA to identify websites and click OK.
        11. Restart the browser, if required.
      • If you are using Firefox on Mac OS, complete the following steps:
        1. Click Firefox > Preferences > Advanced > View Certificates.
        2. Click the Authorities tab and click Import.
        3. Select the certificate from the location where it is saved on your system.
        4. When prompted to trust a new CA, ensure that you select Trust this CA to identify websites and click OK.
        5. Restart the browser, if required.
      • If you are using Internet Explorer, complete the following steps:
        1. When the browser prompts you about a security certificate, click Continue to this website (not recommended).
        2. Click Certificate error in the address bar; then, View Certificates.
        3. In the Certificate dialog, click the Certification Path tab.
        4. Select IBM Spectrum Computing Root CA (SHA256) and click View.
        5. If all looks well, click the General tab and click Install Certificate....
        6. In the Certificate Import Wizard, click Place all certificates in the following store, click Browse, select Trusted Root Certification Authorities, and click OK.
        7. Complete the wizard and accept any additional prompts.
        8. Restart the browser, if required.

Results

You can now securely access the cluster management console over SSL in your development environment.