Kerberos Authentication to SSHD

ApacheDS 1.5.5

This site was updated for ApacheDS 1.5.5.

Introduction

Modern OpenSSH provides support for GSSAPI (Generic Security Services Application Programming Interface) which allows for the use of Kerberos V5 with SSH2 protocols. Users can use Kerberos tickets instead of passwords to SSH to a properly configured SSHD service. The "three-headed" Kerberos setup tested was (1) openssh-clients (2) openssh-server (3) and Apache Directory.

Getting Started

Verify name resolution. Underlying libraries used by SSH will automatically determine your host name. For this reason the hostname you wish to use should be the top-most entry in your hosts file or matching A and PTR records in DNS. Overloading an IP address with multiple hostnames is common in developer workstations, so checking that the host you wish to use is first in the list to resolve will save you a lot of time later! You will likely find a sniffer (like WireShark) very handy for figuring out what hostnames are being assumed and whether DNS is working properly. Since SSH is always used to access a host in order to configure some other service, in this lesson we use the hostname 'www.example.com' for the host we are configuring SSHD on. A typical scenario is SSH'ing into a web server to configure Apache HTTPD or Apache Tomcat.
```
$ more /etc/hosts
# Do not remove the following line, or various programs
# that require network functionality will fail.
127.0.0.1       localhost.localdomain   localhost
10.0.0.2        www.example.com
10.0.0.2        www.apache.org
10.0.0.2        kdc.example.com
```
(OPTIONAL) Configure Wireshark. You may also find it useful to have Wireshark (formerly Ethereal) on hand. You can filter on 'kerberos' to listen to traffic between the SSH client and the KDC.
```
$ yum install wireshark-gnome
```
Configure your host so that it knows where to get Kerberos tickets. On linux this is configured in '/etc/krb5.conf'. The minimum config file must list the default Kerberos realm and the location of at least one key distribution center (KDC). With ApacheDS acting as a KDC and running on our localhost, we can use 'localhost' as the KDC.
```
[libdefaults]
 default_realm = EXAMPLE.COM

[realms]
 EXAMPLE.COM = {
  kdc = kdc.example.com
 }

[domain_realm]
 .example.com = EXAMPLE.COM
 example.com = EXAMPLE.COM
```
Make sure you are using ApacheDS 1.5.5.
Open the server.xml for editing and enable the KDC server and key derivation interceptor as described here: Kerberos in ApacheDS 1.5.5

You may change the Kerberos port so that Kerberos can bind if you're logged-in as a non-root user. If you change the default port of '88', you must change the KDC port in the krb5.conf, as well.

Kerberos authentication is based on symmetric keys. Since a user can't be expected to remember a symmetric key, there are "key derivation functions" that will produce symmetric key material based on the concatenation of the password, realm, and username. Any changes to the user's password must result in new keys being generated. Luckily, ApacheDS has the "KeyDerivation" interceptor. This interceptor will intercept any adds or modifications to the user's 'userPassword' attribute and generate keys. Service principals typically use random keys, so the interceptor will generate random keys when the special keyword 'randomKey' is used.

Pre-load principals using an LDIF file. With the KeyDerivationService enabled, you should be able to use LDIFs or LDAP to configure principals on-the-fly. For this example, since the LDIF format is concise, we review some LDIF entries. You will find attached to this page an example LDIF. Download the LDIF and import it into the LDAP server.

Review the LDIF entries. The metaphor for Kerberos comes from the fact that it is "three-headed"; there is always a KDC principal, service principal, and user principal. All of these principals use the same objectClass'es. The attributes are the minimum to satisfy their respective schema, with the exception of the Kerberos schema. Because we are using the KeyDerivationService, we don't need to specify the Kerberos key, key types, or key version number (kvno); they are automatically added by the interceptor, which will also increment the kvno when the password changes. Looking at the LDIF file you'll see the ASL license, an organizational unit (ou) for our 'users' subcontext, and the following entries:

