Oracle Cloud Infrastructure Documentation

SSL for Certificate Authority (CA) Signed Certificates

A CA certificate is created, signed, and issued by a third-party or certificate authority (CA) that's authorized to validate the identify of the subject of the certificate. In Big Data Service clusters with version 3.0.7 and later, you can run the Big Data Service certificate utility tool to use CA SSL certificates for your ODH clusters.

Note

  1. Oracle generates one issuer certificate and adds it to the truststore on the cluster nodes.
  2. Big Data Service ODH clusters support on-demand node addition and autoscale. For clusters enabled with CA signed SSL certificates, during node addition, an Oracle signed certificate is created on the new node to complete the node addition flow. Newly added nodes can be later updated with CA signed certificates.
  3. Starting with Big Data Service version 3.0.15, ODH supports updating CA signed certificates for targeted nodes. For example, un0 and mn0. In such cases, you must supply certificates for targeted nodes and all other nodes use Oracle signed certificates.
  4. Clusters created before Big Data Service version 3.0.15 require certificates for all the nodes.

Enabling SSL for Certificate Authority (CA) Signed Certificates

  1. Gather the following files in one folder and compress the folder into .zip format.
    • CA signed SSL certificate for each node or targeted nodes (supported in Big Data Service version 3.0.15 or later) in the ODH cluster based on the node's FQDN. The CA signed certificates must be in Privacy Enhanced Mail (PEM) format with the .crt extension.
    • The private key of each certificate with the .key extension.
    • Root certificate for the truststore.
  2. SSH to the first master node (mn0) of the ODH cluster node as opc user.
  3. Copy the zip file to the first master node (mn0). 
    scp -i <node-key> <source/zip/filepath> opc@<mn0-public-ip>:<path/to/destination>

    Example:

    scp -i ssh_login.key /home/test/certificates.zip opc@192.168.0.10:/tmp/certificates.zip
  4. Unzip the file. 
    unzip <filename>.zip -d </path/to/directory>

    Example:

    unzip certificates.zip -d /tmp/certs
  5. Edit /home/opc/cloud/flask-microservice/cert_util/conf/bds-certs.conf. 
    vi /home/opc/cloud/flask-microservice/cert_util/conf/bds-certs.conf
    Example:
    # Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
#
[BDS_CERT_CONFIGS]
#This files defines all the SSL certificate related configurations used in BDS cluster
#Whether custom certificate or not
CUSTOM_CERTIFICATE=false
#Recommended SSL services, Mostly all the customer facing UI services
#Allowed values AMBARI,RANGER,HUE,DATASTUDIO,LIVY
DEFAULT_SSL_SERVICES=AMBARI
#Comma separated service names for enabling SSL, These are the additional components from ambari UI to enable/disable SSL.
#Allowed values ZOOKEEPER,AMS,HDFS,YARN,MAPREDUCE,OOZIE,HBASE,SPARK,HIVE,KAFKA
ADDITIONAL_SSL_SERVICES=NONE
#Whether to restart all the required services after certificate deployment
RESTART_REQUIRED_SERVICES=false
#Certificate validity in days. Mostly used for self signed certificates
CERTIFICATE_VALIDITY=180
#Bits to be used for certificate generation. Mostly used for self signed certificates
CERTIFICATE_BITS=3072
#Algorithm to be used for generating self signed certificate
CERTIFICATE_ALGORITHM=sha256
#Default path to store all the certificate, keys and keystore. Same path will be used for hadoop credential store
CERT_PATH=/etc/security/serverKeys
#Temporary certificate directory. Will be used before applying the certificate
TEMP_CERT_PATH=/etc/security/serverKeys_new
#Initital certificate generation path. Used only when generating self signed certificates
CERT_GEN_FOLDER=/etc/security/serverKeys_cert_gen
#Secure password location. This location will be used only during transaction
CERT_PASS_PATH=/etc/security/certPass
#Whether to take backup when doing certificate renewal. Mostly used for self signed certificates
KEEP_OLD_CERTS=true
#Set this flag incase utility used for older cluster. It will update the keystore path along with other properties
LEGACY_CLUSTER=false
#Set Keystore type
KEYSTORE_TYPE=jks
 
#This is completely owned by oracle. Leave this field unchanged
ORACLE_OWNED_ROOT_CERTIFICATE_NAME=bdsOracleCA.crt
ORACLE_OWNED_ROOT_CERTIFICATE_KEY_NAME=bdsOracleCA.key
 
#Final trust bundle that contains all the trust certificates.
#Including all public ca root certs, oracle owned root certs and customer specified root certs.
#This will be saved in CERT_PATH. Leave this field untouched
TRUST_CERTS_BUNDLE_NAME=oraclerootCA.crt
 
#Root Certificate related details
ROOT_CERT_PATH=/etc/security/serverKeys/bdsOracleCA.crt
 
#Server certificate details
SERVER_CERT_PATH="NONE"
SERVER_CERT_KEY_PATH="NONE"
 
