Kerberos is a complete software solution for establishing a secure network environment. It includes network protocols and software for handling authentication and authorization in a secure, encrypted fashion. Kerberos requires one or more servers known as key distribution centers (KDC) to authenticate and authorize services and the users who access them.

To use Kerberos for VoltDB authentication you must first set up Kerberos within your network environment. If you do not already have a Kerberos KDC, you will need to create one. You will also need to install the Kerberos client libraries on all of the VoltDB servers and clients and set up the appropriate principals and services. Because Kerberos is a complete network environment rather than a single platform application, it is beyond the scope of this document to explain how to install and configure Kerberos itself. This section only provides notes specific to configuring Kerberos for use by VoltDB. For complete information about setting up and using Kerberos, please see the Kerberos documentation.

Part of the Kerberos setup is the creation of a configuration file on both the VoltDB server and client machines. By default, the configuration file is located in /etc/krb5.conf (or /private/etc/krb5.conf on Macintosh). Be sure this file exists and points to the correct realm and KDC.

Once a KDC exists and the nodes are configured correctly, you must create the necessary Kerberos accounts — known as "user principals" for the accounts that run the VoltDB client applications and a "service principal" for the VoltDB cluster. For example, to create the service keytab file for the VoltDB database, you can issue the following commands on the Kerberos KDC:

$ sudo kadmin.local
kadmin.local: addprinc -randkey service/voltdb
kadmin.local: ktadd -k voltdb.keytab service/voltdb

Then copy the keytab file to the database servers, making sure it is only accessible by the user account that starts the database process:

$ scp voltdb.keytab voltadmin@voltsvr:voltdb.keytab
$ ssh voltadmin@voltsvr chmod 0600 voltdb.keytab

The next step is to install and configure the Java security extension known as Java Cryptography Extension (JCE). JCE enables the more robust encryption required by Kerberos within the Java Authentication and Authorization Service (JAAS). This is necessary because VoltDB uses JAAS to interact with Kerberos.

The JCE that needs to be installed is specific to the version of Java you are running. See the the Java web site for details. Again, you must install JCE on both the VoltDB servers and client nodes

Once JCE is installed, you create a JAAS login configuration file so Java knows how to authenticate the current process. By default, the JAAS login configuration file is $HOME/.java.login.config. On the database servers, the configuration file must define the VoltDBService module and associate it with the keytab created in the previous section.

Server JAAS Login Configuration File

VoltDBService {
    com.sun.security.auth.module.Krb5LoginModule required
        useKeyTab=true keyTab="/home/voltadmin/voltdb.keytab"
        doNotPrompt=true
        principal="service/[email protected]" storeKey=true;
};

On the client nodes, the JAAS login configuration defines the VoltDBClient module.

Client JAAS Login Configuration File

VoltDBClient {
    com.sun.security.auth.module.Krb5LoginModule required
    useTicketCache=true renewTGT=true doNotPrompt=true;
};

Finally, once Kerberos and the Java security extensions are installed and configured, you must configure the VoltDB database cluster and client applications to use Kerberos.

On the database servers, you enable Kerberos security using the <security> element in the deployment file, specifying "kerberos" as the provider. For example:

<?xml version="1.0"?>
<deployment>
     <security enabled="true" provider="kerberos"/>
       . . .
</deployment>

You then assign roles to individual users as described in Section 8.3, “Defining Users and Roles”, except in place of generic usernames, you specify the Kerberos user — or "principal" — names, including their realm. Since Kerberos uses encrypted certificates, the password attribute is ignored and can be filled in with arbitrary text. For example:

<?xml version="1.0"?>
<deployment>
   <security enabled="true" provider="kerberos"/>
       . . .
   <users>
       <user name="[email protected]" password="n/a" role="admin"
       <user name="[email protected]" password="n/a" role="dev"
       <user name="[email protected]" password="n/a" role="adhoc"
   </users>
</deployment>

Having configured Kerberos in the deployment file, you are ready to start the VoltDB cluster. When starting the VoltDB process, Java must know how to access the Kerberos and JAAS login configuration files created in the preceding sections. If the files are not in their default locations, you can override the default location using the VOLTDB_OPTS environment variable and setting the flags java.security.krb5.conf and java.security.auth.login.config, respectively.^[3]

In the client application, you specify Kerberos as the security protocol when you create the client connection, using the enableKerberosAuthentication method as part of the configuration. For example:

import org.voltdb.client.ClientConfig;
import org.voltdb.client.ClientFactory;
 
ClientConfig config = new ClientConfig();
      // specify the JAAS login module
config.enableKerberosAuthentication("VoltDBClient"); 
 
VoltClient client = ClientFactory.createClient(config);
client.createConnection("voltsvr");

Note that the VoltDB client automatically picks up the Kerberos cached credentials of the current process, the user's Kerberos "principal". So you do not need to — and should not — specify a username or password as part of the VoltDB client configuration.

It is also important to note that once the cluster starts using Kerberos authentication, only Java clients can connect to the cluster and they must also use Kerberos authentication, including the CLI command sqlcmd. To authenticate to a VoltDB server with Kerberos security enabled using sqlcmd, you must include the --kerberos flag identifying the name of the Kerberos client service module. For example:

$ sqlcmd --kerberos=VoltDBClient

Again, if the configuration files are not in the default location, you must specify their location on the command line:

$ sqlcmd --kerberos=VoltDBClient -J-Djava.security.krb5.conf=/etc/krb5.conf

You cannot use clients in other programming languages or CLI commands other than sqlcmd to access a cluster with Kerberos security enabled.