Configuring Kerberos authentication

You can configure Kerberos on your Db2 containerized solution to reduce the risk of a security exposure. Kerberos is a network authentication protocol that uses a system of shared secret keys to securely verify a user's identity in an untrusted network environment.

To configure Kerberos, complete the following steps.

1. Place a copy of the krb5.conf file at /etc/krb5.conf on the Red Hat OpenShift client/bastion node.
   If you are using Active Directory, see the Active Directory alternate steps. If you are connecting to a Db2 server by using JDBC with Kerberos authentication, see the JDBC alternate steps.
2. Navigate to the project where the db2uinstance CR is deployed.

   oc project <namespace>

3. Create a configmap from krb5.conf.

   oc create configmap db2u-krb5-config-cm --from-file=/etc/krb5.conf 

4. Copy each keytab file to the respective pod's mount point, which is located outside of the pods. Since this mount point is a shared directory, give each keytab file a unique name to ensure the correct file is copied to the right pod in the next step.

   oc cp db2inst1.keytab c-entrepot-db2u-0:/mnt/blumeta0/db2inst1.keytab

5. Exec into each pod and move each keytab to the correct path. The name for each keytab must be "db2inst1.keytab" once they are in the respective ${SYSCFGDIR}/kerberos/${POD_NAME} directories.

   sudo cp /mnt/blumeta0/db2inst1.keytab ${SYSCFGDIR}/kerberos/${POD_NAME}/db2inst1.keytab

6. Save the following as patch_configurations.json on the Red Hat OpenShift client/bastion node:

   {"spec": {
       
       "environment": {
         
         "instance": {
       
           "registry": {
             "DB2AUTH": "OSAUTHDB,ALLOW_LOCAL_FALLBACK",
             "DB2ENVLIST": "KRB5_KTNAME"
           },
           "dbmConfig": {
             "SRVCON_GSSPLUGIN_LIST": "IBMkrb5",
             "SRVCON_AUTH": "KRB_SERVER_ENCRYPT",
             "CLNT_KRB_PLUGIN": "IBMkrb5",
             "AUTHENTICATION": "SERVER_ENCRYPT"
           }
         }
       },
       "volumeSources": [
         {
           "visability": [
             "db2u"
           ],
           "volumeSource": {
             "configMap": {
               "name": "db2u-krb5-config-cm"
             }
           }
         }
       ]
     }
   }

7. Run the following to update the registry, dbmConfig and volumeSources to include the Kerberos configuration.

   oc patch db2 <instance name> --type=merge --patch "$(cat patch_configurations.json)"

   Important: The patch must be applied after the krb5.conf and keytabs are moved to the correct location.

   Once the pods restart and the instance and pods have moved to Ready state, the setup is complete.

   Conditional alternative steps:

   Active Directory

   If you are configuring Kerberos on Active Directory, use krb5.ini from your AD server by following the following steps.

   1. Check whether the user exists on active directory.

      Get-ADUser -Filter {UserPrincipalName -eq "USERNAME@DOMAIN.COM"}

   2. Create principal and keytab for the user, for example:

      ktpass /princ USERNAME@DOMAIN.COM /pass <PASSWORD> /mapuser <USERNAME> /ptype KRB5_NT_PRINCIPAL /out <KEYTAB_FILE_PATH>

   3. Rename krb5.ini to krb5.conf.
   4. Move the keytab and krb5.conf files to the Db2 server.
      Note: Since Kerberos does not provide group mapping, you must configure the db2uinstance for external LDAP/AD. This configuration can be done by using the Custom Resource. For more information, see Configuring External LDAP with a Db2uInstance custom resource
   5. Resume the main procedure in Configuring Kerberos authentication starting from step 2.

   Connecting to a Db2 server by using JDBC with Kerberos authentication

   If you are connecting to a Db2 server though JDBC, complete the following procedure.

   1. Ensure the krb5.conf file also contains a mapping to the local domain name of the pods in the domain_realm section of the configuration file:

      [domain_realm]
      .local = <realm.com>
      local = <realm.com>

      This conf file must be present and identical on both the Db2 or Db2 Warehouse server and on your local machine.

   2. Complete the procedure in Connecting to Db2 or Db2 Warehouse with a Red Hat OpenShift TLS route to create a Red Hat OpenShift TLS route, or alternatively open up a path to the Db2 NodePort service.
   3. Get the certificate for the Db2 instance though the route and import it to a keystore.
   4. Create a Kerberos Jaas Client file with the following contents:

       cat /Users/<username>/.myjaas.conf 
      
      JaasClient{ 
         com.sun.security.auth.module.Krb5LoginModule optional 
         useDefaultCcache=false 
         debug=true; 
      
      }; 

   5. Add the following JVM Args to pick up the Jaas Client file:

      -Djavax.security.auth.useSubjectCredsOnly=false 
      -Dsun.security.krb5.debug=true 
      -Djava.security.krb5.conf=/etc/krb5.conf 
      -Djava.security.auth.login.config=/Users/<username>/.myjaas.conf 

   6. Add the following JDBC connection properties: securityMechanism, sslConnection, and sslTrustStoreLocation.

      securityMechanism : 11
      sslConnection : true
      sslTrustStoreLocation : /Users/<username>/db2wh.jks
      sslTrustStorePassword : <password>

      Note: These parameters are case-sensitive .
   7. Generate a ticket for your user by using kinit. Use either keytab or the password.
      Note: If the ticket expires, the connection will end.
   8. Make a connection to the database. The cached ticket provides single sign-on, so a username and password do not need to be provided.
   9. Resume the main procedure in Configuring Kerberos authentication starting from step 2.