Configuring TLS (Encryption Only) for Cloudera Manager

After creating directories for security artifacts, create a keystore, generate a certificate-signing request (CSR), submit the CSR to the appropriate Certificate Authority (CA), and install the certificate issued by the CA on the host, as detailed in this first step.

These steps include establishing trust for the internal CA's certificates, an explicit step that's not necessary for certificates signed by a public CA. If a known public CA such as Verisign or GeoTrust is used, you may not need to explicitly establish trust for the issued certificates. Newer public CAs might not be present yet in the JDK default cacerts file (see Creating Truststores for details on how to use the default JDK truststore, cacerts). If you have problems with the import process (such as keytool error: java.lang.Exception: Failed to establish chain from reply), follow the steps for trusting private CAs below.

1. Use keytool to generate a Java keystore and Certificate Signing Request (CSR) for the Cloudera Manager Server. In the command below, replace cmhost and cmhost.sec.example.com with the FQDN for your host.

   $ keytool -genkeypair -alias cmhost -keyalg RSA -keystore \
   /opt/cloudera/security/jks/cmhost-keystore.jks -keysize 2048 -dname \
   "CN=cmhost.sec.example.com,OU=Security,O=Example,L=Denver,ST=Colorado,C=US" \
   -storepass password -keypass password

   • -alias is a label that keeps track of the keys and certificate in in the keystore. Use the same -alias across keytool commands for your system.
   • -keyalg is the encryption algorithm used to generate the key. Cloudera recommends you use RSA, which allows key lengths greater than 1024 bits for certificate requests. (Other algorithms, such as DSA, may not be supported by some browsers, resulting in the javax.net.ssl.SSLHandshakeException: no cipher suites in common error.)
   • -dname (the X.509 distinguished name associated with the alias), which makes up the subject information for CSRs. If you don't specify the details in the command, you're prompted for values for the subject's First and Last name (CN). Use the FQDN for the host to which agents and browsers connect.
   • /opt/cloudera/security/jks/cmhost-keystore.jks is an example path to the keystore where you store the keystore file and where the Cloudera Manager Server host can access it.
   • Set -keypass to the same value as -storepass (Cloudera Manager does not support separate values for -keypass and -storepass.)
2. Generate a certificate signing request for the host (in this example, cmhost).

   $ keytool -certreq -alias cmhost \
   -keystore /opt/cloudera/security/jks/cmhost-keystore.jks \
   -file /opt/cloudera/security/x509/cmhost.csr -storepass password \
   -keypass password

3. Submit the .csr file created by the -certreq command to your Certificate Authority to obtain a server certificate. When possible, work with certificates in the default Base64 (ASCII) format. You can easily modify Base64-encoded files from .CER or .CRT to .PEM. The file is in ASCII format if you see the opening and closing lines as follows:

   -----BEGIN CERTIFICATE----- 
   ( the encoded certificate is represented by multiple lines of exactly 64 characters, except 
   for the last line which can contain 64 characters or less.) 
   -----END CERTIFICATE-----

   If your issued certificate is in binary (DER) format, adjust the commands according to the keytool documentation.

4. Copy the root CA certificate and any intermediate CA certificates to /opt/cloudera/security/CAcerts/.
   1. Import the root CA certificate first, followed by any intermediate CA certificates. Substitute $JAVA_HOME in the command below with the path for your Oracle JDK.

      $ sudo cp $JAVA_HOME/jre/lib/security/cacerts $JAVA_HOME/jre/lib/security/jssecacerts
      
      $ sudo keytool -importcert -alias RootCA -keystore $JAVA_HOME/jre/lib/security/jssecacerts \
      -file /opt/cloudera/security/CAcerts/RootCA.cer -storepass changeit
      
      $ sudo keytool -importcert -alias SubordinateCA -keystore \
      $JAVA_HOME/jre/lib/security/jssecacerts \
      -file /opt/cloudera/security/CAcerts/SubordinateCA.cer -storepass changeit

      Repeat for as many intermediate CA certificates as needed. The default -storepass for the cacerts file is changeit. After completing this step, copy the jssecacerts file created to the same path on all cluster hosts.
   2. Import the certificates (signed by your internal CA) into your Java keystore file. Import the root CA certificate first.

      $ keytool -importcert -trustcacerts -alias RootCA -keystore \
      /opt/cloudera/security/jks/cmhost-keystore.jks -file \
      /opt/cloudera/security/CAcerts/RootCA.cer -storepass password
      
      $ keytool -importcert -trustcacerts -alias SubordinateCA -keystore \ 
      /opt/cloudera/security/jks/cmhost-keystore.jks -file \
      /opt/cloudera/security/CAcerts/SubordinateCA.cer -storepass password

      Repeat for as many intermediate CA certificates as needed.
5. Copy the signed certificate file provided to a location where it can be used by the Cloudera Manager Agents (and Hue if necessary).

   $ cp certificate-file.cer  /opt/cloudera/security/x509/cmhost.pem

   Install it with the following keytool command:

   $ keytool -importcert -trustcacerts -alias cmhost \ 
   -file /opt/cloudera/security/x509/cmhost.pem \ 
   -keystore /opt/cloudera/security/jks/cmhost-keystore.jks -storepass password

   You must see the following response verifying that the certificate has been properly imported against its private key.

   Certificate reply was installed in keystore

   Now that the Jave keystore has imported the issued certificate, Java services on the Cloudera Manager Server host no longer need the original certificate-signing request (.CSR) and certificate files. You can access the certificate and private key through the keystore.

   However, you must export the private key from the Java keystore to make the certificate usable by Hue and the Cloudera Manager Agent. For instructions on reusing certificates, see Private Key and Certificate Reuse Across Java Keystores and OpenSSL.

1. Log into the Cloudera Manager Admin Console.
2. Select Administration > Settings.
3. Click the Security category.
4. Configure the following TLS settings:

   Property	Description
   Path to TLS Keystore File	Enter the complete path to the keystore file. For example: /opt/cloudera/security/jks/cmhost-keystore.jks
   Keystore Password	Enter the password for keystore: password
   Use TLS Encryption for Admin Console	Check this box to enable TLS encryption for Cloudera Manager.

5. Click Save Changes to save the settings.

When enabling TLS for the Cloudera Manager UI, you must set the Java truststore location and password in the Cloudera Management Services configuration. If this is not done, roles such as the Host Monitor and Service Monitor will not be able to connect to Cloudera Manager and will not start.

You can use either the default Java truststore ($JAVA_HOME/jre/lib/security/cacerts) and add trusted CA certificates to it, or, create a custom truststore. For instructions on both approaches, see Creating Truststores. If you choose to create a custom truststore, configure the path and password for the truststore file using the instructions as follows:

Restart the Cloudera Manager Server by running service cloudera-scm-server restart from the Cloudera Manager host command prompt.

You should now be able to connect to the Cloudera Manager Admin Console using an HTTPS browser connection. If a private CA certificate or self-signed certificate is used, you must establish trust in the browser for your certificate. This should be done for all browsers that will be used to access Cloudera Manager. By default, certificates issued by public commercial CAs should be trusted by the browsers accessing Cloudera Manager and other Java or OpenSSL-based services.

For more information on establishing trust for certificates, see TLS/SSL Certificates Overview or the relevant JDK documentation.