How to install a Kerberos server

Note:
This documentation has moved to a new home! Please update your bookmarks to the new URL for the up-to-date version of this page.

For this discussion, we will create an MIT Kerberos domain with the following features (edit them to fit your needs):

  • Realm: EXAMPLE.COM
  • Primary KDC: kdc01.example.com
  • Secondary KDC: kdc02.example.com
  • User principal: ubuntu
  • Admin principal: ubuntu/admin

Prerequisites

Before installing the Kerberos server, a properly configured DNS server is needed for your domain. Since the Kerberos realm (by convention) matches the domain name, this section uses the EXAMPLE.COM domain configured in the primary server section of the DNS documentation.

Also, Kerberos is a time sensitive protocol. If the local system time between a client machine and the server differs by more than five minutes (by default), the workstation will not be able to authenticate. To correct the problem all hosts should have their time synchronized using the same Network Time Protocol (NTP) server. Check out the NTP chapter for more details.

Install the Kerberos packages

The first step in creating a Kerberos realm is to install the krb5-kdc and krb5-admin-server packages. From a terminal enter:

sudo apt install krb5-kdc krb5-admin-server

You will be asked at the end of the install to supply the hostname for the Kerberos and Admin servers for the realm, which may or may not be the same server. Since we are going to create the realm, and thus these servers, type in the full hostname of this server.

Note:
By default the realm name will be domain name of the Key Distribution Center (KDC) server.

Next, create the new realm with the kdb5_newrealm utility:

sudo krb5_newrealm

It will ask you for a database master password, which is used to encrypt the local database. Chose a secure password: its strength is not verified for you.

Configure the Kerberos server

The questions asked during installation are used to configure the /etc/krb5.conf and /etc/krb5kdc/kdc.conf files. The former is used by the Kerberos 5 libraries, and the latter configures the KDC. If you need to adjust the KDC settings, edit the file and restart the krb5-kdc daemon. If you need to reconfigure Kerberos from scratch, perhaps to change the realm name, you can do so by typing:

sudo dpkg-reconfigure krb5-kdc

Note:
The manpage for krb5.conf is in the krb5-doc package.

Let’s create our first principal. Since there is no principal create yet, we need to use kadmin.local, which uses a local UNIX socket to talk to the KDC, and requires root privileges:

$ sudo kadmin.local
Authenticating as principal root/admin@EXAMPLE.COM with password.
kadmin.local: addprinc ubuntu
WARNING: no policy specified for ubuntu@EXAMPLE.COM; defaulting to no policy
Enter password for principal "ubuntu@EXAMPLE.COM": 
Re-enter password for principal "ubuntu@EXAMPLE.COM": 
Principal "ubuntu@EXAMPLE.COM" created.
kadmin.local: quit

To be able to use kadmin remotely, we should create an admin principal. Convention suggests it should be an admin instance, as that also makes creating a generic Access Control List (ACL) easier. Let’s create an admin instance for the ubuntu principal:

$ sudo kadmin.local
Authenticating as principal root/admin@EXAMPLE.COM with password.
kadmin.local: addprinc ubuntu/admin
WARNING: no policy specified for ubuntu/admin@EXAMPLE.COM; defaulting to no policy
Enter password for principal "ubuntu/admin@EXAMPLE.COM": 
Re-enter password for principal "ubuntu/admin@EXAMPLE.COM": 
Principal "ubuntu/admin@EXAMPLE.COM" created.
kadmin.local: quit

Next, the new admin principal needs to have the appropriate ACL permissions. The permissions are configured in the /etc/krb5kdc/kadm5.acl file:

ubuntu/admin@EXAMPLE.COM        *

You can also use a more generic form for this ACL:

*/admin@EXAMPLE.COM        *

The above will grant all privileges to any admin instance of a principal. See the kadm5.acl manpage for details.

Now restart the krb5-admin-server for the new ACL to take effect:

sudo systemctl restart krb5-admin-server.service

The new user principal can be tested using the kinit utility:

$ kinit ubuntu/admin
Password for ubuntu/admin@EXAMPLE.COM:

After entering the password, use the klist utility to view information about the Ticket Granting Ticket (TGT):

$ klist
Ticket cache: FILE:/tmp/krb5cc_1000
Default principal: ubuntu/admin@EXAMPLE.COM

Valid starting     Expires            Service principal
04/03/20 19:16:57  04/04/20 05:16:57  krbtgt/EXAMPLE.COM@EXAMPLE.COM
     renew until 04/04/20 19:16:55

Where the cache filename krb5cc_1000 is composed of the prefix krb5cc_ and the user id (UID), which in this case is 1000.

kinit will inspect /etc/krb5.conf to find out which KDC to contact, and the corresponding address. The KDC can also be found via DNS lookups for special TXT and SRV records. You can add these records to your example.com DNS zone:

_kerberos._udp.EXAMPLE.COM.     IN SRV 1  0 88  kdc01.example.com.
_kerberos._tcp.EXAMPLE.COM.     IN SRV 1  0 88  kdc01.example.com.
_kerberos._udp.EXAMPLE.COM.     IN SRV 10 0 88  kdc02.example.com. 
_kerberos._tcp.EXAMPLE.COM.     IN SRV 10 0 88  kdc02.example.com. 
_kerberos-adm._tcp.EXAMPLE.COM. IN SRV 1  0 749 kdc01.example.com.
_kpasswd._udp.EXAMPLE.COM.      IN SRV 1  0 464 kdc01.example.com.

See the DNS chapter for detailed instructions on setting up DNS.

A very quick and useful way to troubleshoot what kinit is doing is to set the environment variable KRB5_TRACE to a file, or stderr, and it will show extra information. The output is quite verbose:

$ KRB5_TRACE=/dev/stderr kinit ubuntu/admin
[2898] 1585941845.278578: Getting initial credentials for ubuntu/admin@EXAMPLE.COM
[2898] 1585941845.278580: Sending unauthenticated request
[2898] 1585941845.278581: Sending request (189 bytes) to EXAMPLE.COM
[2898] 1585941845.278582: Resolving hostname kdc01.example.com
(...)

Your new Kerberos realm is now ready to authenticate clients.

I struggled with the Secondary KDC instructions, and ended up referring to the Red Hat Guide to supplement my understanding. Here were things that weren’t clear to me:

  1. Why the use of the 'extract-key’s privilege? This privilege was unnecessary for me on Ubuntu 20.04, and I don’t see it documented in MIT’s documentation.
  2. Why the use of ‘-norandkey’ when generating the keytab?
  3. Why add kdc02 to the kpropd.acl on the secondary KDC?

Places where I got stuck:

  1. I tried to initialize a new realm on the secondary KDC. This is wrong; you want to create the stash file that’s overwritten on the first realm sync. According to Red Hat’s documentation, the master key of the stash file must match the master key of the primary KDC’s stash file.
  2. I kept getting a ’ Service key not available’ during the manual sync. It took me a long time to notice the result of hostname -f didn’t match the secondary KDC’s Kerberos principal name. Maybe we could add a warning about that?

Also, this page was a useful reference for many failure modes; might be good for the References section: http://research.imb.uq.edu.au/~l.rathbone/ldap/kerberos.shtml

Thanks for the feedback. It’s good to know how well folks are getting along with the documentation and ways we can make it better. We’ll see how we can incorporate your feedback to make it better.

1 Like

Thanks for your comments. I also thought it was weird to need this new extract privilege, but it only worked with that. I’ll revise this.