This post describes how to install using MIT Kerberos version 5 in a Debian GNU/Linux system. The installation of Heimdal should be similar but is not addressed in this document.
Packages installation
This document considers four kinds of hosts:
- master: the master KDC (Key Distribution Center), i.e. the central authentication and administration server,
- slave: a slave KDC, that mirrors a master KDC,
- server: a host that offers Kerberos-authenticated access to services,
- client: a host that accessed Kerberos-authenticated services offered by a server.
The krb5-user package must be installed on every host, including KDC servers and application servers. The krb5-kdc package must be installed on every KDC server, either master or slave. The krb5-admin-server package must be installed only on the master KDC:
root@master> apt-get install krb5-admin-server root@slave> apt-get install krb5-kdc root@client> apt-get install krb5-user root@server> apt-get install krb5-user
Configuration of NTP
The clocks of all hosts (KDCs, servers and clients) must be synchronized. One way is to use NTP. One server must be configured as an NTP server, by installing the ntp-simple package:
root@server> apt-get install ntp-server ntp-simple
The ntpdate packages must then be installed on every other host:
root@host> apt-get install ntpdate
On every host, put the NTP server host name as the value of the NTPSERVERS variable in the /etc/default/ntpdate file.
Configuration of /etc/krb5.conf
The /etc/krb5.conf file is mainly configured through debconf in package krb5-config. The main purpose of this file is to define the default Kerberos realm, and the mapping of the domain name of a service that is accessed, to the realm used to authenticate when accessing that service. A Kerberos realm is an identifier for a domain of authentication. It is usually the DNS domain name in upper-case. In this document, the realm is CSG.IS.TITECH.AC.JP.
In the debconf configuration of krb5-config, Kerberos 4 support should be disabled, in order to allow only Kerberos 5 authentication (which is more secure). As a recommended practice, generic host names should be used: the master KDC host should be named kerberos, and the slave KDC hosts should be named kerberos-1, kerberos-2, etc. The FQDN (Fully Qualified Domain Name, i.e. the host name appended with the DNS domain name) of every KDC host must be given in thekrb5-config package configuration.
WARNING: The master and slave KDC servers bind to the external network interfaces, and cannot be connected by clients if referring to a non-external network interface such as 127.*.*.*. Therefore a valid FQDN or a non-variable IP address must be given to refer to the KDC servers.
The debconf configuration of krb5-config results in the generation of the /etc/krb5.conf file. A /etc/krb5.conf is required on every client, server and KDC server.
It must be noted that, from a service / server point of view, the realm used for authenticating when accessing a service is by default the upper-case conversion of the DNS domain name of the accessed server hostname. Thus, it would be required to handle one Kerberos realm for every DNS domain name. It is however possible to define only one realm for several DNS domains, by adding lines in the [domain_realm] section in /etc/krb5.conf, on every host. For instance, to use the CSG.IS.TITECH.AC.JP realm when accessing hosts in DNS domain csg.is.titech.ac.jp and all its sub-domains, the following two lines must be added:
[domain_realm] ... .csg.is.titech.ac.jp = CSG.IS.TITECH.AC.JP csg.is.titech.ac.jp = CSG.IS.TITECH.AC.JP
An alternative and more centralized way to configure mappings between DNS domain names and Kerberos realms is to add Kerberos-specific entries into the DNS. Since DNS may be subject to spoofing, that method is less secure, and is not described in this post. See: http://web.mit.edu/kerberos/www/krb5-1.4/krb5-1.4.1/doc/krb5-admin/Using-DNS.html
Configuration of /etc/krb5kdc/kdc.conf
The KDC master and slaves additionnally require a /etc/krb5kdc/kdc.conf file to be created, that defines the realm managed by the KDC. This file can be generated using the Debian-specific command krb5_newrealm provided in packagekrb5-config, on the master KDC server. However, the following describes instead the use of the standard kdb5_util command:
root@master> kdb5_util -r CSG.IS.TITECH.AC.JP create -s
This command automatically initializes the realm CSG.IS.TITECH.AC.JP in the KDC, and creates a master key principal K/M@CSG.IS.TITECH.AC.JP. The password must be remembered, as it is needed to repair the KDC database. Then, the KDC master servers can be started:
root@master> touch /etc/krb5kdc/kadm5.acl root@master> /etc/init.d/krb5-kdc start root@master> /etc/init.d/krb5-admin-server start
A first user principal must be created for administration. A principal is an identifier to which capabilities are attached. An user principal name has the form primary/secondary@realm: the primary part should be a valid Unix user name, and the/secondary part is optional and may be used to distinguish the different identities of a single user. For instance, my Unix user is lenglet, and one of my identities is dedicated to system administration. It is a common practice to create principals with /admin as a secondary part, for administration purposes. I therefore create a lenglet/admin@CSG.IS.TITECH.AC.JP principal:
root@master> kadmin.local kadmin.local: add_principal -clearpolicy lenglet/admin kadmin.local: quit
The kadmin.local command is the master KDC administration client, that locally interacts with the administration server, and does not involve remote access nor authentication to modify the database. The kadmin command is an equivalent command, to remotely manage the KDC database, that uses Kerberos authentication. At this point in the installation, only the kadmin.local can be used, although the kadmin command is the preferred command (and having any other remote access to the KDC servers, e.g. through remote shell, is not recommended for the sake of security).
Configuration of administration privileges
Administration of the Kerberos database remotely (using the kadmin command) requires to grant privileges to the principal used to authenticate to the administration server. The administration privileges are defined in the /etc/krb5kdc/kadm5.acl file. For instance, to grant all administrative privileges to the lenglet/admin principal created above:
root@master> echo 'lenglet/admin *' >> /etc/krb5kdc/kadm5.acl root@master> /etc/init.d/krb5-admin-server restart
It is now possible to login to the Kerberos KDC using the lenglet/admin principal:
lenglet@client> kinit lenglet/admin
and to test the privileges of that principal, by creating a new lenglet principal:
lenglet@client> kadmin -p lenglet/admin kadmin: add_principal lenglet kadmin: quit
It is now possible to login to the Kerberos KDC using the lenglet principal (by default, the principal name is the same as the Unix user name, with no secondary part):
lenglet@client> kdestroy lenglet@client> kinit lenglet@client> klist lenglet@client> kdestroy
Kerberos authentication using PAM (Pluggable Authentication Modules)
The example authentication scenario above directly uses the Kerberos commands (kinit, kdestroy, etc.), after login into the client host. It is however possible to use Kerberos authentication to login into client hosts, and to automatically obtain at login a Kerberos TGT (Ticket Granting Ticket) just like kinit does, by using the Kerberos PAM modules. On all client hosts, the Kerberos PAM module must be installed:
root@client> apt-get install libpam-krb5
I decided to group in one file (/etc/pam.d/common-kerberos) the configuration for Kerberos authentication, independently from services. The content of this file is:
auth sufficient pam_krb5.so try_first_pass forwardable account sufficient pam_krb5.so password sufficient pam_krb5.so try_first_pass
Then this file is included in all local only login applications PAM files, by adding the following line at the end of those files:
@include common-kerberos
On a typical client host with KDE installed, only the /etc/pam.d/kdm and /etc/pam.d/login files need to be modified.
Adding those lines at the end of files (in conjunction with the try_first_pass flag) makes Kerberos authentication transparent to local users, and if a user is defined in both NSS (e.g. in /etc/passwd or in an LDAP directory) and Kerberos, a TGT is granted transparently to the user at login.
To test, logout from the client host, login again, and check that a TGT has been granted:
lenglet@client> klist
Common kerberized servers
Standard Kerberos-enhanced server programs for remote access (remote shell, remote FTP, etc.) are available in separate packages:
root@server> apt-get install krb5-ftpd krb5-rsh-server krb5-telnetd
Every service must be explicitely identified with a specific principal in the KDC servers. More precisely, two principals must be created: host/serverfqdn for all the services on the server, and ftp/serverfqdn for the FTP service, etc., all with a random password / key unlike principals for normal users (this is configured with the -randkey option):
root@server> kadmin -p lenglet/admin kadmin: add_principal -randkey host/serverfqdn kadmin: add_principal -randkey ftp/serverfqdn kadmin: quit
The generated password / key associated with those principals is a shared secret between the server and the KDC. The principals generated above must therefore be copied into a key table file (keytab) on the server, using the kadmin command. The default keytab file is /etc/krb5.keytab. To add the principals to the keytab, the user running kadmin must be root, because the /etc/krb5.keytab file can be modified only by root on the server:
root@server> kadmin -p lenglet/admin kadmin: ktadd host/serverfqdn kadmin: ktadd ftp/serverfqdn kadmin: quit
To list the keys in the keytab file:
root@server> klist -k /etc/krb5.keytab
WARNING: the server FQDN (as returned by the hostname command on the server) must be exactly the same as the serverfqdn string, because the kerberized servers use that FQDN to look for keys in the keytab file.
Common kerberised clients
The corresponding Kerberos-enhanced client programs must be installed on every client:
root@client> apt-get install krb5-clients
It is then possible to use the kerberized services installed on a server:
lenglet@client> krb5-ftp serverfqdn lenglet@client> telnet.krb5 -a serverfqdn lenglet@client> telnet.krb5 -x serverfqdn
It must be noted that the -a option must be given to kerberized telnet to enforce automatic login (i.e., Kerberos authentication), or the -x option to do that and additionally enforce encryption, otherwise the kerberized server refuses the connection (no unsecure connection is enabled in the Debian packages).
lenglet@client> krb5-rlogin -x serverfqdn lenglet@client> krb5-rsh -x serverfqdn ls
It must be noted that the -x option must be given to the kerberized rlogin and rsh to enforce encryption, otherwise the kerberized servers refuse the connection.