Kerberos
========

Dovecot supports Kerberos 5 using GSSAPI. The Kerberos authentication mechanism
doesn't require having a <passdb> [PasswordDatabase.txt], but you do need a
<userdb> [UserDatabase.txt] so Dovecot can lookup user-specific information,
such as where their mailboxes are stored.

*Note:* If you only wish to authenticate clients using their Kerberos
/passphrase/ (as opposed to ticket authentication), you will probably want to
use <PAM> [PasswordDatabase.PAM.txt] authentication with 'pam_krb5.so' instead.

Pre-requisites
--------------

This document assumes that you already have a Kerberos Realm up and functioning
correctly at your site, and that each host in your realm also has a host
/keytab/ installed in the appropriate location.

For Dovecot, you will need to install the appropriate /service/ keys on your
server.  By default, Dovecot will look for these in the host's keytab file,
typically '/etc/krb5.keytab', but you can specify an alternate path using the
'auth_krb5_keytab' configuration entry in dovecot.conf.  Anyway specified
keytab file should be readable by user "dovecot" (or whatever user the auth
process is running as). If you wish to provide an IMAP service, you will need
to install a service ticket of the form 'imap/hostname@REALM'.  For POP3, you
will need a service ticket of the form 'pop/hostname@REALM'.  When using
Dovecot's <SASL> [Sasl.txt] with MTA, you will need to install service ticket
of the form 'smtp/hostname@REALM'.

Example dovecot.conf configurations
-----------------------------------

If you only want to use Kerberos ticket-based authentication:

---%<-------------------------------------------------------------------------
auth_mechanisms = gssapi
userdb {
  driver = static
  args = uid=vmail gid=vmail home=/var/vmail/%u
}
---%<-------------------------------------------------------------------------

(In this virtual-hosting example, all mail is stored in /var/vmail/$username
with uid and gid set to 'vmail')

If you also want to support plaintext authentication in addition to
ticket-based authentication, you will need something like:

---%<-------------------------------------------------------------------------
auth_mechanisms = plain gssapi
passdb {
  driver = pam
}
userdb {
  driver = passwd
}
---%<-------------------------------------------------------------------------

(Note that in this example, you will also need to configure PAM to use
whichever authentication backends are appropriate for your site.)

Enable plaintext authentication to use Kerberos
-----------------------------------------------

This is needed when some of your clients don't support GSSAPI and you still
want them to authenticate against Kerberos.

Install pam_krb5 module for PAM, and create '/etc/pam.d/dovecot':

---%<-------------------------------------------------------------------------
auth sufficient pam_krb5.so
account sufficient pam_krb5.so
---%<-------------------------------------------------------------------------

Then enable PAM passdb:

---%<-------------------------------------------------------------------------
passdb {
  driver = pam
}
---%<-------------------------------------------------------------------------

Check '/var/log/auth.log' if you have any problems logging in. The problem
could be that PAM is still trying to use pam_unix.so rather than pam_krb5.so.
Make sure pam_krb5.so is the first module for account or just change
pam_unix.so to sufficient.

Cross-realm authentication
--------------------------

This seems to have all kinds of trouble. Search Dovecot mailing list for
previous threads about it. Some points about it:

 * krb5_kuserok() is used to check if access is allowed. It may try to do the
   check by reading ~user/.k5login (good!) or ~dovecot/.k5login (bad!)
 * v2.2+ has "k5credentials" <passdb extra field>
   [PasswordDatabase.ExtraFields.txt], which is a comma separated list of
   usernames that are allowed to log in. If it's set, it bypasses the
   krb5_kuserok() check.
 * Solaris uses _gss_userok() instead of krb5_kuserok()

Client support
--------------

Mail clients that support Kerberos GSSAPI authentication include:

 * Evolution
 * Mozilla Thunderbird
 * SeaMonkey
 * Mutt
 * UW Pine
 * Apple Mail

Testing
-------

*FIXME*: This section requires cleanup.

Test that the server can access the keytab
------------------------------------------

This test demonstrates that the server can acquire its private credentials.
First telnet directly to the server

---%<-------------------------------------------------------------------------
$ telnet localhost 143
* OK Dovecot ready.
---%<-------------------------------------------------------------------------

or, if you are using IMAPS then use openssl instead of telnet to connect:

---%<-------------------------------------------------------------------------
$ openssl s_client -connect localhost:993
CONNECTED(00000003)
...
* OK Dovecot ready.
---%<-------------------------------------------------------------------------

Check that GSSAPI appears in the authentication capabilities:

---%<-------------------------------------------------------------------------
a capability
* CAPABILITY ... AUTH=GSSAPI
---%<-------------------------------------------------------------------------

Attempt the first round of GSS communication. The '+' indicates that the server
is ready

---%<-------------------------------------------------------------------------
a authenticate GSSAPI
+
---%<-------------------------------------------------------------------------

Abort the telnet session by typing control-] and then 'close'

---%<-------------------------------------------------------------------------
^]
telnet> close
---%<-------------------------------------------------------------------------

The test:

 * Setup mutt in /etc/Muttrc to use kerberos using gssapi and imap
   configuration
    * this is done with 'set imap_authenticators="gssapi"'
 * run kinit (type in password for kerb)
 * run command mutt
 * If you get error No Authentication Method
    * run command klist (list all kerberos keys) should show imap/HOSTNAME
 * /etc/hosts has to be set properly so that kerberos can find server.

(This file was created from the wiki on 2013-11-24 04:42)