Configuring LDAP Clients to Use Security

The following sections explain how to configure
and use SSL in LDAP clients that want to establish secure connections with Directory Server.
In an SSL connection, the server sends its certificate to the client. The
client must first authenticate the server by trusting its certificate. Then,
the client can optionally initiate one of the client authentication mechanisms
by sending its own certificate or information for one of the two SASL mechanism.
The SASL mechanisms are DIGEST-MD5 and GSSAPI using Kerberos V5.

The following sections use the ldapsearch tool as
an example of an SSL-enabled LDAP client.

To configure SSL connections on other LDAP clients, refer to the documentation
provided with your application.

Note –

Some client applications implement SSL but do not verify that
the server has a trusted certificate. These client applications use the SSL
protocol to provide data encryption but cannot guarantee confidentiality nor
protect against impersonation.

The following sections explain how to configure LDAP clients to use
security:

Using SASL DIGEST-MD5 in Clients

When using the DIGEST-MD5 mechanism in clients,
you do not need to install a user certificate. However, if you want to use
encrypted SSL connections, you must still trust the server certificate as
described in Managing Certificates.

Specifying a Realm

A realm defines the namespace from which
the authentication identity is selected. In DIGEST-MD5 authentication, you
must authenticate to a specific realm.

Directory Server uses the fully qualified host name of the machine
as the default realm for DIGEST-MD5. The server uses the lowercase value of
the host name that is found in the nsslapd-localhost configuration
attribute.

If you do not specify a realm, the default realm offered by the server
is used.

Specifying Environment Variables

In the UNIX environment, you must set the SASL-PATH environment
variable so that the LDAP tools can find the DIGEST-MD5 libraries. The DIGEST-MD5
library is a shared library that is dynamically loaded by the SASL plug-in.
Set the SASL_PATH environment variable as follows:

export SASL_PATH=SASL-library

This path assumes that Directory Server is installed on the same
host where the LDAP tools are invoked.

Examples of the ldapsearch Command

You can perform DIGEST-MD5 client authentication without using SSL.
The following example uses the default DIGEST-MD5 identity mapping to determine
the bind DN:

The preceding example shows the use of the -o (lowercase
letter o) option to specify SASL options. The realm is
optional, but if specified, it must be the fully qualified domain name of
the server host machine. The authid and authzid must
both be present and identical, although the authzid intended
for proxy operations is not used. The -w password option
applies to the authid.

The value of authid is the Principal used in identity
mapping. The authid should contain either the dn: prefix
followed by a valid user DN in the directory, or the u: prefix
followed by any string determined by the client. This use of authid allows
you to use the mappings that are shown in DIGEST-MD5 Identity Mappings.

The most common configuration is for an SSL connection to provide encryption
over the LDAPS secure port and DIGEST-MD5 to provide the client authentication.
The following example performs the same operation over SSL:

In this example, the -N and -w options
are required by the ldapsearch command, as the operation
is performed over SSL. However , these options are not used for client authentication.
Instead, the server performs another DIGEST-MD5 identity mapping of the Principal
in the authid value.

Using Kerberos SASL GSSAPI in Clients

When using the GSSAPI mechanism in clients, you do not need to
install a user certificate, but you must configure the Kerberos V5 security
system. Also, if you want to use encrypted SSL connections, you must trust
the server certificate as described in Managing Certificates.

To Configure Kerberos V5 on a Host

You must configure Kerberos V5 on the host machine where your LDAP clients
will run.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Using the Sun Enterprise
Authentication Mechanism software, configure the files under /etc/krb5.
This configuration sets up the kdc server, and defines
the default realm and any other configuration required by your Kerberos system.

If necessary, modify the file /etc/gss/mech
so that the first value that is listed is kerberos_v5 .

To Specify SASL Options for Kerberos Authentication

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Before using a client application that is enabled with the GSSAPI
mechanism, initialize the Kerberos security system with your user Principal.

$ kinit user-principal

where the user-principal is your SASL identity,
for example, bjensen@example.com.

