Using LDAP Client Software With the Oak LDAP Service

2.1. Ensure Oak LDAP's SSL Certificates Will be Trusted

As discussed above, one CA root must be trusted. The exact details of configuration will vary according to OS, LDAP libraries and clients, but one common case is a single file containing the CA roots (it could include more; this is the minimum requirement). In Debian, for example, the ca-certificates package manages the file /etc/ssl/certs/ca-certificates.crt which may be used for this purpose. The directory /etc/ssl/certs may also be configured as a CA directory for some applications.

Any application using the OpenLDAP libldap libraries for making LDAP connections (examples of this include PHP ldap support, the OpenLDAP command line tools (ldapsearch, ldapcompare, etc), and mod_webauthldap) require the following to exist in an ldaprc; commonly, a system-wide file exists; for example on Debian this is /etc/ldap/ldap.conf. This file should contain the following:

TLS_CACERT <path to CA certificates file>

2.2. Install Packages to Enable SASL GSSAPI

You will also need to have the SASL libraries installed, and in particular the SASL GSSAPI module. In Debian this is provided by libsasl2-modules-gssapi-mit.

2.3. Fetch Kerberos Keys Into Keytab Files

When you registered for the service, you requested access for specific principal(s). You can fetch newly generated keys for these principals using the kadmin utility or equivalent (unfortunately, there is no way to fetch a key over the kadmin protocol without triggering generation of a new key, so be careful if this principal is already in use elsewhere). An example session:

$ kadmin -p USER/itss@OX.AC.UK
kadmin: ktadd -k /PATH/TO/KEYTAB host/example.ox.ac.uk@OX.AC.UK
Entry for principal oak-ldap/example.ox.ac.uk with kvno 3, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/PATH/TO/KEYTAB.
Entry for principal oak-ldap/example.ox.ac.uk with kvno 3, encryption type DES cbc mode with CRC-32 added to keytab WRFILE:/PATH/TO/KEYTAB.

You can then check it has created something useful with:

$ klist -e -k /PATH/TO/KEYTAB

2.4. Make the Kerberos credentials cache available to the client

For the MIT or Heimdal Kerberos implementations, the KRB5CCNAME environment variable controls where the application looks for the credentials cache. If you're using Apache, you can use the SetEnv directive from mod_env. Alternatively, use the way of setting this environment variable provided by the runtime system or programming language you're using.

The credentials cache has a short lifetime (order of hours), so to keep it fresh you will need to periodically update it with new tickets fetched using the key in your keytab. The user updating the credentials cache based on the keytab will require read access to the keytab, and write access to the credentials cache. The credentials cache will then need to be readable by the user running the LDAP client, for example the web server.

One utility designed to assist with this is k5start, available in Debian in the package kstart. An example invocation is:

k5start -v -f /PATH/TO/KEYTAB -k /PATH/TO/CCACHE YOURPRINCNAME@OX.AC.UK

You should arrange for k5start to run as a continually-running process (daemon) on the system.

Another way to keep a fresh credentials cache derived from a keytab is by periodically running kinit.