Enabling platform connections to use Kerberos SSO authentication

If your data sources use Kerberos authentication, you can enable users to use their IBM Software Hub credentials to authenticate to the data source.

Who needs to complete this task?
To complete this task you must be either:
  • A cluster administrator
  • An instance administrator
When do you need to complete this task?
You must complete this task before you create a connection to data sources where Kerberos authentication is enabled.
You can use Kerberos SSO authentication for the following connections:
  • Apache Hive
  • Apache Impala
  • Oracle

Before you begin

To use Kerberos SSO:
  • The data source must be configured to use Kerberos authentication with Active Directory.
  • Any additional configuration for Kerberos user impersonation must also be done on the data source.
  • IBM Software Hub must be configured to use the same instance of Active Directory for authentication.

Before you can set up Kerberos SSO for IBM Software Hub, an Active Directory administrator must:

  1. Create a Service Principal Name (SPN) for IBM Software Hub in Active Directory. IBM Software Hub will use the SPN to establish an authentication context.
  2. Configure the SPN to delegate user credentials.
  3. Generate a keytab file for the SPN.
Best practice: You can run the commands in this task exactly as written if you set up environment variables. For instructions, see Setting up installation environment variables.

Ensure that you source the environment variables before you run the commands in this task.

Procedure

To enable platform connections to use Kerberos SSO authentication:

  1. Provide the Kerberos configuration file (krb5.conf) to the connections microservice.
    1. Retrieve the krb5.conf file from the node where the Key Distribution Center (KDC) is configured.
      The file is typically in /etc directory.
    2. Save the krb5.conf file to a workstation that can connect to the cluster.
    3. Ensure that the forwardable parameter is set to true in thee libdefaults section of the krb5.conf file: 
      forwardable = true
    4. Apache Hive user only. Add the following setting to the libdefaults section of the krb5.conf file if both of the following statements are true:
      • IBM Software Hub is installed on a FIPS-enabled cluster.
      • Your Apache Hive Kerberos instance is not configured for AES 256 encryption.
      allow_weak_crypto = true
    5. Set the KRB5_CONF_FILE environment variable to the fully qualified file name of the krb5.conf file: 
      export KRB5_CONF_FILE
    6. Optional: The following steps are optional and are only needed if you are configuring multiple Kerberos configuration files. Skip to step 1.j if you do not need to configure multiple Kerberos configuration files.
      For configuring multiple Kerberos configuration files, create the krb5-config-dir ConfigMap in the operands project for the instance of IBM Software Hub where the Kerberos configuration is being enabled and where you want to use multiple configuration files for connecting to different Kerberos realms.
    7. Optional: Create the new ConfigMap krb5-config-dir by running the following command: 
      oc create configmap krb5-config-dir \
—from-file=${KRB5_CONF_DIR} \
--namespace=${PROJECT_CPD_INST_OPERANDS}
      Where KRB5_CONF_DIR points to the directory hosting multiple Kerberos configuration files on the local filesystem of the machine from where the oc command is being run, and PROJECT_CPD_INST_OPERANDS is the namespace in which the services are deployed.
    8. Optional: Once the ConfigMap krb5-config-dir is created, the base Kerberos configuration file should have the includedir directive pointing to the absolute path of the directory under which the contents of the newly created ConfigMap is mounted. The includedir should point to /etc/krb5-config-files/krb5-config-dir.
    9. Optional: Update the krb5.conf defined through the ConfigMap krb5-config-files to add the includedir directive.
      For example:
      includedir /etc/krb5-config-files/krb5-config-dir
[libdefaults]
  allow_weak_crypto = true
  default_realm = FYRE.IBM.COM
  dns_lookup_kdc = false
  dns_lookup_realm = false
  ticket_lifetime = 86400
  renew_lifetime = 604800
  forwardable = true
  default_tgs_enctypes = aes256-cts aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
  default_tkt_enctypes = aes256-cts aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
  permitted_enctypes = aes256-cts aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
  udp_preference_limit = 1
  kdc_timeout = 3000
[realms]
  FYRE.IBM.COM = {
    kdc = kdc1.fyre.ibm.com
    admin_server = kdc1.fyre.ibm.com
  }
[domain_realm]
    10. Create the krb5-config-files ConfigMap in the operands project for the instance of IBM Software Hub where you want to enable connections to use Kerberos SSO. 
      oc create configmap krb5-config-files \
