Kerberos Mac OS X Implementation (Part Two in a Series)
18 January 2004
If you just finished reading part 1, take a break. Kick back on a natural for a bit and let Kerberos sink in. Perhaps re-read the article if things are a bit fuzzy—just a suggestion.If you feel comfortable with Kerberos, let’s now talk about how Apple has actually implemented it. As I mentioned before Apple now includes a full KDC in Mac OS X 10.3 Panther Server. It will act, walk and talk like a standard MIT Kerberos v5 KDC to anyone who wants to talk with it. Of course if Apple just stopped there, it wouldn’t really be Apple would it?
Apple took a standard MIT Kerberos distribution, made sure that it stayed compatible with other MIT Kerberos systems and added on a few bits that are almost as ingenious as Kerberos itself.
In this part of the series, I’ll walk through Kerberos as it is implemented on Mac OS X, covering what Apple has added and any major differences between what’s on Mac OS X and what’s on other MIT Kerberos systems.
1. The KDC
If you set up your Panther Server as an Open Directory Master, and everything is copacetic with you DNS, you will automagically become a Kerberos Key Distribution Center (KDC). This process is so automatic that you literally won’t see it happen. There is no “Kerberos” button or any GUI configuration for it. It’s just there. It’s so stealthy that the only indication from the admin tools that it’s actually running is a single entry in the Open Directory section of Server Admin that says whether or not the KDC is running.
On a standard MIT Kerberos system, you need to do a bit of work to get it up and running. After you have it installed, since it usually doesn’t come pre-built on systems, you need to initialize the KDC’s password database and then create principles for the KDC, any services you might be hosting, and then start in on the users' principles.
It’s with the user principles that you have to begin veering from the beaten path.
Kerberos only handles user password. It doesn’t store any information about the user whatsoever. This means that even if you are running Kerberos, you will still need to keep your user records in a directory service of some sort. This can be almost anything, ie. NIS, LDAP, MySQL, or even flat files, but you have to have it. Additionally not all services understand Kerberos. There is no easy way of authenticating a user via Kerberos for WebDAV shares and web realms for example, but it is possible.
All of this means that you’ll have to set up a directory service in addition to Kerberos. To allow non-kerberized services to authenticate you’ll also have to set up either some sort of Kerberos authentication gateway, or just keep another password database.
MIT provides no easy solution to this problem. It isn’t part of their feature set for Kerberos and probably never will be. To get around this most Kerberos admins have hand-crafted a collection of scripts or other mechanisms to keep the two password databases in synch. There is no real standard on doing this and it’s almost guaranteed that you’ll have to tweak anything you find to work for your system.
Apple has done all of this legwork for you. They built on the Password Server that made its appearance in Mac OS X Server 10.2 and integrated it with Kerberos and LDAP. An Open Directory Master will keep all of the user records in an LDAP database and keep copies of the user’s password in both the SASL Password Server and the Kerberos KDC. Changing the password with one method will change it in both databases.
When a user is created in an Open Directory system that has a KDC running they will have two authentication authorities listed with their user record. One will refer to their unique SASL Password Server ID and the other will reference their Kerberos principle. This way Open Directory knows what to do when looking for a user’s password.
On Mac OS X the KDC database is stored in /var/db/krb5kdc. This is only readable by root and contains the actual KDC database itself, some support files, and the kdc.conf file that sets up some basic configuration parameters for the KDC. The database and the config file are the same as any other MIT Kerberos system.
If your KDC is running, as it should be automatically after an Mac OS X Server install, you can see what principles are stashed away inside the database by using the kadmin command.
On a stock install you need to be root and use
kadmin.local
Once you do a bit of configuration and get the kdamind process running you can later use just
kadmin
Either way, once you get to the kadmin prompt you can use
listprincs
to see what principles your KDC knows about.
If your KDC was never created when you set up your server, this is probably because you are either not an OD (Open Directory) Master, or you don’t have working DNS. If this is the case, make sure your DNS is good and promote yourself to an OD Master. If you are already an OD Master, and you have already entered a number of users into the LDAP database you are right to not want to demote and then promote yourself to being a Master. Instead you can hand crank Kerberos from the command line.
First you need to set up some basic config files. Luckily for you there is a utility to help you with this:
sudo kerberosautoconfig -r your Kerberos realm -m your server’s DNS name -u
or in our example
sudo kerberosautoconfig -r AFP548.COM -m www.afp548.com -u
You will now have the configuration file /Library/Preferences/edu.mit.Kerberos, which we’ll talk more about later.
Next you need to set up the KDC database with
sudo kdcsetup -f Open Directory domain -a admin user -p admin password -w your Kerberos realm
Or in our example
sudo kdcsetup -f /LDAPv3/127.0.0.1/ -a mactroll -p notgoingtotellyou -w AFP548.COM
This gets the database rolling and creates a few initial principles for you. If the command balks at this, and you know you don’t have anything important in your KDC files you can blow them away and start from scratch with
sudo rm -rf /var/db/krb5kdc/*
Then run the kdcsetup command again.
Now that you have your KDC configured (configure) you need to cross your fingers and start it
sudo krb5kdc
No news is good news here.
At this point the Open Directory section of Server Admin should indicate that the KDC is running. You now need to change the password of one of your users that is set to use an advanced password. Since your KDC wasn’t running when you created any of your current users, none of them have principles in the KDC. Changing the user’s password will change that.
Double-check to make sure the user now has a Kerberos authentication authority in their user record and test out your setup by using
kinit
This will prompt you for your password. If everything is groovy, you’ll be returned to a prompt. If not you’ll get an error and perhaps asked for your password again. If that’s the case check out our troubleshooting article. Hopefully I’ll have finished it by the time you really need it!
If sucsessful you can make sure by using
klist
Which should return a host principle for your KDC server.
Congratulations, you now (know) have a working, albeit mostly useless, but working nonetheless KDC. Now continue on to the next section.
2. Keytabs
While the KDC keeps the password database, nothing else but the KDC can get into it. While this is good for security it kind of throws a wrench into getting a service fully kerberized. The AppleShare server, for example, needs to get access to the password, or key, that it shares with the KDC.
This is done through a keytab. Service keys are exported out of the KDC into a flat file that is only readable by root. This file, on both Mac OS X and other Unix systems, defaults to /etc/krb5.keytab.
When the KDC is automagically set up for you, the keytab is also created. Isn’t Apple nice? On a stock MIT Kerberos system you’d have to do this by hand.
You can see what’s listed in your keytab by either using
ktutil
and reading the keytab in and then list it, or you can do this the easy way with
sudo klist -kt
This should spit back, on a healthy system, a collection of keys. On our sample afp548.com server you would see something like this
server:~ mactroll$ sudo klist -kt Password: Keytab name: FILE:/etc/krb5.keytab KVNO Timestamp Principal ---- ----------------- -------------------------------------------------------- 4 01/03/04 00:58:41 host/server.afp548.com@AFP548.COM 4 01/03/04 00:58:41 host/server.afp548.com@AFP548.COM 4 01/03/04 00:58:41 host/server.afp548.com@AFP548.COM 4 01/03/04 00:48:22 host/barnyard.afp548.com@AFP548.COM 4 01/03/04 00:48:22 host/barnyard.afp548.com@AFP548.COM 4 01/03/04 00:48:22 host/barnyard.afp548.com@AFP548.COM 3 01/03/04 00:58:41 smtp/server.afp548.com@AFP548.COM 3 01/03/04 00:58:41 smtp/server.afp548.com@AFP548.COM 3 01/03/04 00:58:41 smtp/server.afp548.com@AFP548.COM 3 01/03/04 00:58:41 pop/server.afp548.com@AFP548.COM 3 01/03/04 00:58:41 pop/server.afp548.com@AFP548.COM 3 01/03/04 00:58:41 pop/server.afp548.com@AFP548.COM 3 01/03/04 00:58:41 imap/server.afp548.com@AFP548.COM 3 01/03/04 00:58:41 imap/server.afp548.com@AFP548.COM 3 01/03/04 00:58:41 imap/server.afp548.com@AFP548.COM 3 01/03/04 00:58:41 ftp/server.afp548.com@AFP548.COM 3 01/03/04 00:58:41 ftp/server.afp548.com@AFP548.COM 3 01/03/04 00:58:41 ftp/server.afp548.com@AFP548.COM 3 01/03/04 00:58:41 afpserver/server.afp548.com@AFP548.COM 3 01/03/04 00:58:41 afpserver/server.afp548.com@AFP548.COM 3 01/03/04 00:58:41 afpserver/server.afp548.com@AFP548.COM
It’s normal to have three of each. Each one of these is encrypted in a different way, so your services can support more password types.
If you have a list of entries in your keytab, you should be g2g as the kids say to actually use Kerberos for some hot single sign on action.
Make sure that you have done a kinit and received your host principle. Then ssh to your server’s DNS name. For example
ssh www.afp548.com
Through the magic of Kerberos you shouldn’t have to enter in your password. In fact it might be tough to see that you even made a connection at all. Check the process list and the system log to make sure you actually ssh’d to the machine that you are currently on.
If this didn’t work, and this is probably because you don’t have a large number of entries in your keytab file, you can use this utility to populate your keytab.
sudo sso_util configure -r REALM -a admin_name [-p password] service
Or in our example
sudo sso_util configure -r AFP548.COM -a mactroll -p mypass all
After this you should now have a full keytab, so try an ssh connection to yourself again.
3. Clients
An Mac OS X client needs two pieces to be in place before it will seamlessly participate in a Kerberos system.
First it needs to have the aforementioned /Library/Preferences/edu.mit.Kerberos file. This is a non-sensitive plain text file that tells the client where its KDC is. It can also hold additional Kerberos configuration options and application specific parameters. These extras usually aren’t needed, however.
In a healthy Open Directory system the client automatically gets this file when it binds to the parent LDAP server. If you look at your LDAP database you will find a Kerberos configuration in the “config” directory at the root of the database. This is an XML-formatted version of the edu.mit.Kerberos file. When the client binds to the LDAP server using Directory Access or through DHCP, this file is converted into plaintext and installed on the client.
This config file should be stuffed into the LDAP database by the kerberosautoconfig command if you are doing this by hand.
In theory you should be able to make edits to this file on the LDAP server and the client machines will use the file with your changes when they bind. Also you should be able to create a file in the same place on a non-Apple LDAP server and fool any Mac OS X clients into thinking they are dealing with a full-blown Open Directory server.
This bit is an Apple add-on to the standard MIT Kerberos setup, and a handy one at that.
The second piece that the client needs is to tell the loginwindow to begin the Kerberos process when you login. On 10.2 you had to edit /etc/authorization by hand to get the loginwindow to do this. In 10.3 it’s already been done for you. However, if you want to further secure you connection you can edit /etc/authorization to force the server to validate itself to you before you trust it enough to use the TGT it gave you. More on this in Part 4.
4. Replication
With any network service, if it is only provided by one machine you have a single point of failure. Kerberos has full support for replicating itself to a backup KDC.
On a traditional Unix system you would have to do a bit of work on your own to set this up. Host keys need to be exchanged and access control lists need to be set up so that the primary KDC will trust the secondary.
On Panther Server when you set up a second server, remember you need to have at least two unique server serial numbers to do this, you automatically get a replicant KDC on the replica server. That’s cool and all Apple. Everything is taken care of for you.
An OD to OD replication system will also allow users to change their password from the replica if the primary server is down. This is not standard MIT Kerberos behavior, but a feature that Apple implemented.
5. Kerberos Utility
In case the command line just isn’t graphical enough for you, there is a Kerberos application at /System/Library/CoreServices/Kerberos. This will allow you to get and destroy your tickets, plus see how long they have left to live. The icon in the dock showing you your TGT’s lifetime is just flat out cool.
MIT wrote this application as part of their Kerberos for Macintosh package. Apple has put it into the default Mac OS X install. It’s handy for troubleshooting, certainly, but the average user should never have to use this.
6. Ticket cache
A standard MIT Kerberos setup will cache the TGT and other tickets the client receives in a cache file on the local machine’s file system. Even though it is protected by file permissions there is still a possibility of someone compromising the system and getting to this file.
To help prevent that both Apple and Microsoft put this cache into RAM instead of on the local drive. That way there is no chance of the file hanging around after the machine reboots. It also makes it much harder for an attacker to get access to it.
7. End result
The Final result of all of this is that a user can log into an Mac OS X client machine using a username and password from the Open Directory infrastructure and never have to enter a password again.
E-mail, filesharing and other network services can all be authenticated using Kerberos behind the scenes in a very secure fashion. The users won’t understand how much science is going on deep inside the operating system to make this work, but that’s ok.
Macintosh administrators across the world can now sleep soundly at night knowing their users are blissfully using a best of breed authentication solution.