Integrating LDAP and Kerberos: Part Two (LDAP)

In the first installment we covered setting up Kerberos. Now it’s time to set up LDAP and ensure that it works happily ever after with Kerberos.

OpenSSL

OpenSSL enables you to run a secure LDAP server (over ldaps:/// on port 636). The relevant Debian packages are libssl-dev, openssl, ca-certificates, and libssl0.9.8.

To generate a self-signed certificate:

1. First generate a certificate authority:

cd /etc/ssl
/usr/lib/ssl/misc/CA.sh -newca

The CN asked for here must be the FQDN of the LDAP server. Do not use the “challenge password” attribute, but do set the PEM passphrase (and remember it!).

2. Create the certificate:
   openssl req -new -x509 -nodes -out newreq.pem -keyout newreq.pem -days 365

   The -nodes switch is important in order to create an unencrypted certificate, so that it will work with LDAP. Again, when asked for the CN, it needs to be the FQDN (fully qualified domain name) of your server, e.g. ldapserver.example.com.

3. Sign the certificate:
   /usr/lib/ssl/misc/CA.sh -signcert

   Again, do not use a challenge password. The new certificate will be in newcert.pem. (Note: this script looks for the file newreq.pem and signs that; if you have used another file in the certificate creation you will need to rename or copy it.)

If you want Verisign or another Certificate Authority to sign your certificate, the process is easier — you only need step 2, and should leave out the -x509 switch. Check the instructions from your CA as to what you should do with the certificate request.

Once LDAP is installed, you will move the certificate files to the LDAP directory as explained below.

LDAP server setup

The Debian packages you need are libldap2, slapd, ldap-utils, libdb3-dev, and libdb3 (these last two provide the BerkeleyDB database backend). Set the admin password when asked during dpkg-configure.

To use SASL correctly, you need to put the certificates generated above in the correct places:

    mv /etc/ssl/newcert.pem /etc/ldap/servercrt.pem
    mv /etc/ssl/newreq.pem /etc/ldap/serverkey.pem
    mv /etc/ssl/demoCA/cacert.pem /etc/ldap/cacert.pem
    chmod go-r /etc/ldap/serverkey.pem
    chown openldap /etc/ldap/serverkey.pem
    chmod a+r /etc/ldap/servercrt.pem

Edit /etc/default/slapd to include these lines:

        SLAPD_SERVICES="ldaps:///"
        SLAPD_OPTIONS="4"

LDAP configuration

To use LDAP with Kerberos, you need to get a copy of krb5-kdc.schema and put it in /etc/ldap/schema/.

Edit /etc/ldap/slapd.conf:

include         /etc/ldap/schema/krb5-kdc.schema
include         /etc/ldap/schema/openldap.schema

# ... other things that can stay as provided ...

TLSCACertificateFile    /etc/ldap/cacert.pem
TLSCertificateFile      /etc/ldap/servercrt.pem
TLSCertificateKeyFile   /etc/ldap/serverkey.pem

# ... other things that can stay as provided ...

# this section rewrites principals as needed for Kerberos authentication
authz-policy from
authz-regexp
     uid=(.*),cn=example.com,cn=GSSAPI,cn=auth
     uid=$1,ou=people,dc=example,dc=com
sasl-realm      EXAMPLE.COM
sasl-host       ldapserver.example.com

include         /etc/ldap/slapd.access

# ... rest of file ...

Edit /etc/ldap/slapd.access to set your permissions. I’ve provided a basic example; you can complicate it about as much as you want!

# Everyone can read everything
access to dn.base="" by * read

# The admin dn has full write access
access to *
        by dn="uid=ldapadm,ou=people,dc=example,dc=com" write
        by * read

# Temporary lines to allow initial setup
rootdn "cn=admin,dc=example,dc=com"
rootpw secret

Note that you must not have comment lines between the ‘access’ and ‘by’ lines in this file, or it won’t work.

The ACLs should also go before the database backend definitions (so they apply globally) — this means that the include slapd.access line in /etc/ldap/slapd.conf must occur before the database backend definitions.

Put this line in /etc/ldap/ldap.conf:

TLS_REQCERT      allow

This allows clients to request the TLS server certificate from the server, thus saving you having to copy it everywhere.

If you need it, there is more config information for TLS/SSL in the OpenLDAP FAQ.

To separate out the slapd logs from the general systems logging, edit /etc/syslog.conf and add the following line:

local4.* /var/log/slapd.log

LDAP and Kerberos

Add the LDAP server to kerberos, by running kadmin -p krbadm from the LDAP host, and executing these commands:

addprinc -randkey ldap/server.example.com
ktadd -k /etc/ldap/ldap.keytab ldap/server.example.com

You should extract the server key to a keytab other than the system one at /etc/krb5.keytab (this is what the -k flag does), since the LDAP keytab must be owned by the LDAP user. Change the file ownership appropriately.

You also need to ensure that slapd is looking at this keytab. Add the following line to /etc/default/slapd:

export KRB5_KTNAME=/etc/ldap/ldap.keytab

Now, restart slapd.

If there are problems with startup, change the log level in /etc/ldap/slapd.conf to 16383 to get verbose logging in the log file. Change it back before you go into production, as verbose logging makes the server very slow.

Setting up the database

To set up the database, you first use the authentication in the rootdn and rootpw directives, to add the root entry, the People group, and an admin user (e.g. ldapadm — you should have added this user when you set up Kerberos).

For this you need to create a “setup” LDIF file (setup.ldif). You need to choose your base domain, which will depend on your organization. It’s a good idea to use a base domain that is related to your Kerberos domain and also to your IP domain. Here we use dc=example,dc=com.

# setup.ldif
dn: dc=example,dc=com
objectclass: organization
objectclass: dcObject
objectclass: top
o: Example Company
dc: example
description: root entry

dn: ou=people,dc=example,dc=com
objectclass: organizationalUnit
ou: people
description: Users

dn: uid=ldapadm,ou=people,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: shadowAccount
cn: LDAP admin account
uid: ldapadm
uidNumber: 1002
gidNumber: 100
homeDirectory: /etc/ldap
loginShell: /bin/false

Note that the LDAP user cannot log in directly.

To add this, use ldapadd:

ldapadd -x -D "cn=admin,dc=ph,dc=ic,dc=ac,dc=uk" -W -f setup.ldif

-W is the option which causes the password to be demanded, -x uses an anonymous bind.

After this, edit /etc/ldap/slapd.conf again to remove the rootdn and rootpw entries. From now on you can authenticate as the ldapadm user to add or modify entries. Restart slapd.

Testing!

Before you fully populate the database, it’s time to check that it works. Try the below, first from the server. Once that’s working, set up a client (see below) and try it from there.

• ldapsearch -x -H ldaps://server.example.com (The -x option gives a simple bind.)
• ldapsearch -x -H ldaps://server.example.com -ZZ -TLS (This test TLS startup.)
• kinit username; ldapsearch -H ldaps://server.example.com (This to test kerberos auth.)

Troubleshooting notes:

• Add -d 16383 to the ldapsearch line to enable copious debugging output.

• Check the permissions on /etc/ldap/cacert.pem — it needs to be world-readable.

• Check /etc/hosts if the hostname is resolving incorrectly (this will show up in the debugging output — your client needs to be trying server.example.com, not just server).

• If you get the error “Key version for principal in keytable is incorrect”, there is a mismatch between the kerberos keytab and the master server. On the LDAP host, run kadmin -p krbadm and execute the following:

  ktrem ldap/server.example.com
  delprinc ldap/server.example.com
  addprinc -randkey ldap/server.example.com
  ktadd ldap/server.example.com
  

• If you get the error “GSSAPI Error: Miscellaneous failure (Permission denied)”, check that the LDAP keytab is readable by the ldap user, and that slapd is looking at the correct keytab. You can test this quickly by also adding ldap/server.example.com to the system keytab at /etc/krb5.keytab and making that world-readable. If that starts things working then your keytab may be the problem. Remember to change it back to root-only afterwards!

• Note that having high levels of debugging will slow things down dramatically — turn debugging off or down once things are working. If you are not getting errors, but ldapsearch appears to be hanging, try reducing the log levels in /etc/ldap/slapd.conf and restarting slapd.

Populating the LDAP database

You have many options to populate the database. If you already have users, you’ll want to migrate your data — PADL provide tools (the migrationtools package on Debian). This works fine for regular Unix setup (/etc/passwd, /etc/shadow, /etc/groups), and also for NIS. With some adjustment it will also work for NIS+.

You will, however, need to migrate your passwords to Kerberos by hand. This may be a good time to make everyone change their passwords.

To import an existing database: stop slapd, run slapadd -l existing_database.ldif, and restart slapd (where existing_database.ldif is an LDIF dump of an existing database).

You may need to empty the database first: do this by stopping slapd and removing the contents of the database directory — this is specified in /etc/ldap/slapd.conf by the directory directive.

Remove the rootdn and rootpw entries from slapd.conf, then start and stop slapd again before importing the database. If you have startup problems, check that the database directory is owned by the LDAP user (openldap on Debian).

Finally, you need to make sure that you have no password references in your user database — Kerberos will be handling passwords for you, and the easiest way to make this happen is simply to remove all password references from LDAP.

Run kinit ldapadm, and then use ldapsearch to get the attributes for any user: for example, to search for a user named “jkemp” you’d use ldapsearch ("uid=jkemp"). Look for any password attributes. Then for any individual user, you can create the following ldapmodify file:

dn: cn=username,ou=People,dc=example,dc=com
changetype: modify
delete: userPassword

Replace userPassword as appropriate. Then run ldapmodify -f modifyfile. You can put multiple users in the same file: use the same syntax as above, but separate each instance with a blank line.

Alternatively you can of course edit any data migration tool so as not to take the password data.

Client setup

You’ll need the following packages: ldap_utils, libnss-ldap, autofs-ldap (if you use automount), and nscd.

After installing the packages, edit /etc/nsswitch.conf as follows:

passwd:     compat files ldap
shadow:     compat files ldap
group:      compat files ldap

hosts:      files dns

services:   db files ldap [NOTFOUND=return]
networks:   db files ldap [NOTFOUND=return]
protocols:  db files ldap [NOTFOUND=return]
rpc:        db files ldap [NOTFOUND=return]
ethers:     db files ldap [NOTFOUND=return]

automount:  files

It’s important that compat and files entries appear before ldap for passwd, shadow, and group — otherwise if your LDAP server fails (or the client connection to it does) you won’t be able to log in at all. You can use ldap for hosts as well if you prefer.

Edit /etc/libnss-ldap.conf so that the only lines uncommented are:

base dc=example,dc=com
uri ldaps://ldapserver.example.com
ldap_version 3

Edit /etc/ldap/ldap.conf as follows — some of these may be auto-filled from installation questions.

BASE    dc=example,dc=com
URI     ldaps://ldapserver.example.com
TLS_REQCERT allow

The last line enables the client to request the server’s certificate, and saves you installing it on every client.

To set up automount to read from LDAP, you need the autofs-ldap package. Note that you want to use files in /etc/nsswitch.conf (as above) rather than ldap — this seems more reliable. Edit /etc/auto.master as follows:

/home   ldap:nisMapName=auto_home,dc=example,dc=com

Customize as appropriate for your setup. Here the dn uses nisMapName, which is for automounts which were converted from NIS+. You can also use automountMapName.

To test your setup, try the following on the client:

ldapsearch -d 1 -x

You should see the TLS info at the top and bottom of the debug output (generated with the -d 1 flag). If you have any problems, try specifying the server with -H ldaps://ldapserver.example.com — if this works, check the values in /etc/ldap/ldap.conf.

Finally, test that Kerberos auth is working by typing kinit, then ldapsearch (i.e. without the -x simple bind option).

Now you’re there!

Using LDAP

The basic LDAP commands are ldapadd, ldapmodify, and ldapdelete. Execute kinit ldapadm before any of these, to authenticate yourself.

• ldapadd:

  • ldapadd -f newuser.ldif

  • newuser.ldif could look like this:

    dn: uid=username,ou=People,dc=example,dc=com
    uid: username
    objectClass: account
    objectClass: posixAccount
    objectClass: top
    objectClass: shadowAccount
    loginShell: /bin/tcsh
    uidNumber: userid
    gidNumber: groupid
    homeDirectory: /home/username
    gecos: Real Name
    cn: Real Name
    
    dn: cn=username,nisMapName=auto_home,dc=example,dc=com
    objectClass: nisObject
    cn: username
    nisMapEntry: server:/export/home/username
    nisMapName: auto_home
    

    This would create both a user entry, and an entry for the autofs map to set up their home directory. Note the blank line between the two entries.

• ldapsearch:
  • ldapsearch "(uid=username)"
• ldapmodify (again you need to authenticate first):
  • ldapmodify < modify_file

  • Example of modify_file:

    dn: uid=jkemp,ou=People,dc=example,dc=com
    changetype: modify
    replace: loginShell
    loginShell: /bin/bash
    

    This would change the user’s login shell to /bin/bash.

  • Another example, which adds a field:

    dn: uid=jkemp,ou=People,dc=example,dc=com
    changetype: add
    add: emailAddress
    emailAddress: [email protected]
    

• ldapdelete:

  • Run ldapdelete "cn=isis,ou=Hosts,dc=example,dc=com" — you need to specify the DN of the entity you wish to delete.

  • You can also use ldapdelete -f file, where file contains a list of DNs, one per line, all of which will be deleted in turn.

Your site should now be happily Kerberized and LDAP-ized. You can set up various other applications to use LDAP as a directory server (e.g. mail clients, to get an address book) and Kerberos for authentication (e.g. your Web server).