Kerberos

Kerberos is a network authentication system based on the principal of a trusted third party. The other two parties being the user and the service the user wishes to authenticate to. Not all services and applications can use Kerberos, but for those that can, it brings the network environment one step closer to being Single Sign On (SSO).

This section covers installation and configuration of a Kerberos server, and some example client configurations.

Overview

If you are new to Kerberos there are a few terms that are good to understand before setting up a Kerberos server. Most of the terms will relate to things you may be familiar with in other environments:

  • Principal: any users, computers, and services provided by servers need to be defined as Kerberos Principals.

  • Instances: are used for service principals and special administrative principals.

  • Realms: the unique realm of control provided by the Kerberos installation. Think of it as the domain or group your hosts and users belong to. Convention dictates the realm should be in uppercase. By default, ubuntu will use the DNS domain converted to uppercase (EXAMPLE.COM) as the realm.

  • Key Distribution Center: (KDC) consist of three parts: a database of all principals, the authentication server, and the ticket granting server. For each realm there must be at least one KDC.

  • Ticket Granting Ticket: issued by the Authentication Server (AS), the Ticket Granting Ticket (TGT) is encrypted in the user’s password which is known only to the user and the KDC.

  • Ticket Granting Server: (TGS) issues service tickets to clients upon request.

  • Tickets: confirm the identity of the two principals. One principal being a user and the other a service requested by the user. Tickets establish an encryption key used for secure communication during the authenticated session.

  • Keytab Files: are files extracted from the KDC principal database and contain the encryption key for a service or host.

To put the pieces together, a Realm has at least one KDC, preferably more for redundancy, which contains a database of Principals. When a user principal logs into a workstation that is configured for Kerberos authentication, the KDC issues a Ticket Granting Ticket (TGT). If the user supplied credentials match, the user is authenticated and can then request tickets for Kerberized services from the Ticket Granting Server (TGS). The service tickets allow the user to authenticate to the service without entering another username and password.

Kerberos Server

Installation

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

  • Realm: EXAMPLE.COM

  • Primary KDC: kdc01.example.com (192.168.0.1)

  • Secondary KDC: kdc02.example.com (192.168.0.2)

  • User principal: ubuntu

  • Admin principal: ubuntu/admin

Note

It is strongly recommended that your network-authenticated users have their uid in a different range (say, starting at 5000) than that of your local users.

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 section Primary Server of the DNS documentation.

Also, Kerberos is a time sensitive protocol. So 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.

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, which may or may not be the same server, for the realm. 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 is created from the KDC’s domain name.

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.

Configuration

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 Key Distribution Center (KDC) settings simply 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.

Once the KDC is properly running, an admin user – the admin principal – is needed. It is recommended to use a different username from your everyday username. Using the kadmin.local utility in a terminal prompt enter:

$ 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

In the above example ubuntu is the Principal, /admin is an Instance of tha principal, and @EXAMPLE.COM signifies the realm. The “every day” Principal, a.k.a. the user principal, would be ubuntu@EXAMPLE.COM, and should have only normal user rights.

Note

Replace EXAMPLE.COM and ubuntu with your Realm and admin username.

Next, the new admin user needs to have the appropriate Access Control List (ACL) permissions. The permissions are configured in the /etc/krb5kdc/kadm5.acl file:

ubuntu/admin@EXAMPLE.COM        *

This entry grants ubuntu/admin the ability to perform any operation on all principals in the realm. You can configure principals with more restrictive privileges, which is convenient if you need an admin principal that junior staff can use in Kerberos clients. Please see the kadm5.acl man page for details.

Note

