Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Tue, 11 Mar 2008 21:46:06 GMT

Initial conversion from Docbook

New page

{{Linux in a Windows World/TOC}}
The Lightweight Directory Access Protocol is the second of three cross-platform authentication tools described in this book. In reality, though, LDAP is much more than an authentication tool; it's a protocol for accessing ''directories'' , which in this context are essentially databases designed to be read more often than they're written. As such, LDAP can store many different types of information—Unix or Windows account databases, mappings of hostnames to IP addresses, employee contact information, and so on. This chapter focuses on one narrow use for LDAP, as a network-accessible account authentication system. LDAP makes a viable alternative to NT or Active Directory domains for network authentication of both Windows and Linux servers and desktop systems. It can provide better Linux account database integration, so it's the smarter choice if you use many Linux systems. It can also provide much more than account authentication information, although such configurations are beyond the scope of this book. Using Linux as an LDAP platform gives you all of Linux's usual advantages, such as its reliability and low cost.

When setting up an LDAP authentication system, you should first understand some LDAP basics. Despite the word ''lightweight'' in the protocol's name, LDAP is a complex system, with its own terminology and peculiarities. In fact, several LDAP implementations exist, so you must pick one and install it on your Linux LDAP server. You must then set up your directories to handle authentication. Only then can you begin configuring your LDAP clients to use your network's account directory. (Note that LDAP clients can be servers for other protocols.) Of course, the details of this configuration vary between Linux and Windows clients, so you must know how to handle both.

<div class="tip">
'''Tip'''

You can use a non-Linux LDAP server for authentication. In fact, if you currently use a Windows 200x Active Directory domain controller, it already runs LDAP. You can use this server to authenticate users on Linux systems, but you need to add Unix-style account information to the LDAP directories. Alternatively, you can configure the Linux systems to access the Windows server as an NT domain controller, as described in [[Linux in a Windows World/Centralized Authentication Tools/Using NT Domains for Linux Authentication|Chapter 7]]. This solution requires no changes on the Windows LDAP server and so is likely to be slightly simpler to configure.
</div>

== The Principles Behind LDAP ==

At its core, LDAP is a protocol for exchanging data between computers. The LDAP protocol has been independently implemented in several packages, but understanding what problems LDAP is intended to solve will help you understand its features and implementations. As a practical matter, you must also pick an LDAP implementation to run on your LDAP server, as well as LDAP clients for systems that should authenticate against the server.

=== The Problem: Providing a Network-Accessible Directory ===

Directories, and LDAP in particular, are tools for storing data. At this level of analysis, directories are similar to databases. In order to understand directories, though, you should understand a couple of key differences between directories and databases:

* Directories are designed to be read more often than they're written; databases are designed for more equal distribution of read and write accesses. This characteristic simplifies many aspects of a directory's design and can lead to faster lookups in directories.
* The internal structure of databases is designed to support easy sorting and cross-referencing, but the entries are otherwise unstructured. Directories, by contrast, use a hierarchical structure but are less easily sorted than database entries.

LDAP provides tools that enable accessing directories across a network, with the goal of centralizing this information. The central directory can host a variety of information. For instance, it might hold individuals' computer account information, telephone numbers, office numbers, birth dates, departmental affiliations, and so on. This information is unlikely to change frequently, and individuals throughout an organization may have need to access it. Thus, a network-accessible directory protocol is the ideal way to store such information.

<div class="tip">
'''Tip'''

LDAP, and directories more generally, can handle more than just account or even personal information. For instance, you might store computer help documentation in a directory. This chapter focuses on LDAP as a tool for storing computer account information. For more information on LDAP, including additional potential uses, consult a book on the subject, such as ''LDAP System Administration'' (O'Reilly).
</div>

One important characteristic of LDAP is that it's a protocol description. The actual data storage can be in any of several different forms, depending on the features of the LDAP server you choose. For instance, an LDAP server might use plain-text files, a proprietary binary format, or a well-documented database file format. The choice of backend data file format doesn't affect the operations that can be performed by clients, but it may influence the server's overall performance level.

=== LDAP Terminology and Features ===

LDAP documentation is filled with its own jargon. Some LDAP terms should be familiar to most Linux administrators, but some of it is unique or used oddly:

;Directory
: This term, as already described, refers to a data-storage system. Note that the term is unrelated to a filesystem directory, although the two types of directories do have certain common features, such as being methods of data storage. A ''directory tree'' refers to the entire collection of structured entries in the directory.
;Attributes
: An LDAP ''attribute'' is similar to a variable in a programming language; it's a named identifier for data stored in the directory. Attributes, though, can sometimes hold multiple values.
;Object class
: Every entry in a directory is a member of an ''object class'', which defines a collection of attributes for data. You set the object class by setting the <tt>objectClass</tt> attribute to a particular value. For instance, when using LDAP to handle accounts, you'll use the <tt>posixAccount</tt> class, among others. This class defines attributes called <tt>uid</tt>, <tt>userPassword</tt>, and so on, to store account information.
;Schema
: This is a way to define several object classes at once. LDAP implementations ship with standardized schema files that provide many predefined object classes, including some that are useful for handling user accounts. (The schema is a structure for holding data, not the data itself.)
;DC
: A ''domain component'' identifies the scope of an entry or of an entire tree. Typically, you'll set <tt>dc=</tt> attributes that correspond to your DNS domain or subdomain name.
;DN
: A ''distinguished name'' is the name of an attribute along with a description of where the entry belongs in the directory tree. It's described in more detail later in this chapter.
;OU
: An ''organizational unit'' is a common subdivision in a directory. It's often used to separate departments from one another within a single organization, enabling (for instance) duplication of usernames in two different departments.
;LDIF
: The LDAP Data Interchange Format describes information in a way that LDAP can understand. It's covered in more detail later in this chapter.

LDAP directories are often represented in graphical form, such as that shown in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-FIG-1|Figure 8-1]]. In practice, these trees are constructed through the data you place in individual entries, which appear at the nodes in the tree. The topmost entry in the tree (<tt>dc=pangaea,dc=edu</tt> in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-FIG-1|Figure 8-1]]), or its root, defines the naming context of the directory. In this example, the naming context includes two DCs, which together are equivalent to the ''pangaea.edu'' DNS domain.

<div id="linuxwinworld-CHP-8-FIG-1">
'''Figure 8-1. LDAP enables you to define a hierarchical tree of entries'''

[[Image:Linux in a Windows World_I_2_tt94.png|LDAP enables you to define a hierarchical tree of entries]]
</div>

=== LDAP Software ===

Of course, you need actual software to implement an LDAP server. In Linux, the most popular LDAP package is OpenLDAP, which is headquartered at ''http://www.openldap.org''. Other LDAP packages are available, though, and some are popular on non-Linux systems. The most notable of these is probably Microsoft's Active Directory, which incorporates LDAP and Kerberos functionality. Other products include Sun's SunOne and Novell's eDirectory.

Because OpenLDAP is the most common LDAP package for Linux, the rest of this chapter uses it as an example, at least for server operations. In particular, this chapter describes OpenLDAP 2.2. LDAP client configuration should be the same even if you use another LDAP server, though. Many details differ for other LDAP servers, so if you choose to use one, you'll have to consult its documentation to learn how it differs from OpenLDAP.

== Configuring an OpenLDAP Server ==

