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.
- Set up DNS records. See the administration guide for this or Turbo's page.
- Execute krb5_newrealm (a debian command)
- Type in password twice -- remember it or write it somewhere secure.
- kadmin principals are automatically created.
- kerberos servers are automatically started
- Execute kadmin.local.
- listprincs shows created principals
- 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.
- 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. - 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.
- Type
kinit username
to authenticate yourself to kerberos first. - In the first one, type
./sample-server -s ldap
- In the second one, type
./sample-server -s ldap -n FDQN -u username
- 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):
Troubleshooting
Following are some of the problems I ran into and how you can avoid them based on examples from the sample session.
- lt-sample-client: Starting SASL negotiation: generic failure
After pasting the first line from the server to the client, there is a "generic failure":
service=ldap Waiting for mechanism list from server... S: TE9HSU4gUExBSU4gQU5PTllNT1VTIEdTU0FQSQ== Choosing best mechanism from: LOGIN PLAIN ANONYMOUS GSSAPI lt-sample-client: Starting SASL negotiation: generic failureThe problem here is that either the principals are missing from kerberos, or you have not yet authenticated yourself to kerberos.
- Verify that the principals exist.
Type
kadmin.local
to get back into the kerberos admin server and thelistprinc
to view the list of principals. You should see among the list the two principals "ldap/FQDN@KRB5_REALM" and "username@KRB5_REALM", where FQDN is the fully qualified domain name and KRB5_REALM is the realm you selected up when setting up kerberos.$ kadmin.local -q 'listprincs' Authenticating as principal root/admin@EVERYBODY.ORG with password. K/M@EVERYBODY.ORG kadmin/admin@EVERYBODY.ORG kadmin/changepw@EVERYBODY.ORG kadmin/history@EVERYBODY.ORG krbtgt/EVERYBODY.ORG@EVERYBODY.ORG ldap/staging.everybody.org@EVERYBODY.ORG mah@EVERYBODY.ORGUse
ank
as outlined above to add the principals if they are missing. - Verify that you are authenticated.
To verify that you are authenticated to kerberos, type
klist
. You should see something like:Ticket cache: FILE:/tmp/krb5cc_0 Default principal: mah@EVERYBODY.ORG Valid starting Expires Service principal 10/04/01 01:42:26 10/04/01 11:42:21 krbtgt/EVERYBODY.ORG@EVERYBODY.ORG Kerberos 4 ticket cache: /tmp/tkt0 klist: You have no tickets cachedIt is also possible that your ticket has expired. This happened to me when I left my session open for a day or so and then came back to it and expected it to work.
In any case, use
kinit username
to authenticate.
- Verify that the principals exist.
- lt-sample-server: Starting SASL negotiation: generic
failure (GSSAPI: gss_acquire_cred: Miscellaneous failure; No
such file or directory; )
You don't have a keytab file. Run
kadmin.local -q 'ktadd ldap/FQDN'
to create one. - lt-sample-server: Starting SASL negotiation: generic
failure (GSSAPI: gss_acquire_cred: Miscellaneous failure; No
principal in keytab matches desired name; )
You don't have the proper principal in the keytab.
Use
ktadd -k keytabfile ldap/FQDN
from within kadmin.local to add the principal to the keytab.Verify that the principal is in the keytab by using
klist -k
:Keytab name: FILE:/etc/krb5.keytab KVNO Principal ---- -------------------------------------------------------------------------- 3 ldap/staging.everybody.org@EVERYBODY.ORG 3 ldap/staging.everybody.org@EVERYBODY.ORG - lt-sample-server: Starting SASL negotiation:
authentication failure (GSSAPI: gss_accept_sec_context:
Miscellaneous failure; Key version number for principal in
key table is incorrect; )
The version of the key in your keytab file is out of sync with what is in the kerberos database or your ticket cache contains an old principal.
To fix:
- First try to reauthenticate (
kinit -R
orkinit
). If that doesn't work, continue: kadmin.local -q 'ktrem ldap/FQDN'
kadmin.local -q 'delprinc ldap/FQDN'
kadmin.local -q 'ank -randkey ldap/FQDN'
kadmin.local -q 'ktadd ldap/FQDN'
- First try to reauthenticate (