This is a draft

This is draft documentation for Kerberos principal configuration.

ApacheDS Kerberos principal configuration

Introduction

Apache Directory currently supports the Kerberos protocol for network authentication.

Getting Started

  1. Make sure you are using ApacheDS 1.5.1. (How to build the trunks)
  2. Open the server.xml for editing. 
    $ cd <trunk>/server-main
$ vi server.xml
  3. 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). 
    [libdefaults]
 default_realm = EXAMPLE.COM

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

[domain_realm]
 .example.com = EXAMPLE.COM
 example.com = EXAMPLE.COM
  4. Enable the Kerberos protocol provider. By default, the LDAP protocol is enabled, but the Kerberos protocol is not. You may also 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. 
    <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>
  5. 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>
  6. 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-example.ldif</value>
</property>
  7. 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.

  8. 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
  9. Request a ticket-granting ticket (TGT) using 'kinit'. If you have not already "logged in," you must request a fresh TGT. Without a TGT, 'ldapsearch', for example, will fail with error "No credentials cache found." 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>
  10. List your Kerberos credentials. You will see a TGT. 
    $ klist -5fea
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: hnelson@EXAMPLE.COM
Valid starting     Expires            Service principal
06/04/07 20:42:19  06/05/07 20:41:37  krbtgt/EXAMPLE.COM@EXAMPLE.COM
        Etype (skey, tkt): DES cbc mode with RSA-MD5, DES cbc mode with RSA-MD5
        Addresses: (none)
  • No labels