Kerberos Authenticator

This library is intended to make it easy to authenticate someone using their Kerberos password in your Ruby application.

It uses Ruby-FFI to call the Kerberos 5 library. I have tested it with the Kerberos library included with Mac OS X, and with the latest MIT and Heimdal libraries under Debian. (Tests on Travis are run using the MIT library.)

Example

You will need to have

1. configured Kerberos correctly, and
2. obtained a service (or machine principal) and a keytab for that principal.

require 'kerberos_authenticator'

KerberosAuthenticator.setup do |config|
  # Configure the server principal and keytab used to verify the credentials received from the KDC.
  # Setting these to nil will let the underlying Kerberos 5 library try its own defaults.
  config.server = 'server@EXAMPLE.ORG'
  config.keytab_path = 'example.keytab'

  # Provide a keytab as a Base64 encoded string (e.g from an enviromental variable).
  # This will override keytab_path.
  # config.keytab_base64 = Base64.encode64(File.read('example.keytab'))
end

begin
  KerberosAuthenticator.authenticate!('user@EXAMPLE.ORG', 'mypassword')
  puts 'Successful authentication!'
rescue KerberosAuthenticator::Error => e
  puts 'Failed to authenticate!'
  puts e.inspect
end

# You can change passwords too.
KerberosAuthenticator.change_password!('user@EXAMPLE.ORG', 'mypassword', 'my_new_password')

Zanarotti attack

(Or why do I need a keytab?)

Getting credentials from a Kerberos Domain Controller (KDC) for a given username and password isn't sufficient to authenticate a user. This is because an attacker might be able to trick your server into obtaining credentials from a malicious KDC (by DNS hijacking, for example). This attack is called the Zanarotti attack (after Stan Zanarotti).

In order to avoid the Zanarotti attack, your application has to confirm the identity of the KDC that provided credentials for your user. A service principal's key (stored in a keytab) provides one way of doing this - the key is a secret shared only between your application and the KDC.

You can read more about this in the MIT Kerberos documentation.

I wrote this gem specifically because existing Ruby examples of using Kerberos to authenticate a user with their username and password failed to verify the identity of the KDC, and existing Ruby interfaces to Kerberos 5 libraries did not support the krb5_verify_init_creds function necessary to implement this verification.

Thread safety and Memory leaks

I believe that, when used with a recent version of the MIT Kerberos library, this gem is both thread-safe and free of memory leaks. Please do report any issues that you find.

LoadError

If requiring the gem results in a LoadError, you can specify how to find your Kerberos 5 library by setting the FFI_KRB5_LIBRARY_NAME environmental variable. (Or you could install the development files for your Kerberos 5 library, which should almost always allow the gem to find the library.)

License

This gem is licensed under the MIT License.