LDAP Authentication
Prev |  | Next

# 2 Configuring LDAP

LDAP stands for Lightweight Directory Access Protocol and is a subset of the X.500 Directory Access Protocol. Its most recent specifications are in RFC4510 and friends. Essentially it is a database that expects to be read from more often than it is written to.

The LDAP server OpenLDAP will be used in the examples in this document; while the principles here should be generally applicable to many different servers, most of the concrete administration is OpenLDAP-specific. There are several server versions in ports, for example `net/openldap24-server`. Client servers will need the corresponding `net/openldap24-client` libraries.

There are (basically) two areas of the LDAP service which need configuration. The first is setting up a server to receive connections properly, and the second is adding entries to the server's directory so that FreeBSD tools know how to interact with it.

## 2.1 Setting Up the Server for Connections

> Note: This section is specific to OpenLDAP. If you are using another server, you will need to consult that server's documentation.

### 2.1.1 Installing OpenLDAP

First, install OpenLDAP:

Example 1. Installing OpenLDAP

    # cd /usr/ports/net/openldap24-server
    # make install clean

This installs the `slapd` and `slurpd` binaries, along with the required OpenLDAP libraries.

### 2.1.2 Configuring OpenLDAP

Next we must configure OpenLDAP.

You will want to require encryption in your connections to the LDAP server; otherwise your users' passwords will be transferred in plain text, which is considered insecure. The tools we will be using support two very similar kinds of encryption, SSL and TLS.

TLS stands for Transportation Layer Security. Services that employ TLS tend to connect on the same ports as the same services without TLS; thus an SMTP server which supports TLS will listen for connections on port 25, and an LDAP server will listen on 389.

SSL stands for Secure Sockets Layer, and services that implement SSL do not listen on the same ports as their non-SSL counterparts. Thus SMTPS listens on port 465 (not 45), HTTPS listens on 443, and LDAPS on 636.

The reason SSL uses a different port than TLS is because a TLS connection begins as plain text, and switches to encrypted traffic after the `STARTTLS` directive. SSL connections are encrypted from the beginning. Other than that there are no substantial differences between the two.

> Note: We will adjust OpenLDAP to use TLS, as SSL is considered deprecated.

Once OpenLDAP is installed via ports, the following configuration parameters in `/usr/local/etc/openldap/slapd.conf` will enable TLS:

    security ssf=128

    TLSCertificateFile /path/to/your/cert.crt
    TLSCertificateKeyFile /path/to/your/cert.key
    TLSCACertificateFile /path/to/your/cacert.crt

Here, `ssf=128` tells OpenLDAP to require 128-bit encryption for all connections, both search and update. This parameter may be configured based on the security needs of your site, but rarely you need to weaken it, as most LDAP client libraries support strong encryption.

The `cert.crt`, `cert.key`, and `cacert.crt` files are necessary for clients to authenticate you as the valid LDAP server. If you simply want a server that runs, you can create a self-signed certificate with OpenSSL:

Example 2. Generating an RSA key

    % openssl genrsa -out cert.key 1024
    Generating RSA private key, 1024 bit long modulus
    ....................++++++
    ...++++++
    e is 65537 (0x10001)
    % openssl req -new -key cert.key -out cert.csr

At this point you should be prompted for some values. You may enter whatever values you like; however, it is important the Common Name value be the fully qualified domain name of the OpenLDAP server. In our case, and the examples here, the server is `server.example.org`. Incorrectly setting this value will cause clients to fail when making connections. This can the cause of great frustration, so ensure that you follow these steps closely.

Finally, the certificate signing request needs to be signed:

Example 3. Self-signing the certificate

    % openssl x509 -req -in cert.csr -days 365 -signkey cert.key -out cert.crt
    Signature ok
    subject=/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd
    Getting Private key

This will create a self-signed certificate that can be used for the directives in `slapd.conf`, where `cert.crt` and `cacert.crt` are the same file. If you are going to use many OpenLDAP servers (for replication via `slurpd`) you will want to see Appendix B to generate a CA key and use it to sign individual server certificates.

