This document is not part of the official OpenLDAP Project documentation. Comments should be directed to the author, whose address appears below, and not to the Project.

How to Configure Authentication in OpenLDAP

There are several different ways to authenticate LDAP requests. Ultimately each involves proving, in some way, that the user has or knows something which is unique to a given directory object. Access control always depends on linking the user's identity to a directory object.

Anonymous Binding

The user may choose not to identify himself at all. You should decide what information in your directory is public, if any. See the documentation on Access Control Lists.

Some attributes of the root DSE must be readable by anonymous users or various tools will fail (often in strange and cryptic ways). For example, ldapsearch will fail to authenticate using SASL if the supportedSASLMethods attribute is protected against anonymous read, but will succeed if you specify a particular method (using -Y) instead of letting it negotiate. This is because ldapsearch binds anonymously to get the list of supported methods, before attempting to bind using SASL.

Basic Authentication

The user may provide a username and a password. The username is the distinguished name of some object in the directory, and the password is compared to the value of that object's userPassword property. If they match, the named object will be used to determine access to the requested object(s).

Password values may be stored as plaintext, or as one of a variety of hashes. To store a plaintext password (for example, "secret"), just use that string:
userPassword: secret

To store a hashed password, prefix the hash value with the name of the hash algorithm in braces:
userPassword: {SSHA}234234342342342

The available hashes are:

{CRYPT}
The Unix crypt() hash, based on DES. Weaker than the others.
{UNIX}
Synonym for {CRYPT}
{SHA}
SHA-1 based hash.
{SSHA}
Salted SHA-1 based hash.
{MD5}
MD5 based hash.
{SMD5}
Salted MD5 based hash.

Note: Hashing a password protects the plaintext of the password, but hashed passwords alone do not protect the identity of the directory object! The hashed value is stored as-is in the directory and is transmitted as-is across the wire. Stealing the hashed value in transit is enough to compromise access based on the directory object. Carrying the LDAP session in an SSL session encrypts everything, including the password or hash thereof, and may be satisfactory protection for use in untrusted networks. On the other hand, hashed passwords do make it less useful to steal the directory database because it is nearly impossible to recover the plaintext and use it to attack other services that might use the same one, so hashing is still a good idea.

Kerberos IV

slapd can simply hand the given password over to Kerberos IV, along with the commonName of an object, and let Kerberos test them. Unlike most Kerberos applications, the password itself is sent to the server, which then consults Kerberos to verify it. Set the object's userPassword attribute to {KERBEROS}.

You will need to create a service principal ldap.YOUR.HOST@YOUR.REALM and add it to a srvtab file to enable Kerberos support. You will need to set srvtab in slapd.conf if that srvtab is not in the default location.

SASL

The user may request authentication using the Simple Authentication and Security Layer. SASL provides a number of methods, including plaintext passwords in a separate user database, GSSAPI, and external means such as SSL client certificate presentation. GSSAPI may in turn consult a Kerberos V authentication service.

In any case, SASL authentication depends on linkage between a directory object and some object in another service.

The first step in setting up SASL authentication is to get SASL working. Cyrus SASL comes with sample client and server applications. Use them to prove to yourself that SASL is working satisfactorily. If you use the GSSAPI/Kerberos method, go ahead and set up a service principal "ldap/YOUR.LDAP.SERVER@YOUR.DOMAIN" and use that for testing. (Be sure to use kinit to get a TGT for YOUR.DOMAIN so that Kerberos can grant you a ticket for ldap!) The Cyrus SASL kit also contains a note from Ken Hornstein showing how to test the GSSAPI/Kerberos method. Other methods should be similar.

Once you have your desired methods working with the sample programs, they should work with OpenLDAP. Mechanisms requiring configuration will refer to slapd.conf in the SASL plugins directory (typically /usr/lib/sasl). This is not the same as the slapd.conf that slapd itself reads from the OpenLDAP configuration directory!

The following sections briefly describe each mechanism.

PLAIN

This is another form of password authentication. There are a variety of sub-mechanisms, for which you may need to provide configuration data. See the SASL documentation for details.

CRAM-MD5, DIGEST-MD5

The user presents a digest of his password instead of plaintext. These mechanisms require storage of the secrets in the SASL database. See the SASL documentation for details.

KERBEROS_V4

This is real Kerberos authentication: the client passes a service ticket to the server. If the correct srvtab is not where the Kerberos library expects it, you'll need to specify srvtab in slapd's configuration file.

GSSAPI (Kerberos V)

You will need to specify sasl-realm in your slapd.conf if the LDAP server host's fully-qualified domain name is not the same as the name of your realm. See also sasl-host, to change the SASL library's notion of what host it's running on, and sasl-secprops to constrain the mechanisms that SASL will accept.

EXTERNAL

This method depends on SSL to identify the user by means of an X.509 certificate. I don't know how the certificate is mapped to a DN -- if you do, please write!

Mark H. Wood, 05-Apr-2001.