ist-dsi / kadmin

Kerberos Administration Interface (kadmin) for Scala

GitHub

kadmin license

Scaladoc Maven Central Dependency Status Reference Status

Build Status Codacy Badge Codacy Badge BCH compliance

A type-safe wrapper around the kadmin command for Scala.

In the JVM there are no libraries to create or delete kerberos principals. This is due to the fact that Kerberos only offers a C API, and interfacing with it via the Java Native Interface (JNI) can be a hard task to accomplish properly.

We solve the problem of Kerberos administration in JVM via the only other alternative: by launching the kadmin command and write to its standard input and read from its standard output. To simplify this process we use scala-expect.

Latest scaladoc documentation

Install

Add the following dependency to your build.sbt:

libraryDependencies += "pt.tecnico.dsi" %% "kadmin" % "7.0.0"

We use semantic versioning.

Available kadmin commands

Every command is idempotent except when changing either a password, a salt or a key.

Besides the above kadmin commands the following functions are also available:

  • getFullPrincipalName - returns the principal name with the realm, eg: kadmin/admin@EXAMPLE.COM.
  • doOperation - performs a kadmin command which will use password authentication or not according to the configuration, see below.
  • obtainTGT - invokes kinit to obtain a ticket for a given principal. Authentication is either performed with a password or with a keytab.
  • listTickets - invokes klist to obtain the cached tickets.
  • destroyTickets - invokes kdestroy to destroy the ticket cache.

Configurations

Kadmin uses typesafe-config.

The reference.conf file has the following keys:

kadmin {
  realm = "EXAMPLE.COM"

  principal = "kadmin/admin"
  // If keytab is not empty "command-keytab" will be used.
  // If password is not empty "command-password" will be used.
  // If both keytab and password are not empty "command-keytab" will be used.
  keytab = ""
  password = ""
  

  // This is the command used to start kadmin.
  // The literal string "$FULL_PRINCIPAL" will be replaced with s"$principal@$realm"
  // The literal string "$KEYTAB" will be replaced with s"$keytab"
  command-keytab = ${kadmin.command-password}" -kt $KEYTAB"
  command-password = "kadmin -p $FULL_PRINCIPAL"

  //The location to which keytabs will be generated to. Make sure this location:
  // · is NOT volatile
  // · is not world readable
  // · the user running the application has permission to write and to read from it.
  keytabs-location = "/tmp"

  //Regex that matches against the kadmin command prompt
  prompt = "kadmin(.local)?: "

  # Kadmin will use as settings for scala-expect library those defined:
  # 1) Here, directly under the path kadmin (these have precedence over the next ones).
  # 2) On the same level as kadmin.
  # IMPORTANT: if you set the log level of scala-expect to be info or higher the passwords of the principals will appear in the logs.
  # be sure to set the log level to WARN in production.
}

Alternatively you can pass your Config object to the kadmin constructor, or subclass the Settings class for a mixed approach. The scaladoc of the Settings class has examples explaining the different options.

How to test kadmin

In the project root run ./test.sh. This script will run docker-compose up inside the docker-kerberos folder. Be sure to have docker and docker-compose installed on your computer.

Note on the docker-kerberos folder

This folder is a git fake submodule to the docker-kerberos repository.

License

kadmin is open source and available under the MIT license.