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

Configure security 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 security for the cluster management console, see Enabling security with the security tool. Use the security tool generate security server certificates to encrypt information, and then configuring components to use those certificates for security. The security tool provides both of these functions.

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 your own self-signed certificate that will replace the default one generated 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 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 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: 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
```
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 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.
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\
Configure security settings in the server_gui.xml configuration file:
1. Copy the security 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.
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://webguiserver.example.com:8443/platform).
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, Linux, or Mac OS, complete the following steps:
    1. Click Firefox > Settings > Privacy & Security > 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 Microsoft Edge, 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 TLS in your development environment.