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

To manually enable SSL for the cluster management console using a self-signed certificate, you must ensure that:

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.

Alternatively, to automatically enable SSL, see Enabling SSL with the SSL tool.

About this task

Follow these steps if you want to:

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. Note, however, that when SSL is uniformly enabled, you can use different certificates and keys as required.

Note: On a local file system, Tier 1 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

Stop the WEBGUI service:
```
egosh service stop WEBGUI
```
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. This step also uses the keytool utility distributed by the IBM® Spectrum Conductor Java distribution.
1. Back up the default server keystore ($EGO_TOP/wlp/usr/shared/resources/security/serverKeyStore.jks)
2. Change to the /bin directory under your Java™ directory:
```
cd $EGO_TOP/jre/8.0.6.0/linux-x86_64/bin
```
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=IBM Spectrum Computing Root CA (SHA256), O=IBM, 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=IBM Spectrum Computing Root CA, O=IBM, C=CA    
    Issuer: CN=IBM Spectrum Computing Root CA, O=IBM, 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.
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 (for example, $EGO_CONFDIR/../../jre/3.9/linux-x86_64/bin), generate a key pair for the server keystore:
```
keytool -genkeypair -noprompt -alias srvalias -dname "CN=*.domainName,O=IBM,C=CA" -keystore serverKeyStore.jks  
-storepass storepass -keypass keypass -keyalg rsa -validity 825 -keysize  2048 -sigalg SHA256withRSA 
-ext "san=dns:hostname"
```
  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 value is example.com.
  - -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 all management host names to which the certificate must apply as the subjectAltName (SAN). The primary host that is defined during installation is automatically added as the SubjectAltName. If you installed your cluster to a shared file system and enabled primary host failover, add the names of all your primary-candidate hosts (-ext "san=dns:hostname1,dns:hostname2,...").
    Note: If you add primary-candidates after the certificate is first generated, you must generate a new certificate to include the host names of the newly added primary-candidates.
2. Create the certificate-signing request (.csr file):
```
keytool -certreq -alias srvalias -file srvcertreq.csr -storepass storepass -keystore serverKeyStore.jks 
-ext "san=dns:hostname"
```
  where storepass specifies the keystore password; for example: Liberty.
3. Retrieve and save the following CA key and the CA root certificates:
  - INSTALL_TOP/wlp/usr/shared/resources/security/cacert.pem
  - INSTALL_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:hostname"
```
  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: $EGO_TOP/wlp/usr/shared/resources/security/
Configure SSL settings in the server_gui.xml configuration file:
1. Copy the SSL settings from $EGO_CONFDIR/../../gui/conf/server_gui.xml.ssl to $EGO_CONFDIR/../../gui/conf/server_gui.xml.
2. Edit $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 securityUtilities command. For more information, see: Liberty profile: securityUtility command
5. Save your changes to server_gui.xml.
Start the WEBGUI service:
```
egosh service start WEBGUI
```
From your browser, log in to the cluster management console using SSL on port 8443 (for example: https://webguiserver.example.com:8443/platform).
When the browser prompts you about an untrusted connection, download and import the web server certificate:
1. With the appropriate permissions and access, obtain the certificate from the server file system at $INSTALL_TOP/wlp/usr/shared/resources/security/cacert.pem.
2. Configure 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. 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 Tools > Options > Advanced.
    2. On the Certificates tab, click View Certificates.
    3. On the Authorities tab, click Import.
    4. Select the certificate from the location where it is saved on your system.
    5. When prompted to trust a new CA, ensure that you select Trust this CA to identify websites and click OK.
    6. 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.

Results

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