Enabling SSL for the cluster management console using an external certificate

Configure SSL for the cluster management console in your production environment using a properly chained certificate from a trusted certificate authority (CA).

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.

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 a properly chained certificate from a trusted CA that replaces the default self-signed certificate 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 a trusted CA. For your production environment, ensure that you use a properly chained certificate that is issued or signed by a trusted CA. 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:

This procedure uses keytool and openssl commands solely for purposes of demonstration. For proper certificate handling, follow the instructions of the CA vendor generating your certificate.
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

Stop the WEBGUI service:
```
egosh service stop WEBGUI
```
For keytool users only: 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 keytool users only: Generate a keystore for the cluster management console server and create a certificate-signing request file, using keytool.

Note: When you use 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, run the following command to generate a keystore:
```
keytool -genkeypair -alias srvalias -keyalg RSA -keysize 2048 -keystore keystore_name.jks
```
  where keystore_name is the name of your new keystore. You can optionally reuse the default server keystore (serverKeyStore.jks) after cleanup (see step 2).
  
  Ensure that -alias is set to use srvalias.
2. When prompted for the keystore password, enter a password for the keystore_name.jks file.
3. When prompted for the last and first name, enter the FQDN of the cluster management console host; for example, myhostname.example.com. Ensure that the domain name does not start with a number.
  Important: Follow the instructions of the CA vendor generating your certificate for specific information on different fields. Some certificate vendors might state that the L (Location), ST (State), and C (Country) fields cannot be blank; other vendors might require the country value (C) to be uppercase. For example:
```
CN=*.eng.platformlab.ibm.com, OU=Platform Computing, O=IBM, L=Markham, ST=ONT, C=CA
```
4. Answer all other questions.
5. Create the certificate-signing request file:
```
keytool -certreq -alias srvalias -file keystore_name.csr -keystore keystore_name.jks
```
  where:
  - keystore_name.csr is the certificate-signing request file that you require to order an SSL certificate from your CA vendor.
  - keystore_name.jks is the name of your keystore.
Contact your CA vendor to create an SSL certificate. For keytool users, your vendor will need the keystore_name.csr file that you created in step 3.

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.
Once your vendor approves your request, follow the vendor-provided instructions to download the certificate. If you are using keytool, download the certificate in.der format; if you are using openssl, download it in .crt format.
For recovery purposes, back up your SSL files to a secure location. These files include your keystore file (keystore_name.jks), your certificate (for example, cert.der or cert.crt), and optionally, the certificate-signing request file (keystore_name.csr). If you run into any issues when configuring SSL for your production environment, restore your backup files and redo the procedure from the next step.
Import your server certificate to a keystore. If your CA vendor provided instructions, you must follow those instructions.
- If you are using keytool, import your server certificate as follows:
```
keytool -importcert -trustcacerts -alias srvalias -keystore keystore_name.jks -file certificate
```
  where certificate is your certificate in .der format (for example, cert.der), which you downloaded from your CA vendor in step 5.
  If you are prompted to trust the signed certificate when importing the certificate, as follows:
```
Trust this certificate? [no]:
```
  you must additionally import the intermediate or root CA certificates. Your CA vendor must provide instructions on how to obtain the intermediate and root CA certificates; the instructions may be included as part of an email or provided as links.
  If required, use keytool to import the intermediate and root CA certificate. For example:
```
keytool -importcert -noprompt -alias intermediate -file intermediate.der -storepass storepass -keystore keystore_name.jks 
keytool -importcert -noprompt -alias rootCA -file rootCA.der -storepass storepass -keystore keystore_name.jks
```
  where:
  - intermediate.der and rootCA.der are the certificate names of the intermediate certificate and root CA certificate, respectively.
  - storepass specifies the keystore password.
  - keystore_name is the name of your keystore.
- If you are using openssl, follow these steps:
  1. Create a keystore in PKCS12 format from your private key and the public certificate. For example:
```
openssl pkcs12 -export -in certificate.crt -inkey private_key.pem -out keystore_name.p12 -name srvalias
Enter Export Password:
Verifying - Enter Export Password:
```
    where:
    - certificate.crt is your certificate in .crt format (for example, cert.crt), which you downloaded from your CA vendor in step 5.
    - private_key.pem is the name of your private key (for example, private.pem). Ensure that the private key file is not encrypted.
    - keystore_name.p12 is the name of your keystore in PKCS12 format.
  2. Convert your keystore from .p12 format to .jks format:
```
keytool -importkeystore -destkeystore keystore_name.jks -srckeystore keystore_name.p12 -srcstoretype pkcs12 -alias srvalias
Enter destination keystore password:
Re-enter new password:
Enter source keystore password:
```
    where:
    - keystore_name.jks is the name of your keystore file in .jks format.
    - keystore_name.p12 is the name of your keystore in PKCS12 format.
    Ensure that the destination keystore password and the source keystore password are the same.
Configure SSL settings in the server_gui.xml configuration file:
1. Copy the SSL settings in 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. Add the keystore file location and password to the keyStore element. The keyStore element is called defaultKeyStore and contains the keystore password.
```
<keyStore id ="defaultKeyStore" location="keystore_name.jks_location" password="keypass"/>
```
  where:
  - keystore_name.jks_location is the path to keystore_name.jks.
  - keypass is the password set for keystore_name.jks.
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.
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://myhostname.example.com:8443/platform).
When the browser prompts you about an untrusted connection, follow the instructions provided by your CA to install the server certificate.

Results

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