This documentation is for Dovecot v1.x, see wiki2 for v2.x documentation.

Kerberos

Dovecot supports Kerberos 5 using GSSAPI. The Kerberos authentication mechanism doesn't require having a passdb, but you do need a userdb 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 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. 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 with MTA, you will need to install service ticket of the form smtp/hostname@REALM.

In order for Dovecot to determine its principal name properly, it is necessary to have the /etc/hosts file setup properly. This means that the FQDN which is used in the principal name must be associated with an IP address as first entry after the IP address. If the /etc/hosts file is not setup in such a way, an error like this will be logged during authentication process:

While acquiring service credentials: No principal in keytab matches desired name

Example dovecot.conf configurations

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

auth default {
  mechanisms = gssapi
  userdb 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 default {
  mechanisms = plain gssapi
  passdb pam {
  }
  userdb 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 in dovecot.conf:

auth default {
  ..
  passdb 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.

Client support

Mail clients that support Kerberos GSSAPI authentication include:

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:

Authentication/Kerberos (last edited 2010-07-15 09:09:12 by BrankoMajic)