LDAP Authentication

First, install OpenLDAP:

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

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

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 25), 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.

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:

% 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:

% 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, OpenSSL Certificates for LDAP 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                 *:*

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

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.

PAM, which stands for “Pluggable Authentication Modules”, is the method by which FreeBSD authenticates most of its sessions. To tell FreeBSD we wish to use an LDAP server, we will have to add a line to the appropriate PAM file.

Most of the time the appropriate PAM file is /etc/pam.d/sshd, if you want to use SSH (remember to set the relevant options in /etc/ssh/sshd_config, otherwise SSH will not use PAM).

To use PAM for authentication, add the line

auth  sufficient  /usr/local/lib/pam_ldap.so  no_warn

Exactly where this line shows up in the file and which options appear in the fourth column determine the exact behavior of the authentication mechanism; see pam.d(5)

With this configuration you should be able to authenticate a user against an LDAP directory. PAM will perform a bind with your credentials, and if successful will tell SSH to allow access.

However it is not a good idea to allow every user in the directory into every client machine. With the current configuration, all that a user needs to log into a machine is an LDAP entry. Fortunately there are a few ways to restrict user access.

ldap.conf supports a pam_groupdn directive; every account that connects to this machine needs to be a member of the group specified here. For example, if you have

pam_groupdn cn=servername,ou=accessgroups,dc=example,dc=org

in ldap.conf, then only members of that group will be able to log in. There are a few things to bear in mind, however.

Members of this group are specified in one or more memberUid attributes, and each attribute must have the full distinguished name of the member. So memberUid: someuser will not work; it must be:

memberUid: uid=someuser,ou=people,dc=example,dc=org

Additionally, this directive is not checked in PAM during authentication, it is checked during account management, so you will need a second line in your PAM files under account. This will require, in turn, every user to be listed in the group, which is not necessarily what we want. To avoid blocking users that are not in LDAP, you should enable the ignore_unknown_user attribute. Finally, you should set the ignore_authinfo_unavail option so that you are not locked out of every computer when the LDAP server is unavailable.

Your pam.d/sshd might then end up looking like this:

auth            required        pam_nologin.so          no_warn
auth            sufficient      pam_opie.so             no_warn no_fake_prompts
auth            requisite       pam_opieaccess.so       no_warn allow_local
auth            sufficient      /usr/local/lib/pam_ldap.so      no_warn
auth            required        pam_unix.so             no_warn try_first_pass

account         required        pam_login_access.so
account         required        /usr/local/lib/pam_ldap.so      no_warn ignore_authinfo_unavail ignore_unknown_user

Say you want your IT department to be able to change home directories for users, but you do not want all of them to be able to add or remove users. The way to do this is to add a group for these admins:

dn: cn=homemanagement,dc=example,dc=org
objectClass: top
objectClass: posixGroup
cn: homemanagement
gidNumber: 121 # required for posixGroup
memberUid: uid=tuser,ou=people,dc=example,dc=org
memberUid: uid=user2,ou=people,dc=example,dc=org

And then change the permissions attributes in slapd.conf:

access to dn.subtree="ou=people,dc=example,dc=org"
  attr=homeDirectory
  by dn="cn=homemanagement,dc=example,dc=org"
  dnattr=memberUid write

Now tuser and user2 can change other users' home directories.

In this example we have given a subset of administrative power to certain users without giving them power in other domains. The idea is that soon no single user account has the power of a root account, but every power root had is had by at least one user. The root account then becomes unnecessary and can be removed.