How to set up Kerberos authentication in network services

Your organization has a Kerberos realm EXAMPLE.COM, or you set one up. You operate a service such as ssh, SMTP/IMAP/POP, or a web site. How do you kerberize the service to let users authenticate with Kerberos single sign-on instead of juggling passwords?

The answer will vary from service to service, and may sometimes be phrased in terms of GSS-API, but it will always have three parts:

1. Determine the service's principal name, based on the protocol, the service's hostname, and the realm name.

   For example, IMAP uses “imap/hostname” (RFC 9051, IANA GSSAPI/Kerberos/SASL Service Names). So if your users are connecting to the IMAP host imap.example.com, the service principal name will be “imap/imap.example.com” (or “imap/imap.example.com@EXAMPLE.COM” if fully qualified with a realm name).

2. Get a keytab for the service principal from the Kerberos KDC using kadmin(8): first kadmin add to generate a key for the service principal in the KDC database, and then kadmin ext to extract it into a keytab.

   The key is a secret shared between the service and the KDC. Anyone who knows the key can spoof the service, so you must keep it secret.

   You can run kadmin(8) on the KDC itself with kadmin -l (kadmin --local), or you can configure kadmind(8) on the KDC and run kadmin(8) remotely.

3. Put the keytab in a file readable by the server software, for example /usr/pkg/etc/dovecot/private/keytab, and point the software at the keytab and service principal name.

   Some software that uses GSS-API will instead use the GSS-API spelling of a service principal name. For example, IMAP uses “IMAP@hostname”, and HTTPS uses “HTTP@hostname”. The realm name is omitted and must be determined separately, either by setting a default realm or domain-to-realm mapping in krb5.conf(5), or by creating “_kerberos.host” TXT records with the realm name in the DNS.

sshd

sshd(8) uses service principal names of the form “host/hostname” (not “ssh/hostname”).

sshd(8) always uses the default system keytab at /etc/krb5.keytab (or wherever it has been set as default_keytab_name in krb5.conf(5)).

XXX .k5login, aname2lname/auth_to_local mapping

XXX warn against pam_krb5

dovecot (IMAP, POP, SMTP/submission, or any protocol with SASL)

(Main documentation)

1. Create principals for any relevant services—IMAP, POP, SMTP (for Postfix or other MTAs)—and export their keys into a keytab:

   # kadmin add --random-key --max-ticket-life=unlimited \
       --max-renewable-life=unlimited --use-defaults \
       imap/imap.example.com
   # kadmin add --random-key --max-ticket-life=unlimited \
       --max-renewable-life=unlimited --use-defaults \
       pop/pop.example.com
   # kadmin add --random-key --max-ticket-life=unlimited \
       --max-renewable-life=unlimited --use-defaults \
       smtp/mail.example.com
   # mkdir -m 0700 /usr/pkg/etc/dovecot/private
   # cd /usr/pkg/etc/dovecot/private
   # kadmin ext -k keytab imap/imap.example.com
   # kadmin ext -k keytab pop/pop.example.com
   # kadmin ext -k keytab smtp/mail.example.com
   # chown dovecot:dovecot . keytab

2. Make sure gssapi is included in auth_mechanisms:

   /usr/pkg/etc/dovecot/local.conf

   auth_mechanisms = gssapi

3. Point Dovecot at the keytab and allow it to use any of the service principals listed there:

   /usr/pkg/etc/dovecot/local.conf

   auth_krb5_keytab = /usr/pkg/etc/dovecot/private/keytab
   auth_gssapi_hostname = "$ALL"

If you want to map users to local Unix accounts, or are otherwise using a Dovecot userdb without the realm name, so that the user account for Kerberos principal alice@EXAMPLE.COM is alice, set auth_username_format to %n to strip the @ and everything after:

auth_username_format = %n

To use Dovecot exclusively for SASL authentication in other applications like Postfix, you can simply disable all protocols (default includes imap and pop), and provide an auth service at a path used by the other applications:

protocols =
service auth {
    unix_listener /var/spool/postfix/private/auth {
        mode = 0660
        user = postfix
        group = postfix
    }
}

postfix (submission)

(Main documentation)

1. Configure Dovecot for SASL authentication as above.

2. Tell Postfix how to talk to Dovecot in main.cf (postconf(5)):

   /etc/postfix/main.cf

   smtpd_sasl_path = private/auth
   smtpd_sasl_type = dovecot

   Make sure smtpd_sasl_path, taken relative to Postfix's queue_directory, matches the unix_listener path in Dovecot's auth service.

3. Create submission (port 587, RFC 6409) and/or submissions (port 465, RFC 8314) services in master.cf (master(5)) to handle authenticated mail submission:

   /etc/postfix/master.cf

   # service   type private unpriv chroot wakeup maxproc command
   submission  inet n       -      y      -      -       smtpd
      -o smtpd_tls_security_level=encrypt
      -o smtpd_sasl_auth_enable=yes
      -o smtpd_client_restrictions=permit_sasl_authenticated,reject
      -o local_header_rewrite_clients=permit_sasl_authenticated
   submissions inet n       -      y      -      -       smtpd
      -o smtpd_tls_wrappermode=yes
      -o smtpd_sasl_auth_enable=yes
      -o smtpd_client_restrictions=permit_sasl_authenticated,reject
      -o local_header_rewrite_clients=permit_sasl_authenticated

   The difference between submission/587 and submissions/465 is that submission/587 starts as plaintext, and is configured to require a STARTTLS command to start the TLS session, whereas submissions/465 starts immediately with a TLS session. Most mail clients will support both.

   You may also want to set options smtpd_sender_login_maps and smtpd_sender_restrictions to restrict senders to submit MAIL FROM envelope addresses that match their login names.

apache2 (HTTPS)

“HTTP/hostname”

XXX mod_auth_gssapi (or legacy mod_auth_kerb)

XXX reverse-proxy remote-user

XXX single-sign-on option with session cookie

nginx (HTTPS)

“HTTP/hostname”

XXX spnego-http-auth-nginx-module? https://github.com/stnoonan/spnego-http-auth-nginx-module

XXX reverse-proxy remote-user