Entry RDN	Password	Principal Name	Description
uid=hnelson	userpassword: s3crEt	krb5PrincipalName: hnelson@EXAMPLE.COM	Our user principal. Note the user password.
uid=krbtgt	userpassword: randomKey	krb5PrincipalName: krbtgt/EXAMPLE.COM@EXAMPLE.COM	The KDC principal, with a random key.
uid=hostssh	userpassword: s3crEt	krb5PrincipalName: host/www.example.com@EXAMPLE.COM	The SSHD principal. Note the service password.

(OPTIONAL) Increase logging in server-main/log4j.properties
```
log4j.logger.org.apache.directory.kerberos=DEBUG
```
You are now ready to start the server. Upon startup, the server will load the entries from the LDIF.
```
$ cd apacheds_1.5.5
$ ./apacheds.sh
```
(OPTIONAL) You may need to stop the server and delete the database files as you're troubleshooting.
```
$ rm -rf example.com/
```
(OPTIONAL) Make a keytab for the SSHD service principal. In order for an SSHD server to "run as" a given service principal, we must provision (export) a symmetric key for it to use. While a user principal typically uses a password, a service principal typically uses a random key. This random key is generated by the server and then exported for use by the service. This key is exported into a keytab file. Our SSHD service will automatically look for this keytab file based on the hostname. Because key export for ApacheDS is currently under heavy development, we won't export keys for this example. Instead, we'll take advantage of the fact that key derivation algorithms are standardized and we'll create a keytab based on the SSHD service principal from the LDIF we imported. We stated, above, that service keys are typically random. For this example, we have set the SSHD service to use a password, "s3crEt." By fixing the password like this, we can use Kerberos tools to make a keytab. When prompted, the password for the service is "s3crEt" (without the quotes).
```
$ ktutil
ktutil:  addent -password -p host/www.example.com@EXAMPLE.COM -k 1 -e des-cbc-md5
Password for host/www.example.com@EXAMPLE.COM:  s3crEt
ktutil:  list
slot KVNO Principal
---- ---- ---------------------------------------------------------------------
   1    1 host/www.example.com@EXAMPLE.COM
ktutil:  wkt /etc/krb5.keytab
ktutil:  quit
```

(OPTIONAL) Sanity check: verify the presence of the server key in the keytab file.

$ klist -5ke /etc/krb5.keytab
Keytab name: FILE:/etc/krb5.keytab
KVNO Principal
---- --------------------------------------------------------------------------
   1 host/www.example.com@EXAMPLE.COM (DES cbc mode with RSA-MD5)

(OPTIONAL) Test the krb5.keytab. Instead of entering a password with 'kinit', you can also use a keytab file. The following code shows how to "log in" (acquire a TGT) using a keytab file.

$ kinit -k -t /etc/krb5.keytab host/www.example.com@EXAMPLE.COM

If 'kinit' returns with no message, it worked. Now, when you look in your ticket cache, you'll see default principal is set to the SSHD principal, who now has a TGT.

$ klist -5fea
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: host/www.example.com@EXAMPLE.COM

Valid starting     Expires            Service principal
02/18/07 20:01:36  02/19/07 20:01:36  krbtgt/EXAMPLE.COM@EXAMPLE.COM
        Etype (skey, tkt): DES cbc mode with RSA-MD5, DES cbc mode with RSA-MD5 
        Addresses: (none)

(OPTIONAL) Destroy the SSHD service's credentials. Your default principal is now set to the SSHD key you just tested, so you need to destroy it.
```
$ kdestroy
$ klist -5fea
klist: No credentials cache found (ticket cache FILE:/tmp/krb5cc_0)
```

Request a ticket-granting ticket (TGT) using 'kinit'. If you have not already "logged in," you must request a fresh TGT. Without a TGT your attempt to login to the host will fall-back to require a password. Also, if you don't specify the user principal, kinit will guess the principal name based on the logged-in user and the realm configured in the krb5.conf.