The first step in using LDAP as a distributed login database is to get the server software running. This process entails obtaining and installing the software, setting it up to handle your domain, setting encryption options, and running the server. The [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#Creating a User Directory|Section 8.3]] will show you how to create a directory that contains all your site's user accounts.

=== Obtaining and Installing OpenLDAP ===

OpenLDAP's official home page is ''http://www.openldap.org''. You can obtain the OpenLDAP source code from this site, but the OpenLDAP site doesn't host any precompiled binaries. Fortunately, most major Linux distributions provide such binaries, usually under the name ''openldap'' or ''openldap2'' (the current OpenLDAP major version number is 2, hence that digit at the end of some OpenLDAP package names). Because most Linux distributions ship with OpenLDAP packages, the assumption in this chapter is that you're installing the server in this way. If you compile the server from source code, you may need to adjust some filesystem directory paths in the coming descriptions because OpenLDAP installs in ''/usr/local'' by default, compared to ''/usr'' for most precompiled Linux OpenLDAP binaries.

Whether you install a binary package or compile OpenLDAP from source code, you may need to install several dependencies. These programs are either required for proper OpenLDAP functioning or are optional tools that OpenLDAP can use to provide improved security or other features:

;SSL and TLS
: The Secure Sockets Layer and Transport Layer Security are cryptography tools. They're used to encrypt connections between two computers on a network—a useful feature for a network authentication system. In Linux, OpenSSL (''http://www.openssl.org'') is the most common implementation of both protocols.
;SASL
: The Simple Authentication and Security Layer is a tool for mediating between applications and authentication systems. It's optional if you compile OpenLDAP from source code, but your distribution's binary packages may require it. The main reasons to include it are if you want to enable Kerberos authentication with OpenLDAP or if you want to use other SASL-enabled applications, such as SASL-enabled SMTP or IMAP mail servers. Check ''http://asg.web.cmu.edu/sasl/'' for more information on SASL.
;Kerberos
: This tool, described in more detail in [[Linux in a Windows World/Centralized Authentication Tools/Kerberos Configuration and Use|Chapter 9]], is an encryption and remote login tool. It's possible to integrate Kerberos with LDAP authentication (in fact, that's what Microsoft's AD does), but such integration isn't necessary. However, binary OpenLDAP distributions may require that you install a Kerberos package as a dependency.
;Database backends
: LDAP is primarily a tool for computer-to-computer communication. To do any good, though, LDAP requires data to be stored on the server, and OpenLDAP relies on a ''database backend'' to do this job. Several database backends are supported, but the most common is the Berkeley DB package (''http://www.sleepycat.com''). Most Linux distributions provide this software in a package called ''db''.

In addition to these packages, binary distributions are likely to have more mundane dependencies, such as a requirement that ''glibc'' be installed. If you're using a tool such as the Advanced Package Tool's (APT's) ''apt-get'' (used mainly with Debian but also available for many RPM-based distributions) or Gentoo's ''emerge'', dependencies should be installed automatically when you install OpenLDAP. If you use a lower-level tool such as ''rpm'' or ''dpkg'', however, you may see errors about missing dependencies. To correct them, you need to locate and install the dependencies.

The OpenLDAP package contains several programs. Only one is the actual server program; others are support tools of various types, including:

;''slapd''
: This program is the main LDAP server.
;''slurpd''
: This server, which helps synchronize LDAP directories on multiple computers, is an advanced LDAP feature that's beyond the scope of this book.
;''ldapadd''
: This program adds entries to an LDAP directory. Normally, you pass it an LDIF file containing one or more account entries, as described in the later [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#Creating the Directory|Section 8.3.3]].
;''ldapmodify''
: This program modifies entries in an LDAP directory.
;''ldapdelete''
: This program deletes entries from an LDAP directory.
;''ldapsearch''
: This program searches an LDAP directory for entries that match criteria you specify.
;''ldapcompare''
: This program compares entries in an LDAP directory using criteria you specify.
;''ldappasswd''
: This program changes the password attribute in an LDAP entry. It's similar to the standard Linux ''passwd'' command.
;''ldapwhoami''
: This program reports your identity as passed to the LDAP server. It can be a useful diagnostic tool when you can't seem to obtain the results you expect.
;''slapadd''
: This local program adds entries to an LDAP directory, using an LDIF original file as input.
;''slapcat''
: This local program displays entries in an LDAP directory, displaying them as LDIF files.
;''slapindex''
: This local program creates an LDIF index file from the current LDAP directory.
;''slappasswd''
: This utility generates a password suitable for inclusion in an LDIF file and subsequent addition to an LDAP directory via ''slapadd''.

You needn't be too concerned about the details of how these programs work just yet. The upcoming pages describe how to use some of them to help create and maintain your OpenLDAP server and an account directory for it. For more information, consult these programs' manpages. One point to note, though, is that the utilities whose names begin with ''slap'' operate on the directory that's housed on the local computer; that is, they must be run from the OpenLDAP server computer. The programs whose names begin with ''ldap'', by contrast, are network tools; you can run them on the OpenLDAP server or any of its clients, provided they've been properly configured to refer to the LDAP server.

=== Basic OpenLDAP Configuration ===

OpenLDAP's main server configuration file is ''slapd.conf'' . It usually resides in ''/etc/openldap'', but it might appear in another location, particularly if you compile from source.

<div class="tip">
'''Tip'''

LDAP client tools, including programs like ''ldapmodify'' and ''ldapsearch'', use the ''ldap.conf'' file rather than ''slapd.conf''. This file is described in more detail in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#Account Maintenance|Section 8.3.4]].
</div>

The ''slapd.conf'' file is a typical Linux text-mode configuration file. Hash marks (<tt>#</tt>) denote comments; lines beginning with this character are ignored. Parameters are identified by name with one or more values following them; equal signs are not used. One unusual feature of the ''slapd.conf'' format is that a line that begins with a space is interpreted as a continuation of the preceding line. This convention is used instead of the more common backslash (<tt>\</tt>) at the end of the first line to denote a line continuation.

The ''slapd.conf'' file begins with a series of lines that specify the server's overall performance—what schemas it uses, where it stores its PID number, and so on. Following this global configuration are one or more sections, each beginning with the keyword <tt>database</tt>, that define directories. Each <tt>database</tt> section continues until the next <tt>database</tt> section or until the end of the file. These sections include options that specify the backend database type (the <tt>database</tt> directive itself does this, in fact), where the database is to be stored, the root of the directory tree, and so on.

Consider [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]]. This listing is a complete (if simple) ''slapd.conf'' file that's suitable for handling an LDAP server that functions solely as a remote authentication system.

<div id="linuxwinworld-CHP-8-EX-1">
'''Example 8-1. A Sample slapd.conf file'''

####
# Global section

# Load schemas for storing user accounts
include /etc/openldap/schema/core.schema
include /etc/openldap/schema/cosine.schema
include /etc/openldap/schema/nis.schema

# Logging options
loglevel 296
pidfile /var/run/slapd/slapd.pid
argsfile /var/run/slapd/slapd.args

# TLS options
TLSCipherSuite HIGH
TLSCertificateFile /etc/openldap/ssl/slapd-cert.crt
TLSCertificateKeyFile /etc/openldap/ssl/slapd-key.pem

# Set high security
security ssf=128

# Miscellaneous security options
password-hash {SSHA}

# Default access level
defaultaccess search

####
# Database section

database bdb

# The root suffix for the directory
suffix "dc=pangaea,dc=edu"

# The root DN for administration
rootdn "cn=Manager,dc=pangaea,dc=edu"

# The password used for administrative access
rootpw {SSHA}vHVUhjRetxArbQCTPOhyXC1a0s9z3Ej1

# Linux directory housing database files
directory /var/lib/ldap/

# Ensure that files may be read ONLY by their owner
mode 0600

## ACLs to control access to the directory

# Allow users to authenticate against and modify their own
# passwords
access to attrs=userPassword
by self write
by * auth

# Allow users to read all non-password data
access to *
by * read
</div>

Of course, [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]] is only a starting point; you'll need to customize several of its entries for your system. The meanings of these options are:

;Loading schemas
: The first few lines of [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]] load three schema files: ''core.schema'', ''cosine.schema'', and ''nis.schema''. The last of these is the critical one, but it depends on the first two. The ''nis.schema'' schema provides a framework for handling all the data an NIS server normally manages. Because this includes Unix-style account information, it's a common choice for implementing an authentication server. These schema files ship with OpenLDAP, but their location may not be as shown in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]] on your system; adjust the directory paths as required.
;Logging options
: The <tt>loglevel</tt> line sets logging options. These are set using bit flags converted to decimal notation. A value of <tt>296</tt> is reasonable for most production systems. This value logs information on connection statistics, filter processing, and connection management. (Consult the ''slapd.conf'' manpage for details.) The <tt>pidfile</tt> and <tt>argsfile</tt> options specify files in which ''slapd'' stores its PID and the arguments with which it was run. If your OpenLDAP binary includes a sample configuration file that sets these values in a particular way, you should probably leave them as such; it's possible that your SysV startup scripts or other tools rely on this location.
;TLS options
: The next three options set TLS features; the assumption in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]] is that the server will use TLS or SSL encryption, which is a reasonable configuration in most cases. (If you want to use another encryption system, you'll have to consult OpenLDAP's documentation.) As with other Linux directory paths, you may need to adjust the path shown in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]] for your system. Preparing the TLS certificates is described in the next section.
;Security level
: The <tt>security</tt> keyword sets security options. [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]] sets <tt>security</tt> <tt>ssf=128</tt>, which sets the server's overall security strength factor (SSF) to 128—a code that stands for a class of encryption algorithms that includes Blowfish, RC4, and others that are fairly strong. If you must use less robust encryption algorithms, you can change <tt>128</tt> to <tt>112</tt> or <tt>56</tt>. A value of <tt>0</tt> disables the encryption requirement.
;Password hashing
: The <tt>password-hash</tt> option specifies how OpenLDAP hashes passwords it stores. <tt>{SSHA}</tt> means that OpenLDAP uses the Salted Secure Hash Algorithm (SSHA), which is the preferred means of storing passwords on an LDAP server. Other possible values include <tt>{CRYPT}</tt> (the method used by the system <tt>crypt( )</tt> call), <tt>{MD5}</tt> (the Message Digest 5 system, which is often used in ''/etc/passwd'' or ''/etc/shadow'' files), <tt>{SHA}</tt> (a less-secure variant of SSHA), and <tt>{CLEARTEXT}</tt> (no encryption). Of these, <tt>{CLEARTEXT}</tt> is the least secure and should be avoided. Note that individual users' passwords may be stored using any method; the <tt>password-hash</tt> option only sets the default.
;The database definition
: The <tt>database</tt> <tt>bdb</tt> line begins the one and only database definition in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]]. This line tells OpenLDAP to use the Berkeley DB (hence, <tt>bdb</tt>) system for its backend. Other possible backend codes are <tt>ldbm</tt> (an older variant of <tt>bdb</tt> that can be handled by the BerkeleyDB software or the GNU Database Manager), <tt>passwd</tt> (a quick-and-dirty interface to your existing ''/etc/passwd'' file), and <tt>shell</tt> (an interface to other database tools).
;The root suffix
: The <tt>suffix</tt> line specifies the DN for the directory. In most cases, this root suffix is built from your network's domain name. In the case of [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]], OpenLDAP is configured to manage passwords for the ''pangaea.edu'' domain.
;The administrative DN
: You can specify a root DN for administration with the <tt>rootdn</tt> parameter. This DN is built from the root suffix's DN by adding a <tt>cn</tt> value, typically <tt>Manager</tt> (as in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]]) or <tt>admin</tt>. This line and the following <tt>rootpw</tt> entry are useful mainly for initial OpenLDAP configuration; once the system is working, you may want to remove them to improve the server's security.
;The administrative password
: The <tt>rootpw</tt> line sets an administrative password that's associated with the <tt>rootdn</tt> item. You can generate a password with the ''slappasswd'' command; type it and enter a password twice, then paste it into the file in place of the password shown in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]]. The password you generate should begin with <tt>{SSHA}</tt> (or possibly some other value in curly braces); replace everything from <tt>{SSHA}</tt> on with the output of ''slappasswd'' from your system.
;The Linux database directory
: The <tt>directory</tt> line refers to a Linux filesystem directory, not an LDAP directory; it's the location of the database files maintained by the database system specified by the preceding <tt>database</tt> line. This directory must be specified as an absolute path. You may need to adjust this option for your system.
;The database mode
: The <tt>mode</tt> line specifies a Linux file mode for the database files. Normally, <tt>0600</tt> is appropriate: it prevents unauthorized snooping or modifications.
;ACLs
: Access Control Lists specify who may access particular types of data in the directory and in what way. They're conceptually similar to filesystem ACLs, but the details differ. The last few lines of [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]] define two ACLs, each of which begins with the keyword <tt>access</tt>. The first of these sets accesses conditions to the <tt>userPassword</tt> attribute: users may modify their own passwords (<tt>by</tt> <tt>self</tt> <tt>write</tt>), and all users may access this attribute for authentication (<tt>by</tt> <tt>*</tt> <tt>auth</tt>). The second ACL gives all users read access to all other attributes. ACLs are applied in order, with the earlier ACLs taking precedence over the later ones. In the case of [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]], the more restrictive ACL for the <tt>userPassword</tt> attribute must precede the read-only ACL for other attributes, lest users be granted the ability to read each other's passwords.

