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 on Linux systems. (On Macintosh systems, the configuration file is edu.mit.Kerberos located either in ~/Library/Preferences/ or /Library/Preferences/.) 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. If you intend to use the web-based Volt Management Center or the JSON interface, you will also want to create a host and HTTP service principle for each server as well. 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

You can then create host and HTTP service principles for each server in the cluster and write them to a server-specific keytab. For example, to create a keytab file for the database node server1, the command would be the following:

$ sudo kadmin.local

kadmin.local: addprinc -randkey host/server1.mycompany.lan
kadmin.local: addprinc -randkey HTTP/server1.mycompany.lan
 
kadmin.local: ktadd -k server1.mycompany.lan.keytab HTTP/server1.mycompany.lan
kadmin.local: ktadd -k server1.mycompany.lan.keytab host/server1.mycompany.lan

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.

To enable Kerberos access from the web-based Volt Management Center and JSON interface, you must also include entries for the Java Generic Security Service (JGSS) declaring the VoltDB service principle and the server's HTTP service principle. For example:

Server JAAS Login Configuration File

VoltDBService {
    com.sun.security.auth.module.Krb5LoginModule required
        useKeyTab=true keyTab="/home/voltadmin/voltdb.keytab"
        doNotPrompt=true
        principal="service/voltdb@MYCOMPANY.LAN" storeKey=true;
};

com.sun.security.jgss.initiate { 
     com.sun.security.auth.module.Krb5LoginModule required 
     principal="service/voltdb@MYCOMPANY.LAN" 
     keyTab="/home/voltadmin/voltdb.keytab" 
     useKeyTab=true 
     storeKey=true 
     debug=false; 
}; 
  
com.sun.security.jgss.accept { 
     com.sun.security.auth.module.Krb5LoginModule required 
     principal="HTTP/server1.mycompany.lan@MYCOMPANY.LAN" 
     useKeyTab=true 
     keyTab="/etc/krb5.keytab" 
     storeKey=true 
     debug=false 
     isInitiator=false; 
};

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 when you initialize the database root directory, 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 12.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="mtwain@MYCOMPANY.LAN" password="n/a" roles="administrator"/>
       <user name="cdickens@MYCOMPANY.LAN" password="n/a" roles="dev"/>
       <user name="hbalzac@MYCOMPANY.LAN" password="n/a" roles="adhoc"/>
   </users>
</deployment>

Having configured Kerberos in the configuration file, you are ready to initialize and 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 Java client applications, 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.

When using the VoltDB JDBC client interface, you can enable Kerberos by setting the kerberos property on the connection to match the settings in the Java API. For example, you can enable Kerberos by setting the property on the connection string as a query parameter:

Class.forName("org.voltdb.jdbc.Driver");
Connection c = DriverManager.getConnection(
     "jdbc:voltdb://svr1:21212,svr2:21212?kerberos=VoltDBClient");

Alternately, you can supply a list of properties, including the kerberos property, when you initialize the connection:

Class.forName("org.voltdb.jdbc.Driver");
Properties props = new Properties();
props.setProperty("kerberos", “VoltDBClient");
Connection c = DriverManager.getConnection(
     "jdbc:voltdb://svr1:21212,svr2:21212", props);

It is also important to note that once the cluster starts using Kerberos authentication, only Java, JDBC, JSON, and Python clients can connect to the cluster and they must use Kerberos authentication to do it. The same is true for the CLI commands, such has sqlcmd and voltadmin. To authenticate to a VoltDB server with Kerberos security enabled using the Java-based utilities sqlcmd and cvsloader, you must include the --kerberos flag identifying the name of the Kerberos client service module. For example:

$ sqlcmd --kerberos=VoltDBClient

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.auth.login.config=myclient.kerberos.conf

To use the Python API or Python-based voltadmin utility, you must first make sure you have the python-gssapi package installed. Then, login to your Kerberos account using kinit before invoking the Python client. When using the voltadmin utility, you must also include --kerberos flag, but you do not need to specify any argument since it picks up the credentials in the Kerberos user's cache. For example:

$ voltadmin shutdown --kerberos

To use the Volt Management Center or the JSON interface to access the database, your web browser must be configured to use the Simple and Protected GSS-API Negotiation Mechanism (also known as SPNEGO). See your web browser's help for instructions on configuring SPNEGO.