#Support for LDAPS
LDAP_URL=NONE
  6. Update the CUSTOM_CERTIFICATE property value to true. This property indicates to the utility tool that the certificate configured is a CA signed certificate.
  7. Update the SERVER_CERT_PATH property with the certificate path for each node or targeted nodes (supported in Big Data Service version 3.0.15 or later) of the cluster in a comma-separated list in the format: 
    <hostname>:<path/to/cert.crt>

    where, hostname is the node where the certificate is copied to

    and, the <path/to/cert.crt> is the complete path to the certificate file and not the relative path.

    Example:

    my-mn0-host.com:/tmp/my-mn0-host.com.crt,my-mn1-host.com:/tmp/my-mn1-host.com.crt
  8. Update the SERVER_CERT_KEY_PATH property with the private key path for each node or targeted nodes (supported in Big Data Service version 3.0.15 or later) of the cluster in a comma-separated list in the format: 
    <hostname>:<path/to/cert.key>

    where, hostname is the node where the private key is copied to

    and, the <path/to/cert.key> is the complete path to the private key and not the relative path.

    Example:

    my-mn0-host.com:/tmp/my-mn0-host.com.key,my-mn1-host.com:/tmp/my-mn1-host.com.key
  9. Validate that the proper CA certificate chain certificate is present in the cert file passed in config file (Server certificate > Intermediate certs > Root certificate): 
    # openssl crl2pkcs7 -nocrl -certfile bundle.cert.pem | openssl pkcs7 -print_certs -noout

     bundle.cert.pem with the root_ca certificate.

    Example:

    [root@server1.oracle.com certs]# openssl crl2pkcs7 -nocrl -certfile bundle.cert.pem | openssl pkcs7 -print_certs -noout

subject=/C=US/ST=CA/L=San Francisco/O=Example Corp/OU=IT Department/CN=www.example.com
issuer=/C=US/ST=CA/O=Example Corp/OU=IT Department/CN=Intermediate CA 

subject=/C=US/ST=CA/O=Example Corp/OU=IT Department/CN=Intermediate CA
issuer=/C=US/ST=CA/L=San Francisco/O=Example Corp/OU=IT Department/CN=Root CA/emailAddress=Email Address 


subject=/C=US/ST=CA/L=San Francisco/O=Example Corp/OU=IT Department/CN=Root CA/emailAddress=Email Address
issuer=/C=US/ST=CA/L=San Francisco/O=Example Corp/OU=IT Department/CN=Root CA/emailAddress=Email Address
    Note

    In some cases, you might need to import the Active Directory KDC certificate for kerberizing the cluster. Specify the cert path (containing complete CA certificate chain of Active Directory KDC) in ROOT_CERT_PATH.
    Example:
    1. Verify the complete certificate chain for Active Directory KDC SSL connection:
      openssl s_client -connect ldaps_server_name:port -showcerts
    2. Confirm that the available certificate is defined in 'ROOT_CERT_PATH' and it has all of the certificate chain information from the previous command.
  10. Update the ADDITIONAL_SSL_SERVICES property with the services that you want to enable SSL for. The default value for this property is NONE. The allowed values are AMS, HDFS, YARN, MAPREDUCE, OOZIE, HBASE, SPARK, ZOOKEEPER, HIVE, and KAFKA. We recommend that you enable SSL for all required services in one go by using a comma-separated list of the services.
  11. Update LDAP_URL to point to LDAP server URL (applicable for secure LDAP only), if the ODH cluster is integrated with LDAP/AD.

    Example:

    LDAP_URL=ldaps://<myldap.com:636>

    This automatically pulls the required certificates to the ODH truststore.

  12. Update the RESTART_REQUIRED_SERVICES property value to true, if you want this utility to restart the services. The default value for this property is false. If you retain the default value, you need to manually restart all the affected services from Apache Ambari to complete enabling SSL for the cluster.
    Irrespective of the value of this property, few services like Apache Ambari and Datastudio are immediately restarted when you enable certificates using this utility.
  13. Retain the default value true for the KEEP_OLD_CERTS property to keep a backup of the old certificates. Certificate backups are stored at /etc/security/serverKeys-backup-<dateofbackup>.
  14. If the cluster version is 3.0.6 or lower, set the LEGACY_CLUSTER property value as true to update the SSL properties in the cluster. Skip this step if the cluster version is 3.0.7 or later.
  15. Save the changes made to the configuration file.
  16. Run the utility to enable the SSL certificates. If you don't use the ambariPass and keyPass parameters, you're prompted to enter the Ambari password and private key passphrase. If no private key passphrase was provided when the private key got generated, then you don't need to provide the passphrase. 
    sudo bds_cert_util --enable --ambariPass ambari-password --keyPass private-key-passphrase
  17. Wait for the utility to complete.
  18. Review the utility logs from /home/opc/cloud/flask-microservice/logs/bds_cert_util*.log.
  19. After the utility runs successfully, all configured services run on SSL. To verify if the services are enabled for SSL, sign-in to Apache Ambari and click the quicklinks under each of the configured services.