Once you've tweaked [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]] for your system, OpenLDAP is basically configured. You must still prepare the TLS certificates, though. Once that's done, you can start the <tt>slapd</tt> server.

=== Preparing Keys and Certificates ===

Although it's possible to run an LDAP server without using encryption, doing so is inadvisable, at least when the LDAP server is functioning as a network authentication tool. Encryption keeps your passwords secure; without it, passwords will be sent over the network in cleartext, which makes them susceptible to sniffing.

<div class="tip">
'''Tip'''

Use of SASL generally includes its own encryption mechanism, so if you use SASL, preparing encryption as described here isn't necessary. This chapter doesn't cover LDAP's SASL capabilities, though.
</div>

In [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]], the three lines under the <tt>TLS options</tt> comment set options related to SSL and TLS encryption, enabling OpenLDAP to engage in encrypted communications. In order for this configuration to work, though, you must first configure the TLS and SSL encryption tool, which is provided by the OpenSSL package (''http://www.openssl.org''). This package should be a dependency of any binary OpenLDAP package that can use SSL or TLS encryption, and it's also required to compile OpenLDAP with support for these methods of encryption. (If you compile OpenLDAP yourself, you may need to install a separate OpenSSL development package.)

<div class="tip">
'''Tip'''

As described in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#Obtaining and Installing OpenLDAP|Section 8.2.1]], LDAP supports encryption methods other than SSL and TLS. In order to keep this chapter manageable, though, and because SSL and TLS are popular and well-respected encryption tools for LDAP, they're the only ones described here.
</div>

SSL and TLS support a set of encryption tools, some of which require one-time manual preparation before they can be used. Most notable among these are ''keys'' and ''certificates'' . A key is a numeric code that can encrypt or decrypt data. Once data is encrypted with a key, it can only be decrypted with a matching key. Keys can be generated fairly automatically, but certificates require at least minimal input from users. They're designed to authenticate a site's identity and are essentially files with information on the owner of a server, signed and encrypted with a key that the other system trusts. One type of certificate is created by Certificate Authorities (CAs), which are organizations founded to create certificates for the sake of e-commerce and the like. web sites that use encrypted transmissions usually employ certificates created for them by CAs; web browsers can then decrypt the certificates sent by web sites and verify that they were signed by a trusted CA. If a certificate's signature doesn't check out, the web browser notifies the user that the site might not be trustworthy.

For in-house use, though, you don't need to go to a CA; you can create a certificate yourself. The OpenSSL package includes the tools necessary to do so. The simplest and most direct way is to call ''openssl'' with a series of options that cause it to generate a certificate and a key:

# '''openssl req -x509 -days 365 -newkey rsa: -nodes \'''
''' -keyout slapd-key.pem -out slapd-cert.crt'''
Generating a 1024 bit RSA private key
..........................++++++
.....++++++
writing new private key to 'server.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:'''US'''
State or Province Name (full name) [Some-State]:'''RI'''
Locality Name (eg, city) [ ]:'''Woonsocket'''
Organization Name (eg, company) [Internet Widgits Pty Ltd]:'''Very Old University'''
Organizational Unit Name (eg, section) [ ]:'''CS Dept'''
Common Name (eg, YOUR name) [ ]:'''ldap.pangaea.edu'''
Email Address [ ]:'''johndoe@pangaea.edu'''

Of course, you should customize the information in the certificate to describe your organization. Pay particular attention to the data you enter at the <tt>Common Name</tt> <tt>(eg, YOUR</tt> <tt>name)</tt> prompt; some clients, including the Windows LDAP authentication client, require this to match the hostname or IP address of the LDAP server. The result of running this command is two files: ''slapd-key.pem'' and ''slapd-cert.crt'' . These files contain a private key and a public certificate, respectively. Be sure that the private key can be read only by its owner; 600 (<tt>rw-------</tt>) permissions are appropriate, so type <tt>'''chmod'''</tt> <tt>'''600'''</tt> <tt>'''slapd-key.pem'''</tt> to set this file mode. (Some other OpenLDAP files, such as ''slapd.conf'', should be readable to all users, though.) Ordinarily, ''slapd'' runs as a specific user (such as ''ldap'', although this username varies from one distribution to another), so you should give ownership of the file to that user. If you run into problems launching the server you should check to see what user is running the server and adjust ownership of this file accordingly. You should now move the ''sldapd-key.pem'' and ''slapd-cert.crt'' files to the location specified by the <tt>TLSCertificateKeyFile</tt> and <tt>TLSCertificateFile</tt> parameters in ''slapd.conf''—''/etc/openldap/ssl'' in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]].

=== Running the Server ===

At this point, it's time to run the server. You can run ''slapd'' on a one-time basis by typing the server's filename (you may need to include the full path) or by using a SysV startup script. For instance, on a SuSE system, the SysV startup script is ''/etc/init.d/ldap'', so the following command does the trick:

# '''/etc/init.d/ldap start'''

As you test the server, you're likely to start and stop it frequently. Once it's running the way you want it to run, you'll probably want to configure your system to launch ''slapd'' at startup. You can do this as you would any other server that runs constantly. (Typically, ''slapd'' is run from a SysV or local startup script, not from a super server.) Typing <tt>'''chkconfig ldap on'''</tt> will do this on many systems, but some distributions use other commands instead of or in addition to ''chkconfig''. Consult distribution-specific documentation if you need help with this task.

One problem you may encounter is getting the server to bind to appropriate ports, particularly if you intend to use SSL encryption. By default, ''slapd'' binds to port 389, which is used for cleartext connections and those that negotiate TLS encryption after making an initial connection. Some clients, though, including the pGina tool that's described in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#Configuring Windows to Use LDAPfor Login Authentication|Section 8.5]], must use a dedicated SSL LDAP (that is, LDAPS) encryption port, 636. To force ''slapd'' to bind to this port, you must pass an appropriate parameter to the server with the <tt>-h</tt> option. Passing <tt>-h ldap:///</tt> causes ''slapd'' to bind to port 389 only, whereas passing <tt>-h ldap:/// ldaps:///</tt> causes it to bind to both ports 389 and 636. You may need to modify your ''slapd'' SysV startup script to add this option. Some SysV startup scripts, such as the one for SuSE Linux, include a variable in which you can pass these options; in the SuSE script, you edit the <tt>SLAPD_URLS</tt> variable to include <tt>ldaps:///</tt>.

== Creating a User Directory ==

Once the server is running, you must populate the directory with information about your network's users. To do this, you must understand distinguished name notation. Understanding at least the basics of LDIF files, which can be used to enter information into the directory, is also a necessity. With these pieces of information, you can actually begin populating the directory with user accounts.

=== Distinguished Names ===

Distinguished Names (DNs) are the pointers to data in a directory. They're similar in many ways to filenames in hard-disk filesystems. For example, the Linux filename ''/etc/X11/xdm/Xaccess'' refers to the ''Xaccess'' file in the ''/etc/X11/xdm'' directory, which in turn can be broken down into a series of subdirectories leading to the root directory of the Linux directory tree. Similarly, DNs are typically composed of multiple elements that enable an LDAP implementation to quickly locate the data. In the case of DNs, though, these elements are labeled according to type. Common types in an LDAP directory used for authentication include Domain Class (DC), Common Name (CN), User ID (UID, which is equivalent to a username rather than a numeric UID), and sometimes Organizational Unit (OU). Each abbreviation is converted to lowercase and separated from its value by an equal sign; these are then strung together with commas and identified as a DN by using the <tt>dn</tt> code and a colon:

dn: cn=Carl Linnaeus,dc=pangaea,dc=edu

This example refers to an entry for the common name <tt>Carl Linnaeus</tt> in the ''pangaea.edu'' domain. You may have noticed that this notation is similar to the one for the <tt>rootdn</tt> item in the ''slapd.conf'' file, as illustrated in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]]. This is no accident; the <tt>rootdn</tt> entry identifies a DN for a user with special privileges on the server.

<div class="tip">
'''Tip'''

Although the DC components of DN frequently combine to form an Internet domain name that's associated with the LDAP server, this isn't a requirement.
</div>

Occasionally, variants on this notation are necessary. One of these occurs when the CN for a user is not unique. For instance, suppose your organization has two users named Carl Linnaeus, one in the Botany department and one in the Genetics department. You might then create two DNs that add the appropriate OUs:

dn: cn=Carl Linnaeus+ou=Botany,dc=pangaea,dc=edu
dn: cn=Carl Linnaeus+ou=Genetics,dc=pangaea,dc=edu

<div class="tip">
'''Tip'''

In practice, you'll create these DNs in files with intervening lines that specify other account characteristics, as described in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#Understanding LDIF|Section 8.3.2]].
</div>

In this example, the DN begins with a Relative Distinguished Name (RDN)—<tt>cn=Carl Linnaeus+ou=Botany</tt> or <tt>cn=Carl Linnaeus+ou=Genetics</tt>. An RDN uses a plus sign (<tt>+</tt>) to separate two attributes, neither of which is unique by itself. In this example, two users named Carl Linnaeus exist, and presumably both the Botany and Genetics OUs host other users.

<div class="tip">
'''Tip'''

The use of the plus sign to separate RDN components means that this symbol can't be used within an element without taking special steps. Specifically, if an element must contain a plus sign, the plus sign should be preceded by a backslash (<tt>\</tt>). Other special characters that should be preceded by a backslash include a hash mark (<tt>#</tt>) at the start of a string, a space at the end of a string, a comma (,), a double quote ("), a backslash, a semicolon (<tt>;</tt>), and angle brackets (<tt><</tt> or <tt>></tt>). Chances are you won't need to use any of these symbols in the DN elements for a Unix-based account database, although spaces are common in databases that originate on Windows systems.
</div>

DNs are usually case-insensitive, but case is preserved in storing them. Thus, <tt>cn=carl</tt> <tt>linnaeus,dc=pangaea,dc=edu</tt> is equivalent to <tt>cn=Carl Linnaeus,dc=pangaea,dc=EDU</tt>. This characteristic is based on matching rules defined in the schema, though, so it's not always true.

=== Understanding LDIF ===

Behind the scenes, OpenLDAP may use any of several databases for data storage; but to examine and modify data, a common plain-text format is desirable. This is where LDIF comes into the picture; it represents LDAP directory entries that are invariant across OpenLDAP backends, and even across LDAP implementations. For the most part, it consists of a series of attribute names and values, separated by colons. Entries begin with the DN entry, as described earlier. Subsequent entries' content depend on the schemas a directory uses. The NIS schema defines several object classes, each of which defines several attributes. For the purposes of this chapter, the <tt>posixAccount</tt> object class is one of the most important of these object classes. This object class's attributes roughly correspond to entries in the traditional Linux ''/etc/passwd'' file, as shown in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-FIG-2|Figure 8-2]].

<div id="linuxwinworld-CHP-8-FIG-2">
'''Figure 8-2. The posixAccount object class defines data traditionally found in /etc/passwd'''

[[Image:Linux in a Windows World_I_2_tt99.png|The posixAccount object class defines data traditionally found in /etc/passwd]]
</div>

Every field in the ''/etc/passwd'' file maps to an attribute in the <tt>posixAccount</tt> object class, although the names aren't always intuitive. In particular, the <tt>uid</tt> attribute maps to the Linux username; the <tt>uidNumber</tt> attribute holds the Linux UID number. The <tt>posixAccount</tt> object class also defines two attributes, <tt>cn</tt> and <tt>description</tt>, that aren't present in ''/etc/passwd''. Of these, <tt>cn</tt> is required and typically holds the user's real name.

[[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-FIG-3|Figure 8-3]] shows a mapping of the <tt>shadowAccount</tt> object class to entries traditionally found in ''/etc/shadow''. All these entries except <tt>uid</tt> are optional. This attribute, though, as well as the <tt>userPassword</tt> and <tt>description</tt> attributes, are in fact shared with the <tt>posixAccount</tt> object class. Specifying values for all the required attributes in these two object classes creates a user account.

<div id="linuxwinworld-CHP-8-FIG-3">
'''Figure 8-3. The shadowAccount object class defines data traditionally found in /etc/shadow'''

[[Image:Linux in a Windows World_I_2_tt100.png|The shadowAccount object class defines data traditionally found in /etc/shadow]]
</div>

<div class="tip">
'''Tip'''

In traditional Linux accounts, using shadow passwords and the ''/etc/shadow'' file increases security. The equivalent use of the <tt>shadowAccount</tt> object class in LDAP does ''not'' have this effect, though. When properly configured, an LDAP account directory should be at least as secure as a Linux shadow passwords system, whether or not you place data in the <tt>shadowAccount</tt> structures. What <tt>shadowAccount</tt> does provide is a place to store password aging and expiration information.
</div>

Between these two object classes, you can define an account. To do so in an LDIF file, you create one line per attribute, plus a few <tt>objectClass</tt> attributes pointing to the objects upon which the <tt>posixAccount</tt> and <tt>shadowAccount</tt> objects rely. The result looks something like this:

dn: uid=linnaeus,ou=People,dc=pangaea,dc=edu
uid: linnaeus
cn: Carl Linnaeus
objectClass: account
objectClass: posixAccount
objectClass: top
objectClass: shadowAccount
userPassword: {crypt}KpP.s/mnFoEoI
shadowLastChange: 12561
shadowMax: 99999
shadowWarning: 7
loginShell: /bin/bash
uidNumber: 780
gidNumber: 100
homeDirectory: /home/linnaeus
gecos: Carl Linnaeus

<div class="tip">
'''Tip'''

Don't start generating accounts by copying this entry. As described in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#Creating the Directory|Section 8.3.3]], there are easier ways to populate your directory than creating LDIF files by hand.
</div>

[[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-FIG-4|Figure 8-4]] shows a mapping of the <tt>posixGroup</tt> object class to entries traditionally found in ''/etc/group''. These entries are necessary if the server is to deliver group information as well as account information to clients. Note that these objects are not directly related to accounts, although they do refer to accounts; the <tt>memberUid</tt> attribute points to user accounts. (Likewise, the <tt>gidNumber</tt> field in the <tt>posixAccount</tt> object class points to a <tt>posixGroup</tt> via its <tt>gidNumber</tt> field.)

<div id="linuxwinworld-CHP-8-FIG-4">
'''Figure 8-4. The posixGroup object class defines data traditionally found in /etc/group'''

[[Image:Linux in a Windows World_I_2_tt102.png|The posixGroup object class defines data traditionally found in /etc/group]]
</div>

The NIS schema file defines several object classes in addition to those described here. These object classes enable an LDAP server to deliver information that's traditionally contained in ''/etc/fstab'', ''/etc/hosts'', ''/etc/protocols'', and more—in short, the data that's normally delivered by an NIS server. Configuring OpenLDAP to deliver this information is similar to configuring it to deliver account and group information, but such configurations are beyond the scope of this chapter.

=== Creating the Directory ===

The simplest way to populate an OpenLDAP directory with account and group information is to convert this information from existing account and group files. You can perform this task with scripts available on the Internet. If you're not migrating accounts directly, you may want to use these tools on a dummy password file to create a template you can use to create new accounts in piecemeal fashion.

The scripts you use to migrate an existing set of Linux accounts can be obtained from ''http://www.padl.com/OSS/MigrationTools.html''. The download links at the bottom of this page retrieve a file called ''MigrationTools.tgz''. This tarball contains a series of Perl scripts, each of which reads the contents of one or more system configuration files and creates an equivalent LDIF file.

<div class="tip">
'''Tip'''

The migration tools package described here has a project version number of 45, as revealed in the ''CVSVersionInfo.txt'' file. If you obtain a more recent version, you may find that some of the details have changed.
</div>

Before running the conversion scripts, you must edit one of them (''migrate_common.ph'') so that it holds appropriate site-specific information. Specifically, change the <tt>$DEFAULT_MAIL_DOMAIN</tt> and <tt>$DEFAULT_BASE</tt> variables, defined on lines 71 and 74, to point to your DNS domain and your directory's base. For instance, to conform to the options shown in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-EX-1|Example 8-1]], set these options as follows:

$DEFAULT_MAIL_DOMAIN = "pangaea.edu";
$DEFAULT_BASE = "dc=pangaea,dc=edu";

Once this task is done, you can create LDIF files using the appropriate scripts. Of particular interest are the ''migrate_passwd.pl'' and ''migrate_group.pl'' scripts, which migrate your account database (including both ''/etc/passwd'' and ''/etc/shadow'') and your ''/etc/group'' file, respectively. Both scripts accept the name of the source file (just ''/etc/passwd'' in the case of ''migrate_passwd.pl'') followed by an output file:

# '''./migrate_passwd.pl /etc/passwd passwd.ldif'''
# '''./migrate_group.pl /etc/group group.ldif'''

You can examine the contents of these LDIF files, if you like. At a minimum, you might want to perform a quick check to verify that all your users have entries in the password file. You might also want to eliminate system accounts that don't require authentication and those that you don't want to be authenticated via the LDAP server. If you eliminate such accounts, though, be sure that they either exist in your clients' local account databases or aren't required by your clients.

<div class="tip">
'''Tip'''

The migration scripts can't decrypt the already encrypted passwords in the password database. Therefore, they're entered into the LDIF file using the <tt>{crypt}</tt> encoding notation.
</div>

These scripts don't create entries for the top-level DNs. If you haven't created them already, you should add them to the start of each file. For the password file, the entries for the example domain are these:

dn: dc=pangaea,dc=edu
objectClass: domain
dc: pangaea

dn: ou=People,dc=pangaea,dc=edu
objectClass: organizationalUnit
ou: People

The entry to add to the start of the groups file is similar:

dn: ou=Group,dc=pangaea,dc=edu
objectClass: organizationalUnit
ou: Group

Of course, in both cases, you must make changes to the <tt>dn</tt> and <tt>dc</tt> lines suitable for your organization. Once you've done this, you're ready to add the LDIF files to your LDAP directory. You can do this with either the ''ldapadd'' command or the ''slapadd'' command, using the <tt>-f</tt> or <tt>-l</tt> parameters (respectively) to pass the name of the LDIF file you want to add. You might also want to use <tt>-v</tt>, which provides feedback on the success of the operations. (If you use ''ldapadd'', though, you'll first need to perform additional client configurations, as described in the next section.) For instance, these commands add both the files created earlier:

# '''slapadd -v -l passwd.ldif'''
# '''slapadd -v -l group.ldif'''

=== Account Maintenance ===

Account maintenance on an OpenLDAP server uses various utilities whose names begin with ''ldap'', as described earlier. Of particular interest are ''ldapadd'', which adds accounts; ''ldapmodify'', which modifies existing accounts; and ''ldapdelete'', which deletes accounts. You can run these commands on any LDAP client computer (including the LDAP server itself, if it's properly configured as a client); they use the network protocol to communicate with the server.

These tools rely on the ''/etc/openldap/ldap.conf'' configuration file. Before you can use these tools, therefore, you should edit this file. Normally, you must set the <tt>BASE</tt> and <tt>URI</tt> options, and possibly point the system to a certificate file:

BASE dc=pangaea,dc=edu
URI ldaps://ldap.pangaea.edu
TLS_CACERT /etc/openldap/ssl/certs/slapd-cert.crt

The first of these entries should be familiar by now; it's the root of the LDAP directory you'll be using. The <tt>URI</tt> entry points to the LDAP server, using a URI format similar to that used to express web addresses, except that it begins with the <tt>ldaps://</tt> keyword. You can use <tt>ldap://</tt> rather than <tt>ldaps://</tt> if you don't want to require the use of SSL encryption. (The system may still negotiate TLS encryption during the session, however.) If you specify an LDAPS port in the URI, you must point the server to a file that contains certificates (via <tt>TLS_CACERT</tt>) or to a directory that contains certificate files (via <tt>TLS_CACERTDIR</tt>). You must copy the certificate you generated on the server to this location. If you don't, the client tools will refuse to communicate with the server.

In order to perform most account maintenance tasks, you must access the server with sufficient privileges; by default, the LDAP utilities perform anonymous accesses. You can specify a suitable high-privilege DN with the <tt>-D</tt> option. When you do, you must also include the <tt>-W</tt> option to have the utility prompt you for a password. You can use the administrative DN and password you specified in your ''slapd.conf''.

To add an account, you should prepare an LDIF file. You can use an entry from an LDIF file created from ''/etc/passwd'' using ''migrate_passwd.pl'' as a model, if you like. You can then pass this file to ''ldapadd'':

$ '''ldapadd -D cn=manager,dc=pangaea,dc=edu -W -f acct.ldif'''

<div class="tip">
'''Tip'''

Because you're passing the authentication information to the server, you don't need type this command as ''root''.
</div>

The ''ldapmodify'' command works in much the same way, except that the file you pass to the utility contains modifications to an existing entry rather than new account information. To delete an account, you use the ''ldapdelete'' command, omit the <tt>-f</tt> parameter, and instead pass the DN of the account you want to delete:

$ '''ldapdelete -D cn=manager,dc=pangaea,dc=edu -W uid=linnaeus,ou=People,'''
'''dc=pangaea,dc=edu'''

This example deletes the ''linnaeus'' account in the ''People'' unit on the LDAP server. Changing a password is similar, but you must also pass the <tt>-S</tt> option to be prompted for the new password, as well as changing the name of the tool:

$ '''ldappasswd -D cn=manager,dc=pangaea,dc=edu -S -W uid=linnaeus,ou=People,'''
'''dc=pangaea,dc=edu'''
New password:
Re-enter new password:
Enter LDAP Password:
Result: Success (0)

Unlike the standard Linux ''passwd'' command, ''ldappasswd'' prompts for the new password ''before'' prompting for the administrative LDAP password. As with most password-handling tools, this one doesn't echo the passwords to the screen.

<div class="tip">
'''Tip'''

The ''ldappasswd'' command isn't intended as a full replacement for ''passwd''. If you configure the ''/etc/pam.d/passwd'' file to use LDAP, as described in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#Configuring the LDAP PAM Modules|Section 8.4.4]] and [[Linux in a Windows World/Appendixes/Configuring PAM|Appendix A]], the standard Linux ''passwd'' command will change users' passwords on the LDAP server instead of or in addition to changing the local password when an ordinary user calls this tool. The ''ldappasswd'' command is useful mainly when a user has forgotten a password; you can use your LDAP administrative access to replace the forgotten password.
</div>

If you're used to normal Linux account maintenance tools such as ''useradd'' and ''userdel'', these LDAP account maintenance tools may seem awkward at first. If you keep a template LDIF file handy and prepare scripts with the necessary options, DNs can save you a lot of typing and make using these tools far more intuitive.

Various additional tools exist that help manage LDAP accounts. For instance, phpLDAPadmin (''http://phpldapadmin.sourceforge.net/'') is a web-based tool that provides a point-and-click interface to your account database. You could also write some scripts yourself to help simplify these tasks.

== Configuring Linux to Use LDAP for Login Authentication ==

At this point, your LDAP server should be running and should contain account information for your site. In order to do any good, though, you must be able to use that LDAP server for user authentication. In the case of Linux systems, this entails configuring the Pluggable Authentication Modules system and the Name Service Switch system to interface with LDAP. This requires understanding the basic relationships between these systems, installing necessary modules, and configuring the modules.

<div class="tip">
'''Tip'''

To use Windows as an LDAP login client, consult the [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#Configuring Windows to Use LDAPfor Login Authentication|Section 8.5]].
</div>

=== LDAP, PAM, and NSS ===

The PAM and NSS systems are at the core of Linux's account management. These systems are described in [[Linux in a Windows World/Centralized Authentication Tools/Using NT Domains for Linux Authentication|Chapter 7]] and in [[Linux in a Windows World/Appendixes/Configuring PAM|Appendix A]]. In brief, PAM is a set of libraries that sits between applications and the account database for authentication purposes. Instead of accessing account databases directly, PAM-enabled applications consult PAM. This arrangement enables you to modify your authentication system (such as adding LDAP) with relative ease, by reconfiguring PAM rather than rewriting all the programs that require authentication. Similarly, NSS manages access to nonauthentication account information, such as home directory locations.

In order to configure a Linux system to use LDAP, you must tie LDAP into these two systems. This is done by installing PAM and NSS support modules and by modifying PAM and NSS configuration files to call the LDAP modules.

=== Basic LDAP Client Configuration ===

Most Linux distributions make PAM and NSS modules for LDAP available in one or two packages that are separate from the main LDAP package. Packages that are called ''pam_ldap'' and ''nss_ldap'' are common, but some variants exist, such as Debian's ''libpam-ldap'' and ''libnss-ldap''.

The PAM and NSS modules both rely on a configuration file called ''ldap.conf'', which is normally stored in ''/etc''. (Instead of a single ''ldap.conf'' file, though, Debian uses two: ''libnss-ldap.conf'' and ''pam_ldap.conf'', both in ''/etc''. You must make similar changes to both files.) Before configuring PAM- and NSS-specific options, you should load this configuration file into an editor to customize it for your network.

<div class="tip">
'''Tip'''

The OpenLDAP package also includes a configuration file called ''ldap.conf'', but this file is likely to reside in the same directory as ''slapd.conf''—usually ''/etc/openldap''.
</div>

The ''/etc/ldap.conf'' file might be installed as part of any number of different packages. Most frequently, it's installed with the NSS LDAP package, but Debian places its two configuration files in the ''libnss-ldap'' and ''libpam-ldap'' packages, and SuSE distributes the file in the ''pwdutils'' package.

For the basic configuration described earlier in the chapter, you must modify two items, <tt>host</tt> and <tt>base</tt>, in the ''/etc/ldap.conf'' (or equivalent) file:

host 192.168.1.1
base dc=pangaea,dc=edu

The <tt>host</tt> item points the LDAP clients to the LDAP server by IP address or hostname. (The system must be able to locate the server without the use of LDAP, so if you're using LDAP for local hostname resolution, it's particularly important that you use an IP address.) The <tt>base</tt> item specifies the base of the directory tree that's served by your LDAP server.

If you've configured your system for high security, you must also set security options. Most importantly, you must uncomment one of two <tt>ssl</tt> lines:

ssl start_tls
ssl on

The first of these lines tells the client to negotiate TLS encryption after making a connection to the traditional LDAP port (389); the second tells the client to use SSL and connect to the LDAPS port (636). Several other security options also reside in this file; for instance, you can point the tools to a certificate file or directory with the <tt>tls_cacertfile</tt> or <tt>tls_cacertdir</tt> options. One of these options is required if you set <tt>tls_checkpeer</tt> <tt>yes</tt>, which makes the server refuse connections to a server if it has an unknown certificate.

=== Configuring the LDAP NSS Modules ===

NSS provides basic account information to the Linux system. It's controlled via its configuration file, ''/etc/nsswitch.conf''. To tell NSS to use LDAP as part of its operation, you must change just three lines in this file. Specifically, you should look for the lines beginning with the keywords <tt>passwd</tt>, <tt>shadow</tt>, and <tt>group</tt>. Each line contains a list of tools NSS uses to look up account information, and you should add <tt>ldap</tt> to each of these lines:

passwd: files ldap
shadow: files ldap
group: files ldap

<div class="tip">
'''Tip'''

As with PAM configuration files, the ''/etc/nsswitch.conf'' file varies from one distribution to another. If yours contains entries instead of or in addition to the <tt>files</tt> entry, the safest course is to add <tt>ldap</tt> to the end of whatever entries already exist. (The <tt>compat</tt> source is common with distributions based on ''glibc'' 2.3, for instance.) If you want LDAP to replace an existing authentication tool, though, you can remove the reference to that old tool.
</div>

<div class="note">
'''Note'''

If you want to use LDAP to take over additional duties, you can add <tt>ldap</tt> to additional appropriate lines in ''/etc/nsswitch.conf''. If you add <tt>ldap</tt> to the <tt>hosts</tt> line, for instance, the system attempts to use LDAP for hostname resolution. Of course, such configurations require adding appropriate directory entries to the LDAP server, much as you added user accounts to the server.
</div>

=== Configuring the LDAP PAM Modules ===

Once you've configured ''/etc/ldap.conf'' or its equivalent and modified ''/etc/nsswitch.conf'', you can begin telling PAM to use LDAP for authentication of various services. This process is described in [[Linux in a Windows World/Appendixes/Configuring PAM|Appendix A]], so look there for details of PAM configuration. This section describes some LDAP-specific features. In most cases, you'll modify files in ''/etc/pam.d''; each file is named after the login or account maintenance service you want to adjust.

To add LDAP to the login authentication, you must add a couple of lines to the PAM configuration file for the service you want to use LDAP:

auth sufficient /lib/security/pam_ldap.so try_first_pass
account sufficient /lib/security/pam_ldap.so

<div class="warning">
'''Warning'''

Modifying your PAM configuration modifies how Linux authenticates you. A mistake can result in an inability to log into the computer. For this reason, I recommend modifying these files one at a time, leaving at least one known-working login tool unmodified. This way, if you create a nonfunctional service, you'll still be able to log in using another tool to correct the problem. Backing up the original files can also help you recover from such an error.
</div>

Typically, you'll modify all your active login services' PAM modules in analogous ways. These are likely to include ''login'', ''gdm'', ''xdm'', ''sshd'', ''ftp'', and perhaps some others. If your system uses the <tt>pam_stack</tt> system, though, you may be able to get away with modifying just one file: ''system-auth''. However, you might want to keep some authentication tools local. For instance, you might want to use the local database only for ''sudo'', which is often used to obtain ''root'' privileges; if your LDAP directory doesn't include information on the ''root'' account, it obviously won't be useful for ''sudo'''s typical uses.

=== Verifying Proper Functioning ===

At this point, the Linux system should be using the LDAP server for user authentication. One way to check this is to type <tt>'''getent'''</tt> <tt>'''passwd'''</tt>. This command returns user account information. (A similar command, <tt>'''getent'''</tt> <tt>'''group'''</tt>, returns group information.) On a system that uses only its local account files, the result is similar to typing <tt>'''cat'''</tt> <tt>'''/etc/passwd'''</tt>; however, on a system that uses an LDAP server, you should see additional entries for LDAP-accessible accounts. A partial output might look like this:

# '''getent passwd'''
root:x:0:0:root:/root:/bin/bash
bin:x:1:1:bin:/bin:/bin/false
linnaeus:x:500:100:C. Linnaeus:/home/linnaeus:/bin/bash
linnaeus:x:500:100:Carl Linnaeus:/home/linnaeus:/bin/bash

This output reveals an oddity: the user ''linnaeus'' has two entries. One entry is in the computer's local ''/etc/passwd'' file; the other originates on the LDAP server. (If the two lines are different, you can tell which is which by comparing the lines to the contents of the local ''/etc/passwd'' file.) In this case, no harm comes of this because information from the two sources is identical, aside from the minor detail of the user's full name. If the entries had different data, though, such as different UIDs or home directories, confusion can result. Thus, it's best not to duplicate accounts between the LDAP server and the local system. If duplicates do occur, the first one takes precedence. NSS orders accounts according to the order specified on the <tt>passwd</tt>, <tt>shadow</tt>, and <tt>group</tt> lines in ''/etc/nsswitch.conf'', so placing <tt>ldap</tt> after <tt>files</tt> in this file gives local files precedence over LDAP entries.

If you've been able to verify your LDAP-generated accounts with ''getent'', you can proceed to testing the login tools. Use whatever login tool you've modified to use LDAP and try to log in. Try entering accounts that are defined only via LDAP and only via the local account files, to be sure both work. Try entering both correct and incorrect passwords to be sure that the system is correctly handling the case of login failures. If a password is correct for one system (such as LDAP or your local files) but incorrect for the other, the behavior will vary depending on your precise configuration, as described in [[Linux in a Windows World/Appendixes/Configuring PAM|Appendix A]].

== Configuring Windows to Use LDAPfor Login Authentication ==

All this talk of using LDAP for Linux authentication is well and good, but this book is about integrating Linux and Windows on a network. How, then, does LDAP help you with Windows clients? The answer is that Windows—or at least, Windows NT/200x/XP—uses an authentication system known as Graphical Identification and Authentication (GINA). Supplements to the Microsoft-supplied GINA are available, and you can use one of these to have Windows authenticate against your LDAP server.

One of the most flexible GINA supplements is known as pGina (''http://pgina.xpasystems.com''), which is a modular open source GINA tool. You can find pGina modules that support LDAP, MySQL, NIS, SecurID, and many more authentication systems. The following pages are devoted to pGina's LDAP functionality. Unfortunately, pGina is limited to working with Windows 200x/XP; it doesn't work with Windows 9x/Me. (In theory, pGina should work with Windows NT, but its LDAP module requires features that were added with Windows 2000.) Using pGina requires installing it and configuring it to use your LDAP server.

=== Obtaining and Installing pGina ===

You can obtain pGina from its web site. You'll need to download both the main pGina package (available from ''http://pgina.xpasystems.com/files/'') and the LDAP plugin module (available from ''http://pgina.xpasystems.com/plugins/''). Both packages come in the form of installer applications. This chapter uses pGina 1.7.6 and the LDAPAuth 1.4-beta plugin as references; some details may differ if you use another version of the package.

<div class="tip">
'''Tip'''

To work with Windows XP SP2, pGina Version 1.7.7.4 or later is required for best functionality.
</div>

Once you've downloaded the two installer programs, you should run them both as the Windows ''Administrator''. These are typical Windows program installers; they ask you to accept a license agreement (the GPL), where to install the program, and so on, then drop the files in the appropriate locations. The main pGina installer then runs the pGina configuration utility, but if you install it first, you'll have to run the LDAP plugin installer before you can configure pGina to use LDAP.

<div class="warning">
'''Warning'''

As with configuring PAM in Linux, installing and configuring pGina incorrectly can produce a system you can't access. You should prepare an emergency recovery disk and be prepared to use it with the Windows Safe Mode should problems occur. Completely backing up the Windows boot partition may be wise, as well. If you're preparing to install pGina on an entire network, try installing it first on a test system that holds no important data.
</div>

=== Registering Your Certificate ===

If you're using strong encryption, as is wise on most networks, you must register your SSL certificate with Windows. This step is necessary because Windows is fussier about certificates than are the Linux PAM and NSS LDAP modules; if Windows can't verify your certificate, you won't be able to establish an encrypted SSL connection with the LDAP server.

To do the deed, you should begin by making the LDAP certificate file (''slapd-cert.crt'' ), which you created earlier. You can place it on a file share, move it around on a floppy, or whatever's convenient. (This file is not sensitive from a security point of view, so you needn't take any precautions to prevent it from being seen by others.) Once the file is available in Windows, follow these steps:

<ol>
<li><div>Double-click the certificate file. This action should bring up the Certificate dialog box shown in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-FIG-5|Figure 8-5]]. If it doesn't, check the filename; it should end in a ''.crt'' extension. If it doesn't, correct the matter, and try again.

