In the Cyrus-Sasl distribution, Ken Hornstein has offered a good start at directions on how to get started with GSSAPI authentication using SASL.

Although a lot of good information is there, it wasn't explicit enough for me. Evidently, he didn't anticipate that some of us dolts would try this without having already been Kerberos administrators for a while.

This document is an attempt to hold the hand of an administrator who hasn't had experience with either Kerberos or SASL, but knows that he wants to use both for authentication through the GSSAPI authentication protocol under SASL. Much of it repeats other documentation that you should have already read but skipped because you wanted to get this done now. Go read that documentation now.

More information and more hand-holding can be found in Turbo Fredriksson's wonderful HOWTO on the subject.

Like him, I'm using Debian Linux. However, the testing distribution seems to have some features that were lacking in the distribution that Turbo was using.

Base Configuration

If you want to get going quickly using Debian, just run through this configuration document.

Kerberos Setup

This is the part a lot of you are probably missing. I know I was.

  1. Set up DNS records. See the administration guide for this or Turbo's page.
  2. Execute krb5_newrealm (a debian command)
    1. Type in password twice -- remember it or write it somewhere secure.
    2. kadmin principals are automatically created.
    3. kerberos servers are automatically started
  3. Execute kadmin.local.
    1. listprincs shows created principals
    2. ank -randkey ldap/your fully qualified domain name

      We need these keys for SASL authentication. We'll also use them in the next step when we test SASL auth.

    3. ktadd ldap/FQDN

      This command puts the key in the /etc/krb5.keytab file so that your servers can use it to authenticate themselves. "FQDN" is the host's fully qualified domain name. "ldap" must match the service name that you wish to use kerberos authentication.

      Usually, you won't have keytab files on the same machine as the kerberos server, so you have to use the command ktadd -k filename principal and then securely copy the file from filename to whichever host has runs the service.

    4. ank username

      You need a username to authenticate.

Running the Sample SASL Server

You'll have to compile this yourself. If you are inexperienced with sasl or kerberos or both, I really recommend you go through this as it will help you diagnose where your problem is.

The testing process is simple but cumbersome. Open two windows and get ready to cut-n-paste between them.

  1. Type kinit username to authenticate yourself to kerberos first.
  2. In the first one, type ./sample-server -s ldap
  3. In the second one, type ./sample-server -s ldap -n FDQN -u username
  4. Cut the line that starts "S: " from the server window and paste them to the client window. Cut any responses starting with a "C: " from the client window and paste them to the server window. Repeat. A lot.

A sample session with pasted data bold (and elided):

$ ./sample-server -s ldap Generating client mechanism list... Sending list of 4 mechanism(s) S: TE9HSU4gUExBSU4gQU5PTllNT1VTIEdTU0FQSQ== Waiting for client mechanism... C: R1NTQVBJA ... got 'GSSAPI' Sending response... S: YIGMB ... Waiting for client reply... C: got '' Sending response... S: YD8G ... Waiting for client reply... C: YD8G got '....' Negotiation complete Username: mah lt-sample-server: realm: can't request info until later in exchange SSF: 56

Troubleshooting

Following are some of the problems I ran into and how you can avoid them based on examples from the sample session.