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.
This section is specific to OpenLDAP. If you are using another server, you will need to consult that server's documentation.
First, install OpenLDAP:
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 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.
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:
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 keyThis 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
:
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:
It is important that your clients have access to
cacert.crt
, otherwise they will not be
able to connect.
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.
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,
, so
that is what will be used here. However keep in mind that this is
configurable.base
So the ldif entry for the people
organizational unit will look like:
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:
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:
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.
This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/
For questions about FreeBSD, read the
documentation before
contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.