Infrastructure at your Service

Morgan Patou

How to install and manage a Kerberos Server

For some time now, I have been working on how to set up a Single Sign-On (SSO) solution in my company. As a big fan of Open Source solutions, I have obviously proposed the implementation of a solution based on Kerberos. What I mean by that is a solution based on the true Kerberos, i. e. MIT Kerberos. Indeed, Kerberos was originally a research project at the Massachusetts Institute for Technology (MIT) in the early 1980s.

Before starting this kind of project, it’s important to clearly define and have in mind the following points:

  • Architecture of the enterprise
  • Operating systems used by end users
  • Operating systems used by applications which must be kerberized
  • Is it difficult to kerberized these applications?

The answers to these elements provide insight on which types of solutions are possible. For example if there is no restrictions on which operating system an end user can use (Windows or different Linux distribution or …) then the introduction of a solution based on a Linux Kerberos could be a good idea. That’s why in this blog, I will first explain how to install a MIT Kerberos Server. In the second part, I will focus on how to manage this Server.

1. Install MIT Kerberos

It’s important to note that the server and the client share the same release and that the MIT Keberos server could only be installed on a Unix-like. The Mac release is available as part of the Mac OS X since version 10.3 (the current release is Mavericks: 10.9). The Key Distribution Center (KDC) is the Kerberos Server where all identities (users, computers and kerberized applications) will be stored.

For this installation, let’s define the followings properties/variable:

  • example.com = the DNS Domain
  • EXAMPLE.COM = the KDC REALM which should be the DNS Domain in UPPERCASE. In case where there should be more than one KDC, all names must be unique and self descriptive
  • kdc01oel.example.com = the FQDN of the KDC
  • 192.168.1.2 = the IP of kdc01oel.example.com

So let’s begin the installation. Obviously, the first thing to do is to download the current release of the MIT Kerberos distribution for the target operating system. This could be done at the following URL: http://web.mit.edu/kerberos/dist/index.html. The current Linux release is krb5-1.12.1-signed.tar:

[[email protected] opt]# wget http://web.mit.edu/kerberos/dist/krb5/1.12/krb5-1.12.1-signed.tar
--2014-04-01 14:00:28--  http://web.mit.edu/kerberos/dist/krb5/1.12/krb5-1.12.1-signed.tar
Resolving web.mit.edu... 23.58.214.151
Connecting to web.mit.edu|23.58.214.151|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 11950080 (11M) [application/x-tar]
Saving to: “krb5-1.12.1-signed.tar”
100%[===============================================>] 11,950,080  1.52M/s   in 7.3s
2014-04-01 14:00:38 (1.56 MB/s) - “krb5-1.12.1-signed.tar” saved [11950080/11950080]
[[email protected] opt]# tar -xvf krb5-1.12.1-signed.tar
krb5-1.12.1.tar.gz
krb5-1.12.1.tar.gz.asc

 

As you could see, this file is signed and you could (should) verify the integrity and identity of the software. This can be done, for example, using GNU Privacy Guard (need another file that can be found on the MIT Kerberos download page):

[[email protected] opt]# gpg --verify krb5-1.12.1.tar.gz.asc

 

After that, just extract the MIT Kerberos source code and build it:

[[email protected] opt]# tar -zxf krb5-1.12.1.tar.gz
[[email protected] opt]# cd krb5-1.12.1/src/
[[email protected] src]# ./configure
...
[[email protected] src]# yum install *yacc*
...
[[email protected] src]# make
...
[[email protected] src]# make install
...

 

At this step, Kerberos should be installed properly and the binaries, libraries and the documentation should be under /usr/local. The default location is sufficient in almost all cases:

[[email protected] src]# krb5-config --all
Version:     Kerberos 5 release 1.12.1
Vendor:      Massachusetts Institute of Technology
Prefix:      /usr/local
Exec_prefix: /usr/local

As Kerberos should be installed properly, the next step is to configure it. This is done through a configuration file named krb5.conf:

[[email protected] src]# vi /etc/krb5.conf
[libdefaults]
  default_realm = EXAMPLE.COM
  forwardable = true
  proxiable = true
[realms]
  EXAMPLE.COM = {
    kdc = kdc01oel.example.com:88
    admin_server = kdc01oel.example.com:749
    default_domain = example.com
  }
[domain_realm]
  .example.com = EXAMPLE.COM
  example.com = EXAMPLE.COM
[logging]
  kdc = FILE:/var/log/krb5kdc.log
  admin_server = FILE:/var/log/kadmin.log
  default = FILE:/var/log/krb5lib.log

 

To avoid hostname resolution issues, the file /etc/hosts must contain the fully qualified domain name of the server as well as the IP address:

[[email protected] src]# vi /etc/hosts
127.0.0.1         localhost   kdc01oel
192.168.1.2       kdc01oel.example.com   kdc01oel

 