The extract privilege is not included in the wildcard privilege; it must be explicitly assigned. his privilege allows the user to extract keys from the database, and must be handled with great care to avoid disclosure of important keys like those of the kadmin/* or krbtgt/* principals. See the kadm5.acl man page for details.

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

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 its 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.

Note

Replace EXAMPLE.COM, kdc01, and kdc02 with your domain name, primary KDC, and secondary KDC.

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, and won’t be shown fully here:

$ 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.

Secondary KDC

Once you have one Key Distribution Center (KDC) on your network, it is good practice to have a Secondary KDC in case the primary becomes unavailable. Also, if you have Kerberos clients that are in different networks (possibly separated by routers using NAT), it is wise to place a secondary KDC in each of those networks.

Note

The native replication mechanism explained here relies on a cronjob, and essentially dumps the DB on the primary and loads it back up on the secondary. You may want to take a look at using the kldap backend which can use the OpenLDAP replication mechanism. It is explained further below.

First, install the packages, and when asked for the Kerberos and Admin server names enter the name of the Primary KDC:

sudo apt install krb5-kdc krb5-admin-server

Once you have the packages installed, create the host principals for both KDCs. From a terminal prompt, enter:

kadmin -q "addprinc -randkey host/kdc01.example.com"
kadmin -q "addprinc -randkey host/kdc02.example.com"

Note

The kadmin command defaults to using a principal like username/admin@EXAMPLE.COM, where username is your current shell user. If you need to override that, use -p <principal-you-want>

Make sure the principal you are using has the extra extract-keys privilege in kdc01's /etc/krb5kdc/kadm5.acl file. Something like this:

ubuntu/admin@EXAMPLE.COM *e

Where “*” means all privileges (except extract-keys), and e means exactly extract-keys.

Extract the keytab file:

kadmin -q "ktadd -norandkey -k keytab.kdc02 host/kdc02.example.com"

There should now be a keytab.kdc02 in the current directory, move the file to /etc/krb5.keytab:

sudo mv keytab.kdc02 /etc/krb5.keytab
sudo chown root:root /etc/krb5.keytab

Note

If the path to the keytab.kdc02 file is different adjust accordingly.

Also, you can list the principals in a Keytab file, which can be useful when troubleshooting, using the klist utility:

sudo klist -k /etc/krb5.keytab

The -k option indicates the file is a keytab file.

Next, there needs to be a kpropd.acl file on each KDC that lists all KDCs for the Realm. For example, on both primary and secondary KDC, create /etc/krb5kdc/kpropd.acl:

host/kdc01.example.com@EXAMPLE.COM
host/kdc02.example.com@EXAMPLE.COM

Create an empty database on the Secondary KDC:

sudo kdb5_util -s create

Now install kpropd daemon, which listens for connections from the kprop utility from the primary kdc:

sudo apt install krb5-kpropd

The service will be running right after installation.

From a terminal on the Primary KDC, create a dump file of the principal database:

sudo kdb5_util dump /var/lib/krb5kdc/dump

Still on the Primary KDC, extract its keytab file and copy it to /etc/krb5.keytab:

kadmin -q "ktadd -k keytab.kdc01 host/kdc01.example.com"
sudo mv keytab.kdc01 /etc/krb5.keytab
sudo chown root:root /etc/krb5.keytab

Note

You can now remove the extract-keys privilege from this principal in kdc01's /etc/krb5kdc/kadm5.acl file

On the Primary KDC, run the kprop utility to push the database dump made before to the Secondary KDC:

$ sudo kprop -r EXAMPLE.COM -f /var/lib/krb5kdc/dump kdc02.example.com
Database propagation to kdc02.example.com: SUCCEEDED

Note the SUCCEEDED message, which signals that the propagation worked. If there is an error message check /var/log/syslog on the secondary KDC for more information.

You may also want to create a cron job to periodically update the database on the Secondary KDC. For example, the following will push the database every hour:

# m h  dom mon dow   command
0 * * * * root /usr/sbin/kdb5_util dump /var/lib/krb5kdc/dump && /usr/sbin/kprop -r EXAMPLE.COM -f /var/lib/krb5kdc/dump kdc02.example.com

Back on the Secondary KDC, create a stash file to hold the Kerberos master key:

sudo kdb5_util stash

Finally, start the krb5-kdc daemon on the Secondary KDC:

sudo systemctl start krb5-kdc.service

Note

The Secondary KDC does not run an admin server, since it’s a read-only copy

From now on, you can specify both KDC servers in /etc/krb5.conf for the EXAMPLE.COM realm, in any host participating in this realm (including kdc01 and kdc02), but remember that there can only be one admin server and that’s the one running on kdc01:

[realms]
    EXAMPLE.COM = {
            kdc = kdc01.example.com
            kdc = kdc02.example.com
            admin_server = kdc01.example.com
    }

The Secondary KDC should now be able to issue tickets for the Realm. You can test this by stopping the krb5-kdc daemon on the Primary KDC, then by using kinit to request a ticket. If all goes well you should receive a ticket from the Secondary KDC. Otherwise, check /var/log/syslog and /var/log/auth.log in the Secondary KDC.

Kerberos Linux Client

This section covers configuring a Linux system as a Kerberos client. This will allow access to any kerberized services once a user has successfully logged into the system.

Note that Kerberos alone is not enough for a user to exist in a Linux system. Meaning, we cannot just point the system at a kerberos server and expect all the kerberos principals to be able to login on the linux system, simply because these users do not exist locally. Kerberos only provides authentication: it doesn’t know about user groups, Linux uids and gids, home directories, etc. Normally another network source is used for this information, such as an LDAP or Windows server, and, in the old days, NIS was used for that as well.

Installation

If you have local users matching the principals in a Kerberos realm, and just want to switch the authentication from local to remote using Kerberos, you can follow this section. This is not a very usual scenario, but serves to highlight the separation between user authentication and user information (full name, uid, gid, home directory, groups, etc). If you just want to be able to grab tickets and use them, it’s enough to install krb5-user and run kinit.

We are going to use sssd with a trick so that it will fetch the user information from the local system files, instead of a remote source which is the common case.

To install the packages enter the following in a terminal prompt:

sudo apt install krb5-user sssd-krb5

You will be prompted for the addresses of your KDCs and admin servers. If you have been following this chapter so far, the KDCs will be: kdc01.example.com kdc02.example.com (space separated)

And the admin server will be: kdc01.example.com. Remember that kdc02 is a read-only copy of the primary KDC, so it doesn’t run an admin server.

Note

If you have added the appropriate SRV records to DNS, none of those prompts will need answering.

Configuration

If you missed the questions earlier, you can reconfigure the package to fill them in again: sudo dpkg-reconfigure krb5-config.

You can test the kerberos configuration by requesting a ticket using the kinit utility. For example:

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

Note

kinit doesn’t need for the principal to exist as a local user in the system. In fact, you can kinit any principal you want. If you don’t specify one, then the tool will use the username of whoever is running kinit.

Since we are at it, let’s also create a non-admin principal for ubuntu:

$ kadmin -q "addprinc ubuntu"
Authenticating as principal ubuntu/admin@EXAMPLE.COM with password.
Password for ubuntu/admin@EXAMPLE.COM: 
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.

The only remaining configuration now is for sssd. Create the file /etc/sssd/sssd.conf with the following content:

[sssd]
config_file_version = 2
services = pam
domains = example.com

[pam]

[domain/example.com]
id_provider = proxy
proxy_lib_name = files
auth_provider = krb5
krb5_server = kdc01.example.com,kdc01.example.com
krb5_kpasswd = kdc01.example.com
krb5_realm = EXAMPLE.COM

The above configuration will use kerberos for authentication (auth_provider), but will use the local system users for user and group information (id_provider).

Adjust the permissions of the config file and start sssd:

$ sudo chown root:root /etc/sssd/sssd.conf
$ sudo chmod 0600 /etc/sssd/sssd.conf
$ sudo systemctl start sssd

Just by having installed sssd and its dependencies, PAM will already have been configured to use sssd, with a fallback to local user authentication. To try it out, if this is a workstation, simply switch users (in the GUI), or open a login terminal (CTRL-ALT-<number>), or spawn a login shell with sudo login, and try logging in using the name of a kerberos principal. Remember that this user must already exist on the local system:

$ sudo login
focal-krb5-client login: ubuntu
Password: 
Welcome to Ubuntu Focal Fossa (development branch) (GNU/Linux 5.4.0-21-generic x86_64)

(...)

Last login: Thu Apr  9 21:23:50 UTC 2020 from 10.20.20.1 on pts/0
$ klist
Ticket cache: FILE:/tmp/krb5cc_1000_NlfnSX
Default principal: ubuntu@EXAMPLE.COM

Valid starting     Expires            Service principal
04/09/20 21:36:12  04/10/20 07:36:12  krbtgt/EXAMPLE.COM@EXAMPLE.COM
	renew until 04/10/20 21:36:12

And you will have a Kerberos ticket already right after login.

Resources

Last updated 3 months ago. Help improve this document in the forum.