Kerberos Authentication to Windows 2003

Work in progress

This site is in the process of being reviewed and updated.

Introduction

Windows clients can be configured for single sign-on (SSO) to a Kerberos realm, based on a strict interpretation of RFC 1510. The Windows releases have some known Kerberos interoperability limitations. These limitations include the following:

Only DES-CBC-MD5 and DES-CBC-CRC encryption types are available for Apache Kerberos interoperability.
Hierarchical realm support for cross-platform trust between the Windows 2003 and Apache Kerberos realms is not included; however, transitive trust is supported between Windows domains in the domain tree.

This HOWTO describes how to configure Linux, Windows 2003, and Apache Directory to allow Windows logins to use Apache Directory as the KDC.

Getting Started

(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 Windows client and the KDC.
```
$ yum install wireshark-gnome
```
Make sure you are using ApacheDS 1.5.1, which is currently (10-JUN-2007) only available from the HEAD of trunk in svn. (How to build the trunks)

Open the server.xml for editing.

$ cd <trunk>/server-main
$ vi server.xml

Enable the Kerberos protocol provider. By default, the Kerberos protocol is not enabled. Changing the Kerberos port is not recommended when working with Windows hosts.

<bean id="kdcConfiguration" class="org.apache.directory.server.kerberos.kdc.KdcConfiguration">
  <!-- Whether to enable the Kerberos protocol.                           -->
  <property name="enabled" value="true" />
  <!-- The port to run the Kerberos protocol on.                          -->
  <property name="ipPort" value="88" />
</bean>

Enable the KeyDerivationService. 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 "KeyDerivationService" interceptor. This service 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.
```
<bean class="org.apache.directory.server.core.configuration.MutableInterceptorConfiguration">
  <property name="name" value="keyDerivationService" />
  <property name="interceptor">
    <bean class="org.apache.directory.server.core.kerberos.KeyDerivationService" />
  </property>
</bean>
```
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 configure the 'ldifDirectory' in server.xml.
```
<property name="ldifDirectory">
  <value>/path/to/kerberos-host-example.ldif</value>
</property>
```

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=host	userpassword: s3crEt	krb5PrincipalName: host/www.example.com@EXAMPLE.COM	The Windows host 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 <trunk>/server-main
$ ./apacheds.sh
```
(OPTIONAL) You may need to stop the server and delete the database files as you're troubleshooting.
```
$ rm -rf example.com/
```
Perform a default Windows 2003 installation. DO NOT configure Windows 2003 to be part of a domain.
The Windows 2003 Support Tools are not automatically installed when you install Windows 2003; their installation isn't an option in the Windows 2003 setup. The installation program is located on the CD-ROM in the \support\tools folder and the setup file (suptools.msi) must be opened manually to initiate the installation wizard. After double-clicking the suptools.msi file and running the installer, you will have the ksetup command available on the Command Prompt.
Since a Kerberos realm is not a Windows 2003 domain, Windows 2003 must be configured as a member of a workgroup. This is automatic when you set the Kerberos realm and add a KDC server as follows:
```
C:> Ksetup /setdomain EXAMPLE.COM
C:> Ksetup /addkdc EXAMPLE.COM kdc.example.com
```
Ensure that 'kdc.example.com', from the 'addkdc' mapping, above, is configured to properly resolve using ping. You may add 'kdc.example.com' to DNS or the \windows\system32\drivers\etc\hosts file. In my hosts file I have:
```
127.0.0.1    localhost
192.168.0.2  kdc.example.com
```
BECAUSE KERBEROS KEYS ARE DERIVED FROM THE REALM, HOSTNAME, AND PASSWORD, YOU MUST HAVE THE REALM AND HOSTNAME SET IN WINDOWS 2003 BEFORE SETTING THE MACHINE PASSWORD OR THE KERBEROS SHARED SECRET WILL NOT MATCH THE SHARED SECRET IN THE LDAP DIRECTORY!!! Ensure the following Windows 2003 settings, ignoring the case:
```
Full computer name:  www.EXAMPLE.COM
Workgroup:           EXAMPLE.COM
```
Note the similarity between the 'Full computer name' and 'Workgroup', above, and the following attribute from the kerberos-host-example.ldif:
```
krb5PrincipalName: host/www.example.com@EXAMPLE.COM
```
Set the local machine account password to match the kerberos-host-example.ldif userpassword, as follows:
```
userpassword: s3crEt
```
```
C:> Ksetup /setmachpassword s3crEt
```
Restart your computer for the changes to take effect. Whenever changes are made to the external KDC and realm configuration, a restart is required.
Use Ksetup to configure single sign on (SSO) by mapping local Windows 2003 accounts to Kerberos principals. To keep this simple, we will map a default user from the kerberos-host-example.ldif to the Windows 2003 administrator account:
```
C:> Ksetup /mapuser hnelson@EXAMPLE.COM administrator
```
(OPTIONAL) Map clients to local accounts of the same name.
```
C:> Ksetup /mapuser * *
```

Use Ksetup with no arguments to see the current settings.

C:> Ksetup
default realm = EXAMPLE.COM (external)
EXAMPLE.COM:
     kdc = kdc.example.com
     Realm Flags = 0x0 none
Mapping hnelson@EXAMPLE.COM to administrator.

When you login (or unlock the computer), make sure that you have selected the proper domain. The domain may be hidden by the 'Options > >' button.
```
User name:  hnelson
Password:   ******
Log on to:  EXAMPLE.COM (Kerberos Realm)
```
You should now be able to login to the Windows 2003 machine using 'hnelson' and the password 's3crEt'.

Child pages

Kerberos Authentication to Windows 2003

Introduction

Getting Started