The next thing to do is to create the realm and the KDC database. Let’s begin with the creation of the database parent folder:

[[email protected] src]# cd /usr/local
[[email protected] local]# mkdir /usr/local/var
[[email protected] local]# mkdir /usr/local/var/krb5kdc
[[email protected] local]# chmod 700 /usr/local/var/krb5kdc

 

The file krb5.conf (just above) is the generic Kerberos configuration file but the KDC also has is own configuration file (kdc.conf). Create this file and populate it as follow:

[[email protected] local]# cd /usr/local/var/krb5kdc/
[[email protected] krb5kdc]# vi kdc.conf
[kdcdefaults]
  kdc_ports = 749,88
[realms]
  EXAMPLE.COM = {
    database_name = /usr/local/var/krb5kdc/principal
    admin_keytab = /usr/local/var/krb5kdc/kadm5.keytab
    acl_file = /usr/local/var/krb5kdc/kadm5.acl
    key_stash_file = /usr/local/var/krb5kdc/.k5.EXAMPLE.COM
    kdc_ports = 749,88
    max_life = 10h 0m 0s
    max_renewable_life = 7d 0h 0m 0s
  }

 

So let’s create the Kerberos database using this configuration file:

[[email protected] krb5kdc]# /usr/local/sbin/kdb5_util create -s
Loading random data
Initializing database '/usr/local/var/krb5kdc/principal' for realm 'EXAMPLE.COM',
master key name 'K/[email protected]'
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key: 
Re-enter KDC database master key to verify:
[[email protected] krb5kdc]#

 

If there is any error at this point, it is certainly due to a misconfiguration of the /etc/krb5.conf file or because Kerberos can’t resolve the hostname (the /etc/hosts file isn’t configure properly).

This finaly conclude the first part about the installation of the MIT Kerberos Server.

2. Manage the KDC

For this part, I assume that the KDC is set up according to what I’ve explain above. In the previous part, I just shown how to install the KDC but in fact the KDC isn’t running for the moment. So the first thing to do is to configure which will be able to connect to the KDC (that mean obtain a ticket) and with which permissions.

To enter to the KDC administration console, use the kadmin.local (only for the local machine):

[[email protected] krb5kdc]# /usr/local/sbin/kadmin.local
Authenticating as principal root/[email protected] with password.
kadmin.local:

Once in the kadmin.local, several command can be used to manage the KDC. The following command can be used to list them all:

kadmin.local:  ?
Available kadmin.local requests:
add_principal, addprinc, ank
                         Add principal
delete_principal, delprinc
                         Delete principal
modify_principal, modprinc
                         Modify principal
rename_principal, renprinc
                         Rename principal
change_password, cpw     Change password
get_principal, getprinc  Get principal
list_principals, listprincs, get_principals, getprincs
                         List principals
add_policy, addpol       Add policy
modify_policy, modpol    Modify policy
delete_policy, delpol    Delete policy
get_policy, getpol       Get policy
list_policies, listpols, get_policies, getpols
                         List policies
get_privs, getprivs      Get privileges
ktadd, xst               Add entry(s) to a keytab
ktremove, ktrem          Remove entry(s) from a keytab
lock                     Lock database exclusively (use with extreme caution!)
unlock                   Release exclusive database lock
purgekeys                Purge previously retained old keys from a principal
get_strings, getstrs     Show string attributes on a principal
set_string, setstr       Set a string attribute on a principal
del_string, delstr       Delete a string attribute on a principal
list_requests, lr, ?     List available requests.
quit, exit, q            Exit program.

So for example let’s create two principal. One with administrator capabilities (xxx/admin) and another one without:

kadmin.local:  addprinc mpatou/admin
WARNING: no policy specified for mpatou/[email protected]; defaulting to no policy
Enter password for principal "mpatou/[email protected]": 
Re-enter password for principal "mpatou/[email protected]": 
Principal "mpatou/[email protected]" created.
kadmin.local:  addprinc mpatou
WARNING: no policy specified for [email protected]; defaulting to no policy
Enter password for principal "[email protected]": 
Re-enter password for principal "[email protected]": 
Principal "[email protected]" created.

With a new “listprincs”, the two new principals should be displayed but for now, mpatou/admin has no administrative access because this account isn’t declared in the access control list. In the ACL file, permissions can be defined by using the following characters:

  • A = Addition of users or policies into the KDC database
  • D = Deletion of users or policies from the KDC database
  • M = Modification of users or policies in the KDC database
  • C = Changing principals’ passwords in the KDC database
  • I = Inquiries into the database, to list principal information
  • L = Listing of the principals contained in the database
  • * = Grants the user all of the above permissions

Moreover, the wildcard (*) can be used to match more than one user. For example */admin will match all administrative account. Let’s create the ACL file as define in the KDC configuration file (kdc.conf):

