cassandra-java-driver-kerberos

== Cassandra Java Driver Kerberos Authenticator

image:https://img.shields.io/maven-central/v/com.instaclustr/cassandra-driver-kerberos.svg?label=Maven%20Central[link=https://search.maven.org/search?q=g:%22com.instaclustr%22%20AND%20a:%22cassandra-driver-kerberos%22"] image:https://circleci.com/gh/instaclustr/cassandra-java-driver-kerberos.svg?style=svg["Instaclustr",link="https://circleci.com/gh/instaclustr/cassandra-java-driver-kerberos"]

A GSSAPI authentication provider for the https://github.com/datastax/java-driver[Cassandra Java driver].

This driver plugin is intended to work with the https://github.com/instaclustr/cassandra-kerberos[Cassandra kerberos authenticator] plugin for https://cassandra.apache.org/[Apache Cassandra].

=== Usage

The authenticator is distributed via Maven Central. To use, add the following dependency to your POM:

=== Pre-requisite setup steps

• A Kerberos 5 KDC server is available
• An NTP client is installed & configured on the application host, each Cassandra node, and the KDC. Ideally the application host syncs
  with the same time source as the KDC & Cassandra nodes in order to minimise potential time-sync issues.
• If using Oracle Java, ensure that the https://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html[Java Cryptographic Extensions Unlimited Strength Jurisdiction Policy Files]
  are installed (not necessary when using OpenJDK or other JRE implementations)
• Follow the instructions https://github.com/instaclustr/cassandra-kerberos[here] to configure a Cassandra cluster for Kerberos authentication.

Configure the /etc/krb5.conf Kerberos config file (see http://web.mit.edu/kerberos/www/krb5-latest/doc/admin/conf_files/krb5_conf.html[here] for further details).

An example krb5.conf for the EXAMPLE.COM realm:

[logging] default = FILE:/var/log/krb5libs.log

[libdefaults] default_realm = EXAMPLE.COM dns_lookup_realm = false dns_lookup_kdc = false

[realms] EXAMPLE.COM = { kdc = kdc.example.com admin_server = kdc.example.com }

[domain_realm]
.example.com = EXAMPLE.COM
example.com = EXAMPLE.COM

See http://web.mit.edu/kerberos/www/krb5-latest/doc/admin/conf_files/krb5_conf.html[here] for further details.

=== How to use the authenticator plugin

Note: Please read the javadoc for full details on how to configure & use the plugin.

The plugin works with the https://github.com/datastax/java-driver[Cassandra Java driver]:

CqlSession session = CqlSession.builder()
.addContactPoint(new InetSocketAddress(ipAddress, 9042))
.withAuthProvider(new ProgrammaticKerberosAuthProvider(
KerberosAuthOptions.builder().build()
)).build();

You may also configure the authenticator provider via file configuration as this driver builds on top of Cassandra Driver version 4. Please consult Javadoc of KerberosAuthProvider to know what configuration properties are available.

datastax-java-driver {
advanced.auth-provider {
class = com.instaclustr.cassandra.driver.auth.KerberosAuthProvider
... options
}
}

A JAAS config file is also required. The following example retrieves a TGT from the local Kerberos ticket cache:

CassandraJavaClient {
com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;
};

This particular example requires that the Kerberos client libraries & tools (kinit in particular) are installed.

The location of the JAAS config file must be provided via the java.security.auth.login.config system property.

For example: java -Djava.security.auth.login.config=/path/to/jaas.conf -jar MyApplication.jar

=== Build

If you would like to build the JAR package from source, checkout this project and run mvn clean package.

Please see https://www.instaclustr.com/support/documentation/announcements/instaclustr-open-source-project-status/[status] for Instaclustr support status of this project.