<div id="linuxwinworld-CHP-8-FIG-5">
'''Figure 8-5. Windows provides a tool for registering certificates you generate'''

[[Image:Linux in a Windows World_I_2_tt117.png|Windows provides a tool for registering certificates you generate]]
</div>
</div></li>

<li><div>Click Install Certificate. This action yields a certificate installation wizard.
</div></li>

<li><div>Click Next in the wizard. The result resembles [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-FIG-6|Figure 8-6]], except that this figure shows some data entered as described in the next few steps.

<div id="linuxwinworld-CHP-8-FIG-6">
'''Figure 8-6. The certificate installation wizard lets you select how to categorize your certificate'''

[[Image:Linux in a Windows World_I_2_tt118.png|The certificate installation wizard lets you select how to categorize your certificate]]
</div>
</div></li>

<li><div>Click Place all certificates in the following store.
</div></li>

<li><div>Click Browse. The wizard displays a dialog box called Select Certificate Store.
</div></li>

<li><div>In the Select Certificate Store dialog box, check the Show Physical Stores checkbox.
</div></li>

<li><div>In the Select Certificate Store dialog box, expand the Trusted Root Certification Authorities item.
</div></li>

<li><div>An object called Local Computer should now be visible. Highlight it and click OK in the Select Certificate Store dialog box. Your wizard should now show the same path in the Certificate Store field as is shown in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-FIG-6|Figure 8-6]].
</div></li>