$ kinit hnelson@EXAMPLE.COM
Password for hnelson@EXAMPLE.COM:  s3crEt
$ klist -5fea
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: hnelson@EXAMPLE.COM

Valid starting     Expires            Service principal
02/18/07 20:02:23  02/19/07 20:02:22  krbtgt/EXAMPLE.COM@EXAMPLE.COM
        Etype (skey, tkt): DES cbc mode with RSA-MD5, DES cbc mode with RSA-MD5 
        Addresses: (none)

Configure local user accounts. Users still need local accounts on each machine. Kerberos only abstracts the location of the password, moving it from the shadow password file to one or more Kerberos servers. To indicate that Linux is looking to Kerberos for a password, the password in /etc/shadow should be set to '*K*' like this:
```
hnelson:*K*:12308:-1:99999:-1:::
```
Usernames can't have a period in them, like 'horatio.nelson'.

On the server, you need to edit sshd_config and comment out all of the Kerberos* options and enable some GSSAPI options. For added security, you may wish to disable regular password-based authentication.

# To disable tunneled clear text passwords, change to no here!
#PasswordAuthentication yes
PasswordAuthentication no

# Kerberos options
#KerberosAuthentication no
#KerberosOrLocalPasswd yes
#KerberosTicketCleanup yes
#KerberosGetAFSToken no

# GSSAPI options
#GSSAPIAuthentication no
GSSAPIAuthentication yes
#GSSAPICleanupCredentials yes
GSSAPICleanupCredentials yes

You should leave the Kerberos options commented out. Enable the GSSAPIAuthentication and GSSAPICleanupCredentials options. Restart sshd once the file is saved.

(OPTIONAL) Start a one-time instance of SSHD to aid in troubleshooting. The first command runs a one-time instance of the SSH daemon on a new port with triple-verbose logging enabled. The second command starts a client to connect to said daemon.
```
$ sshd -p 2222 -d -d -d
$ ssh -p 2222 -v -v -v [username]@[server]
```
Configure SSH clients. You can configure ssh per-user with ~/.ssh/options or you can modify the system-wide /etc/ssh/ssh_config file. Either way, the options you want to enable are:
```
Host *
GSSAPIAuthentication yes
GSSAPIDelegateCredentials yes
```
"GSSAPIAuthentication yes" tells the client to allow GSSAPI user authentication. By default this is set to "no."
"GSSAPIDelegateCredentials yes" will forward your Kerberos credentials to the server. By default this is "no." After ssh'ing to a host, if you do a 'klist' you'll see your TGT available for subsequent operations.
Test SSH access. Once both the server and client allow GSSAPI authentication, you can now ssh to your server using your Kerberos credentials. However, if for some reason you cannot authenticate to the KDC (i.e. it is down), you will be locked out unless you permit password (keyboard-based) authentication or public key authentication. Password-based authentication is not recommended; you should rely strictly on public key and GSSAPI authentication, or public key authentication alone. This especially makes sense for servers that are directly on the Internet (colo, Xen vhost, dedicated, etc.) Your SSHD will get scanned regularly with brute force attacks!

(OPTIONAL) List your Kerberos credentials. You'll see that in addition to a TGT, you also now have a service ticket for the SSHD server.

$ klist -5fea
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: hnelson@EXAMPLE.COM

Valid starting     Expires            Service principal
02/18/07 20:02:23  02/19/07 20:02:22  krbtgt/EXAMPLE.COM@EXAMPLE.COM
        Etype (skey, tkt): DES cbc mode with RSA-MD5, DES cbc mode with RSA-MD5 
        Addresses: (none)
02/18/07 20:06:31  02/19/07 20:02:22  host/www.example.com@EXAMPLE.COM
        Etype (skey, tkt): DES cbc mode with RSA-MD5, DES cbc mode with RSA-MD5 
        Addresses: (none)

Child pages

Kerberos Authentication to SSHD

Introduction

Getting Started