--from-file=${KRB5_CONF_FILE} \
--namespace=${PROJECT_CPD_INST_OPERANDS}
  2. Verify that the krb5.conf file is mounted correctly.
    1. Verify that the contents of the krb5.conf file are mounted as a file under the default file location /etc/krb5-config-files/ in the wdp connect-connector pod: 
      oc exec \
-n ${PROJECT_CPD_INST_OPERANDS} `(oc get pods -n ${PROJECT_CPD_INST_OPERANDS} -o jsonpath='{range .items[*].metadata}{.name}{"\n"}' | grep -i wdp-connect-connector)` -- ls -l ${KRB5_CONF_FILE}
      The command returns output with the following format:
      lrwxrwxrwx. 1 root 1000680000 16 Jul 29 18:21 /etc/krb5-config-files/krb5.conf -> ..data/krb5.conf
    2. Verify that the KRB5_CONF_FILE environment variable is set and points to the default configuration file location /etc/krb5-config-files/krb5.conf: 
      oc exec \
-n ${PROJECT_CPD_INST_OPERANDS} `(oc get pods -n ${PROJECT_CPD_INST_OPERANDS} -o jsonpath='{range .items[*].metadata}{.name}{"\n"}' | grep -i wdp-connect-connector)` -- env | grep ${KRB5_CONF_FILE}
    3. Verify the content of the krb5.conf file that is mounted in the container. 
      oc exec \
-n ${PROJECT_CPD_INST_OPERANDS} `(oc get pods -n ${PROJECT_CPD_INST_OPERANDS} -o jsonpath='{range .items[*].metadata}{.name}{"\n"}' | grep -i wdp-connect-connector)` -- cat ${KRB5_CONF_FILE}
      The command returns output with the following format:
      [libdefaults]
  forwardable = true
  default_realm = IBM.COM
  ticket_lifetime = 24h
  dns_lookup_realm = false
  dns_lookup_kdc = false

[logging]
  default = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmind.log
  kdc = FILE:/var/log/krb5kdc.log

[realms]
  IBM.COM = {
    admin_server = mykrbadminserver.ibm.com
    kdc = mykdcadminserver.ibm.com
 }
    4. Optional: If you configured multiple Kerberos configuration files, perform the following validation. If you did not configure multiple Kerberos configuration files, skip this step.
      Validate the number of configuration files in the ConfigMap by running:
      oc get cm krb5-config-dir
      An example output:
      # oc get cm krb5-config-dir
NAME              DATA      AGE
krb5-config-dir   2         4h
      Where the number under the column DATA indicates the number of files.
  3. If the file is not mounted, restart the wdp connect-connector pods: 
    oc delete pods -n ${PROJECT_CPD_INST_OPERANDS} | grep wdp connect-connector
  4. Save the keytab file to a workstation that can connect to the cluster.
  5. Create a secret for the Service Principal Name (SPN):
    1. Set the KERBEROS_SSO_SPN environment variable to the name of the SPN: 
      export KERBEROS_SSO_SPN=<spn>
    2. Create a secret named wdp-kerberos-sso-principal-secret: 
      oc create secret generic wdp-kerberos-sso-principal-secret \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
--from-literal wdp-kerberos-sso-principal=${KERBEROS_SSO_SPN}
  6. Create a secret for the keytab file for the SPN:
    1. Set the KEYTAB_FILE environment variable to the fully qualified file name of the keytab file: 
      export KEYTAB_FILE=<fully-qualified-keytab-file-name>
    2. Create a secret named wdp-kerberos-sso-keytab-secret: 
      oc create secret generic wdp-kerberos-sso-keytab-secret \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
--from-file wdp-kerberos-sso-keytab=${KEYTAB_FILE}
  7. Verify that the secrets were created in the /etc/.secrets directory of the wdp-connect-connection pod: 
    oc exec \
-n ${PROJECT_CPD_INST_OPERANDS} $(oc get pods -n ${PROJECT_CPD_INST_OPERANDS} -o jsonpath='{range .items[*].metadata}{.name}{"\n"}' | grep -i wdp-connect-connection) -- ls -l /etc/.secrets

Results

You can now create connections that use Kerberos SSO authentication. Ensure that the connections use personal credentials.