Specify SASL options for using Kerberos.

Note that
in the UNIX environment, you must set the SASL_PATH environment
variable to the correct path for the SASL libraries. For example in the Korn
shell:

$ export SASL_PATH=SASL-library

This path assumes that Directory Server is installed on the same
host where the LDAP tools are invoked.

The following example of the ldapsearch tool shows
the use of the -o (lowercase letter o) option to specify
SASL options for using Kerberos:

The authid can be omitted because it is present in
the Kerberos cache that was initialized by the kinit command.
If authid is present, authid and authzid must be identical, although the authzid intended
for proxy operations is not used. The value of authid is
the Principal that is used in identity mapping. The Principal must be the
full Principal, including the realm. See GSSAPI Identity Mappings.

Example Configuration of Kerberos Authentication
Using GSSAPI With SASL

Configuring Kerberos for Directory Server can be complicated. Your
first point of reference should be the Kerberos documentation.

For more help, use the following example procedure to get an idea of
which steps to follow. Be aware, however, that this procedure is an example.
You must modify the procedure to suit your own configuration and your own
environment.

Additional information about configuring and using Kerberos in the Solaris
OS can be found in System Administration Guide: Security Services.
This guide is a part of the Solaris documentation set. You can also consult
the man pages.

Assumptions for This Example

This example procedure describes the process of configuring one machine
to operate as a Key Distribution Center (KDC), and a second machine to run
a Directory Server. The result of this procedure is that users can perform
Kerberos authentication through GSSAPI.

It is possible to run both the KDC and the Directory Server on the
same machine. If you choose to run both on the same machine, use the same
procedure, but omit the steps for the Directory Server machine that have
already been done for the KDC machine.

This procedure makes a number of assumptions about the environment that
is used. When using the example procedure, modify the values accordingly to
suit your environment. These assumptions are:

This system has a fresh installation of the Solaris 9 software
with the latest recommended patch cluster installed. Kerberos authentication
to the Directory Server can fail if the appropriate Solaris patches are
not installed.

Note that although the documented procedure is
largely the same for Solaris 10, there are some differences. The configuration
file format is slightly different, and the output of some of the commands
might not be the same.

The machine that is running the Kerberos daemons has the fully
qualified domain name of kdc.example.com. The machine must
be configured to use DNS as a naming service. This configuration is a requirement
of Kerberos. Certain operations might fail if other naming services such as file are used instead.

The machine that is running Directory Server has the fully
qualified domain name of directory.example.com. This machine
must also be configured to use DNS as a naming service.

The Directory Server machine serves as the client system
for authenticating to the Directory Server through Kerberos. This authentication
can be performed from any system that can communicate with both the Directory Server and
Kerberos daemons. However, all of the necessary components for this example
are provided with the Directory Server, and the authentication is performed
from that system.

Users in the Directory Server have DNs of the form uid=username,ou=People,dc=example,dc=com. The corresponding
Kerberos principal is username@EXAMPLE.COM.
If a different naming scheme is used, a different GSSAPI identity mapping
must be used.

All Machines: Edit the Kerberos Client Configuration
File

The /etc/krb5/krb5.conf configuration file provides
information that Kerberos clients require in order to communicate with the
KDC.

Edit the /etc/krb5/krb5.conf configuration file on
the KDC machine, the Directory Server machine, and any client machines
that will authenticate to the Directory Server using Kerberos.

Replace every occurrence of "___default_realm___" with
"EXAMPLE.COM".

Replace every occurrence of "___master_kdc___" with
"kdc.example.com".

Remove the line that contains "___slave_kdcs___" as
there will be only a single Kerberos server.

Replace "___domain_mapping___" with ".example.com
= EXAMPLE.COM" (note the initial period in .example.com).

The updated /etc/krb5/krb5.conf configuration file
should look like the contents of the following example.

Use the following sequence of commands to add host Principals to the
Kerberos database for the KDC and Directory Server machines. The host Principal
is used by certain Kerberos utilities such as klist.