Once this is done, put the following in `/etc/rc.conf`:

    slapd_enable="YES"

Then run `/usr/local/etc/rc.d/slapd start`. This should start OpenLDAP. Confirm that it is listening on 389 with

    % sockstat -4 -p 389
    ldap     slapd      3261  7  tcp4   *:389                 *:*

### 2.1.3 Configuring the Client

Install the `net/openldap24-client` port for the OpenLDAP libraries. The client machines will always have OpenLDAP libraries since that is all `security/pam_ldap` and `net/nss_ldap` support, at least for the moment.

The configuration file for the OpenLDAP libraries is `/usr/local/etc/openldap/ldap.conf`. Edit this file to contain the following values:

    base dc=example,dc=org
    uri ldap://server.example.org/
    ssl start_tls
    tls_cacert /path/to/your/cacert.crt

> Note: It is important that your clients have access to `cacert.crt`, otherwise they will not be able to connect.

> Note: There are two files called `ldap.conf`. The first is this file, which is for the OpenLDAP libraries and defines how to talk to the server. The second is `/usr/local/etc/ldap.conf`, and is for pam_ldap.

At this point you should be able to run `ldapsearch -Z` on the client machine; `-Z` means use TLS. If you encounter an error, then something is configured wrong; most likely it is your certificates. Use openssl(1)'s `s_client` and `s_server` to ensure you have them configured and signed properly.

## 2.2 Entries in the Database

Authentication against an LDAP directory is generally accomplished by attempting to bind to the directory as the connecting user. This is done by establishing a simple bind on the directory with the user name supplied. If there is an entry with the `uid` equal to the user name and that entry's `userPassword` attribute matches the password supplied, then the bind is successful.

The first thing we have to do is figure out is where in the directory our users will live.

The base entry for our database is `dc=example,dc=org`. The default location for users that most clients seem to expect is something like `ou=people,`base``, so that is what will be used here. However keep in mind that this is configurable.

So the ldif entry for the `people` organizational unit will look like:

    dn: ou=people,dc=example,dc=org
    objectClass: top
    objectClass: organizationalUnit
    ou: people

All users will be created as subentries of this organizational unit.

Some thought might be given to the object class your users will belong to. Most tools by default will use `people`, which is fine if you simply want to provide entries against which to authenticate. However, if you are going to store user information in the LDAP database as well, you will probably want to use `inetOrgPerson`, which has many useful attributes. In either case, the relevant schemas need to be loaded in `slapd.conf`.

For this example we will use the `person` object class. If you are using `inetOrgPerson`, the steps are basically identical, except that the `sn` attribute is required.

To add a user `testuser`, the ldif would be:

    dn: uid=tuser,ou=people,dc=example,dc=org
    objectClass: person
    objectClass: posixAccount
    objectClass: shadowAccount
    objectClass: top
    uidNumber: 10000
    gidNumber: 10000
    homeDirectory: /home/tuser
    loginShell: /bin/csh
    uid: tuser
    cn: tuser

I start my LDAP users' UIDs at 10000 to avoid collisions with system accounts; you can configure whatever number you wish here, as long as it's less than 65536.

We also need group entries. They are as configurable as user entries, but we will use the defaults below:

    dn: ou=groups,dc=example,dc=org
    objectClass: top
    objectClass: organizationalUnit
    ou: groups

    dn: cn=tuser,ou=groups,dc=example,dc=org
    objectClass: posixGroup
    objectClass: top
    gidNumber: 10000
    cn: tuser

To enter these into your database, you can use `slapadd` or `ldapadd` on a file containing these entries. Alternatively, you can use `sysutils/ldapvi`.

The `ldapsearch` utility on the client machine should now return these entries. If it does, your database is properly configured to be used as an LDAP authentication server.

Prev | Home | Next
LDAP Authentication |  | Client Configuration