Enabling security for the cluster management console using an external certificate

Configure security 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 security for the first time (in other words, if you disabled security during installation by setting DISABLESSL=Y).
Use a properly chained certificate from a trusted CA that replaces the default self-signed certificate when security is enabled during installation.

When security 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 security setting for the cluster management console and the RESTful web servers. If you enable security for one, you must also enable security for the other; if you disable security for one, security must be disabled for the other as well. This setting also takes effect for cloud bursting with host factory. Ensure that security for all these functions is configured consistently in the cluster; without a uniform configuration, errors occur. When security 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 security 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.2 is 8.0.6.36.
  - Windows:
```
cd Installation_top\jre\jre_version\bin
```
    where the jre_version for IBM Spectrum Symphony 7.3.2 is 8.0.6.36.
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 a security certificate from your CA vendor.
  - keystore_name.jks is the name of your keystore.
Contact your CA vendor to create a security 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 security 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 security 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 security settings in the server_gui.xml configuration file:
1. Copy the security 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 security 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 TLS in your production environment.