Configuring TLS (Encryption Only) for Cloudera Manager

Minimum Required Role: Cluster Administrator (also provided by Full Administrator)

Before enabling TLS security for Cloudera Manager, you must create a keystore, submit a certificate-signing request, and install the issued certificate for the Server. You do this using the Oracle JDK keytool command-line tool. If you are using an internal CA, append its certificate (and any required intermediate certificates) to the alternate default truststore provided with the JDK for inherent trust. This process is described in detail in Creating Truststores.

The table below shows the paths for managing certificates in the following examples. These paths persist during any upgrades and should be removed manually if the host is removed from a CDH cluster. Note that the folders and filepaths listed here can reside anywhere on the system and must be created on every host, since each host will have its own unique set of keys.

Set permissions on the paths such that scm-user, hue, Hadoop service users (or groups), and root users can read the private key, certificate, and keystore and truststore files.

Example pathnames for encryption keys and certificates
Example Property Values Description
cmhost.sec.example.com FQDN for Cloudera Manager Server host.
/opt/cloudera/security Base location for security-related files.
/opt/cloudera/security/x509 Location for openssl key/, cert/ and cacerts/ files to be used by the Cloudera Manager Agent and Hue.
/opt/cloudera/security/jks Location for the Java-based keystore/ and truststore/ files for use by Cloudera Manager and Java-based cluster services.
/opt/cloudera/security/CAcerts Location for CA certificates (root and intermediate CAs). One PEM file per CA in the chain is required.

Step 1: Obtain Encryption Keys and Certificates for Cloudera Manager Server

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.

Step 2: Enable HTTPS for the Cloudera Manager Admin Console and Specify Server Keystore Properties

  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.

Step 3: Specify SSL Truststore Properties for Cloudera Management Services

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:

  1. Open the Cloudera Manager Administration Console and go to the Cloudera Management Service.
  2. Click the Configuration tab.
  3. Select Scope > Cloudera Management Service (Service-Wide).
  4. Select Category > Security.
  5. Edit the following TLS/SSL properties according to your cluster configuration.
    Property Description
    TLS/SSL Client Truststore File Location Path to the client truststore file used in HTTPS communication. This truststore contains certificates of trusted servers, or of Certificate Authorities trusted to identify servers. If set, this is used to verify certificates in HTTPS communication with CDH services and the Cloudera Manager Server. If not set, the default Java truststore located at $JAVA_HOME/jre/lib/security/cacerts is used to verify certificates.

    The contents of this truststore can be modified without restarting the Cloudera Management Service roles. By default, changes to its contents are picked up within ten seconds.

    TLS/SSL Client Truststore File Password Password for the client truststore file. The password for the default cacerts file is changeit.
  6. Click Save Changes to commit the changes.
  7. Restart the Cloudera Management Service. For more information, see TLS/SSL Communication Between Cloudera Manager and Cloudera Management Services.

Step 4: Restart the Cloudera Manager Server

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.