wiki:GettingStarted
Last modified 2 years ago Last modified on 02/24/12 15:16:02

Getting Started

Assumptions

I assume in this guide you already have a working MIT krb5 setup or knowledge of how to set it up. I will not be covering krb5 configuration during this guide. One important thing to note here is that you MUST have krb5 FAST setup.

Installing

Source Install

If you are not on Fedora 17 or later, you can download the source and do:

./configure ; make ; sudo make install

Be aware that you might have to specify some directories (like systemdsystemunitdir, libdir and socketdir) as configure options. AuthHub? also requires:

  • MIT krb5 >= 1.10
  • systemd
  • python
  • com_err
  • libverto >= 0.2.4
  • libverto-jsonrpc

Fedora 17+ Install

In Fedora 17 and later, AuthHub? is divided into several packages:

  1. client only: authhub-client
  2. server only: authhub
  3. server plugins: authhub-httpbasicauth authhub-totp authhub-yubikey
  4. python bindings for server plugins: python-authhub

Clients require only authhub-client. Servers require at least one plugin.

Enabling

krb5.conf

In order for MIT Kerberos to utilize AuthHub? plugins, you must enable AuthHub? in krb5.conf. This configuration stanza should look something like this:

[plugins]
 enable_only = authhub

 # Server-side
 kdcpreauth = {
  module = authhub:preauth/authhub.so
 }

 # Client-side
 clpreauth = {
  module = authhub:preauth/authhubc.so
 }

Plugins

Once everything is installed, you will need to decide which plugins you wish to run (you may run multiple). For the sake of this guide we will be running only authhub-totp.

# Start authhub-totp right now
sudo systemctl start authhub-totp.socket

# Automatically start authhub-totp at boot
sudo systemctl enable authhub-totp.socket 

# Restart the KDC
sudo systemctl restart krb5kdc.service

Now everything should be running. If you wish to enable other plugins, just repeat the steps above for each plugin.

Configuring

Although configuration is done in the same way for all plugins, what each plugin requires is different. Configuration that is per-plugin, but not per-principal is up to the plugin itself to provide if needed. As such, this type of configuration will not be covered here. That being said, most configuration is per-principal and is stored in the per-principal strings in kadmin.

First, the kdc needs to be told that a given principal will require authhub authorization to return a ticket. This is enabled by running the following kadmin command:

modprinc +requires_preauth +requires_hwauth <PRINCIPAL>

At this point, the principal specified above will be unable to log in due to the fact that we now require AuthHub? for authentication, but the principal has no AuthHub? specific configuration yet. In general this configuration will be set by issuing the following kadmin command:

setstr <PRINCIPAL> authhub:totp <CONFIG>

This will set the authhub-totp configuration. An example of what this configuration might look like is this:

setstr npmccallum@redhat.com authhub:totp "{'key': 'base32:5Q7HBYO7JKPRXXS2TYTU4SAZJZBUGTML' }"

However, precisely how this configuration will look will depend significantly on the plugin involved.

What I can point out is that the value of <CONFIG> will always be a JSON object.

For plugin specific configuration instruction, see the plugin pages:

  1. authhub-totp