<li><div>Click Next. The wizard presents a summary screen.
</div></li>

<li><div>Click Finish. A message stating that the import was successful should appear.
</div></li>

</ol>

At this point, your certificate should be installed, which should enable you to use SSL encryption with your LDAP server, provided the server is properly configured to accept this encryption.

=== Configuring pGina for LDAP Client Use ===

Before proceeding to actual pGina configuration, I recommend you test the LDAP module. To do so, select Start → Programs → pGina → PluginTester from the Windows desktop. The result is a large pGina Plugin Simulation dialog box. Click the Browse button to locate the LDAP plugin, which by default is installed in a subdirectory of your main pGina installation directory. You can then click the Configure button, which brings up the pGina LDAPAuth configuration dialog box, shown in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-FIG-7|Figure 8-7]].

<div id="linuxwinworld-CHP-8-FIG-7">
'''Figure 8-7. To configure pGina's LDAP module, use a dialog box to enter many of the options you enter in Linux LDAP client configuration files'''

[[Image:Linux in a Windows World_I_2_tt119.png|To configure pGina's LDAP module, use a dialog box to enter many of the options you enter in Linux LDAP client configuration files]]
</div>

You must give pGina's LDAPAuth dialog box some basic information on your LDAP server. The most important information items are the LDAP Server, Use SSL, and Contexts items. The other items can be important in some situations, but are beyond the scope of this chapter to describe; consult the pGina documentation for details. Enter your server's IP address or hostname in the LDAP Server field. If you're using SSL encryption, you ''must'' use the name you specified in the <tt>Common</tt> <tt>Name</tt> <tt>(eg</tt>, <tt>YOUR</tt> <tt>name)</tt> item when you created your certificate, as described in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#Preparing Keys and Certificates|Section 8.2.3]]. You must also check the Use SSL checkbox to enable SSL encryption. For the Contexts, you must enter a context in the field just above the Add Context button, then click that button. Your entry will then be moved to the larger field to the right of the button. Typically, the context you enter will be your root DN, as shown in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-FIG-7|Figure 8-7]].

After entering this information, click OK. The system says it's saved the settings. You can then type a username and password into the large pGina Plugin Simulation dialog box, and click Login. (Note that your password will echo when you type it, and it will also appear in the dialog box once it's been authenticated.) If all goes well, the program reports "plugin reported success", along with information on the account in the main dialog box. If the tool instead reports a failure, you should click Configure to go back to the configuration dialog box and make changes. Because of pGina's insistence on verifying the server's certificate, this can be a problem area. You may want to temporarily disable SSL encryption (on both the client and the server) to simplify matters while you troubleshoot. Once you can authenticate users, click Exit.

To fully configure pGina, select Start → Programs → pGina → Configuration Tool. (The installer launches this program automatically by default, so it may already be running.) The result is the main pGina configuration dialog box, shown in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-FIG-8|Figure 8-8]]. Basic configuration at this point is fairly simple: click Browse to locate the LDAP plugin. If you haven't tested the plugin, though, you'll also need to click Configure to configure it. Testing your configuration can be tricky unless you use the plugin tester program, as just described.

