diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/wiki/Authentication.Kerberos.txt | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/doc/wiki/Authentication.Kerberos.txt b/doc/wiki/Authentication.Kerberos.txt new file mode 100644 index 0000000..d37dc3c --- /dev/null +++ b/doc/wiki/Authentication.Kerberos.txt @@ -0,0 +1,229 @@ +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. With centralized systems, such as +Microsoft Active Directory, LDAP is pretty good choice. + +*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'. + +Setting up (samba) +------------------ + +Create symlink for krb5.conf, if you do not have krb5.conf ready + +---%<------------------------------------------------------------------------- +ln -sf /usr/local/samba/private/krb5.conf /etc/krb5.conf +---%<------------------------------------------------------------------------- + +Create dovecot user to your samba instance (choose random password) + +---%<------------------------------------------------------------------------- +$ samba-tool user create dovecot +New Password: +Retype Password: +User 'dovecot' created successfully +---%<------------------------------------------------------------------------- + +Add Service Principal Names (SPNs) and create keytab + +---%<------------------------------------------------------------------------- +$ samba-tool spn add imap/host.domain.com dovecot +$ samba-tool domain exportkeytab --principal imap/host.domain.com +/etc/dovecot/dovecot.keytab +---%<------------------------------------------------------------------------- + +Dovecot needs to be able to read the keytab + +---%<------------------------------------------------------------------------- +$ chgrp dovecot /etc/dovecot/dovecot.keytab +$ chmod g+r /etc/dovecot/dovecot.keytab +---%<------------------------------------------------------------------------- + +Make sure your keytab has entry for imap/host.domain.name@REALM. + +---%<------------------------------------------------------------------------- +$ klist -Kek /etc/dovecot/dovecot.keytab +Keytab name: FILE:/etc/dovecot/dovecot.keytab +KVNO Principal +---- -------------------------------------------------------------------------- + 1 imap/host.domain.name@REALM (des-cbc-crc) + 1 imap/host.domain.name@REALM (des-cbc-md5) + 1 imap/host.domain.name@REALM (arcfour-hmac) +---%<------------------------------------------------------------------------- + +Example dovecot.conf configurations +----------------------------------- + +If you only want to use Kerberos ticket-based authentication: + +---%<------------------------------------------------------------------------- +auth_gssapi_hostname = "$ALL" +auth_mechanisms = gssapi +auth_krb5_keytab = /etc/dovecot/dovecot.keytab + +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 login gssapi +auth_gssapi_hostname = "$ALL" +auth_mechanisms = gssapi +auth_krb5_keytab = /etc/dovecot/dovecot.keytab +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!) + * Solaris uses _gss_userok() instead of krb5_kuserok() + * v2.2+ has "k5principals" <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.*NOTE*: for this to work, you need a password database + which supports *credential lookups*. + * With 2.2.13, this excludes LDAP databases using authentication binds + (auth_bind = yes). However, a second LDAP passdb entry without "auth_bind + = yes" may be added for the sole purpose of Kerberos principals mapping. + This passdb doesn't need to return a password attribute (and usually + should'nt). + * UPDATE: code seems to have been reworked in later versions. With 2.2.24, + authentication-bind LDAP databases are able to provide k5principals + lookups if configured with "pass_filter". + +Client support +-------------- + +Mail clients that support Kerberos GSSAPI authentication include: + + * Evolution + * Mozilla Thunderbird + * SeaMonkey + * Mutt + * UW Pine + * Apple Mail + +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 + * DNS has to function correctly so that kerberos works. + +(This file was created from the wiki on 2019-06-19 12:42) |