kadmin.local:  exit
[[email protected] krb5kdc]# vi /usr/local/var/krb5kdc/kadm5.acl
*/[email protected]        ADMCIL

 

So there is a kadmin.local for local administration but there is also a remote administration console which is kadmin. This remote access can’t be used for now because it need a file that doesn’t exist. This file (a “keytab”), is a file that store a principal and an encryption key derived from the principal’s password. It could be used to log into Kerberos without being prompted for a password and that’s why this is useful for all kerberized applications.

[[email protected] krb5kdc]# /usr/local/sbin/kadmin.local
Authenticating as principal root/[email protected] with password.
kadmin.local:  ktadd -k /usr/local/var/krb5kdc/kadm5.keytab kadmin/admin kadmin/changepw
Entry for principal kadmin/admin with kvno 2, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
Entry for principal kadmin/admin with kvno 2, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
Entry for principal kadmin/admin with kvno 2, encryption type des3-cbc-sha1 added to keytab WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
Entry for principal kadmin/admin with kvno 2, encryption type arcfour-hmac added to keytab WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
Entry for principal kadmin/changepw with kvno 2, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
Entry for principal kadmin/changepw with kvno 2, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
Entry for principal kadmin/changepw with kvno 2, encryption type des3-cbc-sha1 added to keytab WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
Entry for principal kadmin/changepw with kvno 2, encryption type arcfour-hmac added to keytab WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
kadmin.local:  exit

The location of this kadm5.keytab is also define in the kdc.conf file. Now the KDC server process is ready to start:

[[email protected] krb5kdc]# /usr/local/sbin/krb5kdc
[[email protected] krb5kdc]# /usr/local/sbin/kadmind

If there is no error, then the KDC should be running and ready to reply to any client with a valid principal. The easiest way to test it is to try to obtain a TGT (Ticket Granting Ticket) using the kinit command:

[[email protected] krb5kdc]# cd /usr/local/bin
[[email protected] bin]# klist 
klist: Credentials cache file '/tmp/krb5cc_0' not found
[[email protected] bin]# kinit mpatou
Password for [email protected]: 
[[email protected] bin]# klist 
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: [email protected]
Valid starting       Expires              Service principal
04/03/2014 09:54:48  04/03/2014 19:54:48  krbtgt/[email protected]
    renew until 04/04/2014 09:54:47
[[email protected] bin]# kdestroy
[[email protected] bin]# klist 
klist: Credentials cache file '/tmp/krb5cc_0' not found

 

The klist command can be used to list all existing tickets whereas the kdestroy is used to remove them. The KDC is now fully operational and some possible additional steps can be done (e.g. set up slaves KDC).

This finally concludes this blog about how to install a MIT Kerberos Server. If you need more information about Kerberos (MIT or Heimdal or Active Directory implementation), I strongly suggest you to read the book “Kerberos, The Definitive Guide” by Jason Garman. This book was for me the best source of knowledge on this subject.

5 Comments

  • Anthony Boutinov says:

    I was following your article step-by-step (but with krb5-1.12.2 release) and had some difficulties during the process. So I decided to make it easy for those who might experience the similar situation.

    First, I had to run ‘make’ and ‘make install’ commands twice, because otherwise it didn’t work. So frustrating!

    Another thing was that command ‘kinit mpatou’ replied with something like ‘no such user found’, so I used ‘kinit mpatou/admin’ instead.

  • Morgan Patou says:

    Hi Anthony,

    The fact that you had to run the ‘make’ and ‘make install’ commands twice isn’t something normal. On which Operating System did you try to install your Kerberos server? Does the first command fail due to an error?

    If the command ‘kinit mpatou’ reply with ‘no such user found’, it means that the user [email protected] doesn’t exist. If you take a look at my step by step guide, I create two different users using the following commands:
    addprinc mpatou/admin —> This create the user mpatou/[email protected]
    addprinc mpatou —> This create the user [email protected]

    That fact that only ‘kinit mpatou/admin’ worked looks like you only create the user mpatou/admin. If you want to display all users created, you can use the command ‘listprincs’ (using kadmin or kadmin.local). Could you please ensure that both users have been created?

    Best regards,
    Morgan

  • hema says:

    hi

    when i type make command i’m getting below mentioned error.

    make[2]: Entering directory ‘/root/krb5-1.12.1/src/kadmin/cli’
    /usr/bin/install -c kadmin.local /usr/local/sbin/kadmin.local

    please help me to resolve this

    • Morgan Patou says:

      Hi Hema,

      The message you printed isn’t an error. Could you try to run the make command again? Maybe put the source under /opt like I did? I do not really like to do something like that under /root. Then please put the whole trace.

      Regards,
      Morgan

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Morgan Patou
Morgan Patou

Senior Consultant & Technology Leader ECM