<div id="linuxwinworld-CHP-8-FIG-8">
'''Figure 8-8. The main pGina configuration dialog box'''

[[Image:Linux in a Windows World_I_2_tt120.png|The main pGina configuration dialog box]]
</div>

In addition to the basic configuration, you may want to adjust some of the more advanced features of pGina:

* You can tell pGina to map network drives by entering a mapping in the Drive Maps field. For instance, entering <tt>'''M:\\MANDRAGORA\SHARED'''</tt> maps the ''SHARED'' share on the ''MANDRAGORA'' server to the local ''M'': drive letter. (This requires that the SMB/CIFS server use the same password that's stored by the LDAP server.)
* You can force all users to belong to a specified set of groups by entering those groups in the Groups field. Separate groups with semicolons (<tt>;</tt>), as in <tt>Users;Staff</tt> to make all users members of both the ''Users'' and ''Staff'' groups.
* You can set features of the logon display, such as the graphic shown and any login messages, by using the Logon Window tab.
* By default, pGina keeps users' profiles between logons, meaning that users can customize their desktops and keep these settings. If you want users to see a standard desktop at each logon, you can uncheck the Keep Profiles item on the Account Information tab. The Force Login checkbox on this tab tells pGina to store the authenticated password locally, which should enable local logins even if the LDAP server goes down, provided the user has authenticated before. (This option might be handy on laptop computers.)
* The Domain Interaction tab presents options that enable pGina to perform domain authentication, as well as LDAP authentication. If your network hosts both an LDAP server and an NT Domain controller, each with its own set of accounts, this option enables a client to authenticate against either server.

Once you've configured pGina, you need to reboot the computer for the changes to take effect. Once you do, you'll be greeted by a new pGina login prompt, as shown in [[Linux in a Windows World/Centralized Authentication Tools/Using LDAP#linuxwinworld-CHP-8-FIG-9|Figure 8-9]]. You should be able to log on using any of the accounts defined on your LDAP server, as well as any accounts that are defined locally on the Windows system. When you log on using an LDAP account, pGina automatically generates a matching local account. The user thereafter appears in the local user database unless you manually delete the accounts or uncheck the Keep Profiles checkbox, as just described.

<div id="linuxwinworld-CHP-8-FIG-9">
'''Figure 8-9. Once pGina is working, it presents its own logon screen rather than the default Windows logon screen'''

[[Image:Linux in a Windows World_I_2_tt121.png|Once pGina is working, it presents its own logon screen rather than the default Windows logon screen]]
</div>

== Summary ==

LDAP is an extremely powerful tool for managing information on a network. Although by no means its only possible role, one good way to begin using LDAP is as a cross-platform authentication tool. In order to configure an LDAP server for this role, you must begin by installing a server package, such as OpenLDAP. Much of the tedium of LDAP configuration comes with properly configuring the server; you must set basic server configuration options, enable security options, and create an initial account database backend for the server. Only then can you configure your clients, which is a relatively straightforward task involving setting options in a few configuration files. Windows clients require a helper application, such as pGina, to integrate with an LDAP server, but once this software is installed, these servers can work quite nicely. The result of all this work is integrated Linux/Windows account information and simplified account maintenance, particularly on a mid-sized or large network. On a complex or large network, the savings in day-to-day administrative hassles more than compensates for the time you invest in configuring LDAP.

Linux in a Windows World/Centralized Authentication Tools/Using LDAP - Revision history

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki: Initial conversion from Docbook