# How to set up Kerberos authentication in network services

Your organization has a [[Kerberos|kerberos]] realm EXAMPLE.COM, or you
[[set one up|tutorials/kerberos_realm]].
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|tutorials/kerberos_client]] 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_.
   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 key for the service principal from the Kerberos KDC using
   [[!template id=man name="kadmin" section="8"]]:
   first `kadmin add` to generate a key for the service principal, 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.

3. Put the keytab in a file readable by the server software, for
   example /etc/dovecot/dovecot.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
   [[!template id=man name="krb5.conf" section="5"]], or
   by creating \_kerberos._host_ TXT records with the realm name in the
   DNS.

[[!toc startlevel=2 levels=1]]

## sshd

[[!template id=man name="sshd" section="8"]] uses service principal
names of the form host/_hostname_ (not ssh/_hostname_).

[[!template id=man name="sshd" section="8"]] always uses the default
system keytab at /etc/krb5.keytab (or wherever it has been set as
`default_keytab_name` in [[!template id=man name="krb5" section="5"]]).

XXX .k5login, aname2lname/auth_to_local mapping

XXX warn against pam_krb5

## postfix (submission)

XXX SASL GSSAPI, via dovecot/cyrus SASL

## apache2 (HTTPS)

HTTP/_hostname_

XXX mod_auth_gssapi (or legacy mod_auth_kerb)

XXX reverse-proxy remote-user

## nginx (HTTPS)

HTTP/_hostname_

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

XXX reverse-proxy remote-user