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:

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. Note, however, that 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, 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.

Procedure

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 ($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.5.25/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.
Generate a keystore for the cluster management console server and create a certificate-signing request file by 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, 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 1).
  
  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.
Contact your CA vendor to create an SSL certificate. Your vendor will need the keystore_name.csr file that you created in step 2.

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.
Once your vendor approves your request, follow the vendor-provided instructions to download the certificate in .der and .pem formats (for example, cert.der and cert.pem)
If your vendor does not provide the certificate in .pem format, which is required for use in a later step, convert the certificate from .der to .pem format. For example:
```
openssl x509 -inform der -in cert.der -out cert.pem
```
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), 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.
Optional: Complete the following steps to generate and export a private key if you are enabling SSL for Elastic Stack.
1. Generate a pkcs12 format keystore from the jks format keystore. For example:
```
keytool -importkeystore -srckeystore path_to_keystore_name.jks -destkeystore keystore_name.p12 -srcstoretype jks 
-deststoretype pkcs12 -srcalias srvalias -srckeypass sourcekeypass -deststorepass deststorepass -srcstorepass sourcestorepass -noprompt
```
  where:
  - path_to_keystore_name.jks is the path to your keystore and keystore_name.p12 is the keystore in pkcs12 format.
  - sourcekeypass specifies the password of the source keystore.
  - sourcestorepass and deststorepass specify the password to protect the integrity of the keystore at source and at destination, respectively.
2. Export the private key (for example, private.key) from the pkcs12 format keystore. For example:
```
openssl pkcs12 -in keystore_name.p12 -nodes -nocerts -out private.key
```
  where keystore_name.p12 is the name of your keystore in pkcs12 format.
Import your server certificate to the keystore. If your CA vendor provided instructions, you must follow those instructions.
To import your server certificate using the keytool utility, for example, enter:
```
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 4.
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.
Configure SSL settings in the server_gui.xml configuration file:
1. Copy the SSL settings in $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. 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 securityUtilities command. For more information, see:
  - Liberty profile: securityUtility command
5. Save your changes to server_gui.xml.
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.