KDC Machine: Add an LDAP Principal for the Directory
Server

For the Directory Server to be able to validate the Kerberos tickets
that are held by authenticating users, the Directory Server must have its
own Principal. Currently, the Directory Server is hard coded to require
a Principal of ldap/fqdn@realm where fqdn is the fully-qualified domain name of the Directory Server and realm is the Kerberos realm. The fqdn must
match the fully qualified name provided when installing the Directory Server.
In this case, the Principal for the Directory Server would be ldap/directory.example.com@EXAMPLE.COM.

Use the following sequence of commands to create an LDAP Principal for
the Directory Server:

KDC Machine: Add a Test User to the KDC

To perform Kerberos authentication, the user authenticating must exist
in the Kerberos database. In this example, the user has the user name kerberos-test, which means that the Kerberos Principal is kerberos-test@EXAMPLE.COM.

First, create the file /data/ds/shared/bin/gssapi.ldif to
define the mapping that should be used by the Directory Server, and to
identify which Kerberos user is authenticating, based on the Principal. Create
the file contents to be the same as what is shown in the following example.

Directory Server Machine: Create a Directory Server Keytab

As mentioned previously, to authenticate Kerberos users through GSSAPI,
the Directory Server must have its own Principal in the KDC. For authentication
to work properly, the Principal information must reside in a Kerberos keytab
on the Directory Server machine. This information must be in a file that
is readable by the user account under which the Directory Server operates.

Create a keytab file with the correct properties by using the following
command sequence:

By default, the Directory Server tries to use the standard Kerberos
keytab in the file /etc/kerb5/krb5.keytab. However, making
this file readable by the Directory Server user could constitute a security
risk, which is why a custom keytab was created for the Directory Server.

Configure the Directory Server to use the new custom keytab. Do this
by setting the KRB5_KTNAME environment variable.

Finally, restart the Directory Server to allow these changes to take
effect:

$ KRB5_KTNAME=/etc/krb5/ldap.keytab dsadm restart /local/ds

Directory Server Machine: Add a Test User to the Directory Server

To authenticate a Kerberos user to the Directory Server, there must
be a directory entry for the user that corresponds to the Kerberos Principal
for that user.

In a previous step, a test user was added to the Kerberos database with
a Principal of kerberos-test@EXAMPLE.COM. Because of the
identity mapping configuration added to the directory, the corresponding directory
entry for that user must have a DN of uid=kerberos-test,ou=People,dc=example,dc=com.

Before you can add the user to the directory, you must create the file testuser.ldif with the following contents.

Client Machine: Authenticate to the Directory Server Through
GSSAPI

The final step is to authenticate to the Directory Server by using
GSSAPI. The ldapsearch utility provided with the Directory Server provides
support for SASL authentication, including GSSAPI, DIGEST-MD5, and EXTERNAL
mechanisms. However, to bind by using GSSAPI you must provide the client with
the path to the SASL library. Provide the path by setting the SASL_PATH environment
variable to the lib/sasl directory:

$ SASL_PATH=SASL-library
$ export SASL_PATH
$

To actually perform a Kerberos-based authentication to the Directory Server using ldapsearch, you must include the -o mech=GSSAPI and
-o authzid=principal arguments.

You must also specify the fully qualified host name, shown here as -h directory.example.com, which must match the value of the nsslapd-localhost attribute on cn=config for the server. This
use of the -h option is needed because the GSSAPI authentication
process requires the host name provided by the client to match the host name
provided by the server.

The following example retrieves the dc=example,dc=com entry
while authenticated as the Kerberos test user account created previously:

This example shows that the bind is a three-step process. The first
two steps return LDAP result 14 (SASL bind in progress),
and the third step shows that the bind was successful. The method=sasl and mech=GSSAPI tags show that the bind used the GSSAPI SASL mechanism.
The dn="uid=kerberos-test,ou=people,dc=example,dc=com"
at the end of the successful bind response shows that the bind was performed
as the appropriate user.