How to Set Up and Administrate Kerberos

This document is based on Unfurl's instructions on how to set up and administrate Kerberos 5 on FreeBSD 4.x, and some detecive work in the FreeBSD Handbook and the Heimdal Manual.

This document applies to both FreeBSD 4.x and FreeBSD 5.x.

Installing Kerberos

Installing Kerberos on FreeBSD 4.x

For every machine on your network that will authenticate via Kerberos, build and install world with these options enabled in /etc/make.conf:

MAKE_KERBEROS5=yes
KRB5_HOME=/usr/local
ENABLE_SUID_K5SU=yes

Install the security/heimdal port.

Installing Kerberos on FreeBSD 5.1+

Do nothing, its built in. (If you're running 5.0, you need to upgrade, now.)

Initial Kerberos Setup

Kerberos Master

Modify your rc.conf to start the Kerberos services:

kerberos5_server_enable="YES"
kadmind5_server_enable="YES"
kpasswdd5_server_enable="YES"

These respond to running the commands /usr/libexec/kdc &, /usr/libexec/k5admind & and /usr/libexec/k5passwd &, but don't do this just yet.

Kerberos Clients

Note that the Kerberos Master will probably also be a Kerberos client.

Create /etc/krb5.conf with these contents:

[libdefaults]
        default_realm = EXAMPLE.COM

[realms]
        EXAMPLE.COM = {
                kdc = kserver.example.com
                kpasswd_server = kserver.example.com
        }

[domain_realm]
        .example.com = EXAMPLE.COM

Verify that world has been installed with Kerberos:

ldd /usr/sbin/sshd | grep krb

To make k5su work if world wasn't built with ENABLE_SUID_K5SU=yes:

chflags noschg /usr/bin/k5su 
chmod 4555 /usr/bin/k5su
chflags schg /usr/bin/k5su

Initialize the Kerberos database:

# k5admin -l
kadmin> init EXAMPLE.ORG
Max ticket life [unlimited]: 1 day
Max renewable life [unlimited]: 1 week
kadmin> exit

Now you can start the Kerberos services by either rebooting the Kerberos master, or running the following commands:

# /usr/libexec/kdc &
# /usr/libexec/k5admind &
# /usr/libexec/k5passwdd &

Setting up a Kerberos Client Host

This allows a server (other than the Kerberos server) to properly verify the identity of the Kerberos server and vice versa.

You will need to do this if you wish to, for example, ssh into other hosts and be authenticated via Kerberos. pam.conf allows a number of different services to authenticate themselves via Kerberos.

On the Kerberos Master Server

Create new host keytab for the client host:

# k5admin -l
kadmin> ank --random-key host/kclient.example.com
Max ticket life [1 day]:
Max renewable life [1 week]:
Principal expiration time [never]:
Password expiration time [never]:
Attributes []:
kadmin>

Export the new keytab:

kadmin> ext -k /tmp/tmp.keytab host/kclient.example.com

Securely copy kserver:/tmp/tmp.keytab to kclient:/etc/krb5.keytab, and delete it from kserver.

On the Kerberos Client Host

Fix permissions on krb5.keytab:

# chmod 600 /etc/krb5.keytab
# chown root:wheel /etc/krb5.keytab

Setup Client Host Services

Here is how to enable Kerberos authentication for sshd.

Change /etc/ssh/sshd_config to allow Kerberos authentication:

ChallengeResponseAuthentication yes
KerberosAuthentication yes
KerberosOrLocalPasswd no
KerberosTicketCleanup yes

Change /etc/pam.conf entries to allow Kerberos authentication:

#sshd		auth		sufficient	pam_skey.so
#sshd		auth		sufficient	pam_opie.so		no_fake_prompts
#sshd		auth		required	pam_opieaccess.so
#sshd		auth		sufficient	pam_kerberosIV.so	try_first_pass
sshd		auth		sufficient	pam_krb5.so		try_first_pass
sshd		auth		required	pam_unix.so		try_first_pass
sshd		account		required	pam_unix.so
sshd		password	required	pam_permit.so
sshd		session		required	pam_permit.so

If you'd like, you can make similar modifications for other services, like login. With this setup, sshd will first attempt to authenticate against the Kerberos server. If that fails, it will look in the UNIX password file.

Add Kerberos principals to /root/.k5login for people that should have ksu access:

your_username/root@EXAMPLE.COM

Note that if you have a machine that won't always be attached to the network, you will want to setup /etc/pam.conf like this:

sshd		auth		sufficient	pam_unix.so		try_first_pass
sshd		auth		required	pam_krb5.so		try_first_pass
sshd		account		required	pam_unix.so
sshd		password	required	pam_permit.so
sshd		session		required	pam_permit.so

This tries the local machine's password first, then the Kerberos machine's password.

User Management

Adding New Users

Note: this can only be done on the Kerberos master server:

# k5admin -l
kadmin> add_new_key newuser
Max ticket life [1 day]:
Max renewable life [1 week]:
Principal expiration time [never]:
Password expiration time [never]:
Attributes []:
newuser@EXAMPLE.COM's Password: 
Verifying password - newuser@EXAMPLE.COM's Password: 
kadmin>

Changing a User's Password

Users can change their own passwords on any kerberized machine with the k5passwd(1) program as long as they know their old password. If they forget their password a Kerberos admin will have to do it for them. This can only be accomplished using the kadmin tool.