Gentoo Guide to OpenLDAP Authentication

1.  Getting Started with OpenLDAP

What is LDAP?

LDAP stands for Lightweight Directory Access Protocol. Based on X.500 it encompasses most of its primary functions, but lacks the more esoteric functions that X.500 has. Now what is this X.500 and why is there an LDAP?

X.500 is a model for Directory Services in the OSI concept. It contains namespace definitions and the protocols for querying and updating the directory. However, X.500 has been found to be overkill in many situations. Enter LDAP. Like X.500 it provides a data/namespace model for the directory and a protocol too. However, LDAP is designed to run directly over the TCP/IP stack. See LDAP as a slim-down version of X.500.

I don't get it. What is a directory?

A directory is a specialized database designed for frequent queries but infrequent updates. Unlike general databases they don't contain transaction support or roll-back functionality. Directories are easily replicated to increase availability and reliability. When directories are replicated, temporary inconsistencies are allowed as long as they get synchronised eventually.

How is information structured?

All information inside a directory is structured hierarchically. Even more, if you want to enter data inside a directory, the directory must know how to store this data inside a tree. Lets take a look at a fictional company and an Internet-like tree:

dc:         com
             |
dc:        genfic         (Organisation)
          /      \
ou:   people   servers    (Organisational Units)
      /    \     ..     
uid: ..   jhon            (OU-specific data)

Since you don't feed data to the database in this ascii-art like manner, every node of such a tree must be defined. To name such nodes, LDAP uses a naming scheme. Most LDAP distributions (including OpenLDAP) already contain quite a number of predefined (and general approved) schemes, such as the inetorgperson, a frequently used scheme to define users.

Interested users are encouraged to read the OpenLDAP Admin Guide.

So... What's the Use?

LDAP can be used for various things. This document focuses on centralised user management, keeping all user accounts in a single LDAP location (which doesn't mean that it's housed on a single server, LDAP supports high availability and redundancy), yet other goals can be achieved using LDAP as well.

• Public Key Infrastructure
• Shared Calendar
• Shared Addressbook
• Storage for DHCP, DNS, ...
• System Class Configuration Directives (keeping track of several server configurations)
• ...

2.  Configuring OpenLDAP

Initial Configuration

Lets first emerge all necessary components on our server:

# emerge ">=net-nds/openldap-2.3.38" pam_ldap nss_ldap

Now generate an encrypted password we'll use later on:

# slappasswd
New password: my-password
Re-enter new password: my-password
{SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4

Now edit the LDAP Server config at /etc/openldap/slapd.conf:

# Include the needed data schemes below core.schema
include         /etc/openldap/schema/cosine.schema
include         /etc/openldap/schema/inetorgperson.schema
include         /etc/openldap/schema/nis.schema

Uncomment modulepath and hdb module
# Load dynamic backend modules:
modulepath    /usr/lib/openldap/openldap
# moduleload    back_shell.so
# moduleload    back_relay.so
# moduleload    back_perl.so
# moduleload    back_passwd.so
# moduleload    back_null.so
# moduleload    back_monitor.so
# moduleload    back_meta.so
moduleload    back_hdb.so
# moduleload    back_dnssrv.so

# Uncomment sample access restrictions (Note: maintain indentation!)
access to dn.base="" by * read
access to dn.base="cn=Subschema" by * read
access to *
   by self write
   by users read
   by anonymous auth


# BDB Database definition

database        hdb
suffix          "dc=genfic,dc=com"
checkpoint      32      30 # <kbyte> <min>
rootdn          "cn=Manager,dc=genfic,dc=com"
rootpw          {SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4
directory       /var/lib/openldap-ldbm
index           objectClass     eq

Next we edit the LDAP Client configuration file:

# nano -w /etc/openldap/ldap.conf
(Add the following...)

BASE         dc=genfic, dc=com
URI          ldap://auth.genfic.com:389/
TLS_REQCERT  allow

Now edit /etc/conf.d/slapd and add the following, commenting out the existing line:

# Note: we don't use cn=config here, so stay with this line:
OPTS="-h 'ldap:// ldapi://%2fvar%2frun%2fopenldap%2fslapd.sock'"

Start slapd:

# /etc/init.d/slapd start

You can test with the following command:

# ldapsearch -D "cn=Manager,dc=genfic,dc=com" -W

If you receive an error, try adding -d 255 to increase the verbosity and solve the issue you have.

3.  Client Configuration

Migrate existing data to ldap

Go to http://www.padl.com/OSS/MigrationTools.html and fetch the scripts there. Configuration is stated on the page. We don't ship this anymore because the scripts are a potential security hole if you leave them on the system after porting. When you've finished migrating your data, continue to the next section.

Configuring PAM

First, we will configure PAM to allow LDAP authorization. Install sys-auth/pam_ldap so that PAM supports LDAP authorization, and sys-auth/nss_ldap so that your system can cope with LDAP servers for additional information (used by nsswitch.conf).

# emerge pam_ldap nss_ldap

Now add the following lines in the right places to /etc/pam.d/system-auth:

# Note: only add them. Don't kill stuff already in there or your box won't let you login again!

auth       sufficient   pam_ldap.so use_first_pass
account    sufficient   pam_ldap.so
password   sufficient   pam_ldap.so use_authtok use_first_pass
session    optional     pam_ldap.so

# Example file:
#%PAM-1.0

auth       required     pam_env.so
auth       sufficient   pam_unix.so try_first_pass likeauth nullok
auth       sufficient   pam_ldap.so use_first_pass
auth       required     pam_deny.so

account    sufficient   pam_ldap.so
account    required     pam_unix.so

password   required     pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 try_first_pass retry=3
password   sufficient   pam_unix.so try_first_pass use_authtok nullok md5 shadow
password   sufficient   pam_ldap.so use_authtok use_first_pass
password   required     pam_deny.so

session    required     pam_limits.so
session    required     pam_unix.so
session    optional     pam_ldap.so

Now change /etc/ldap.conf to read:

#host 127.0.0.1
#base dc=padl,dc=com

suffix          "dc=genfic,dc=com"
#rootbinddn uid=root,ou=People,dc=genfic,dc=com

uri ldap://auth.genfic.com/
pam_password exop

ldap_version 3
pam_filter objectclass=posixAccount
pam_login_attribute uid
pam_member_attribute memberuid
nss_base_passwd ou=People,dc=genfic,dc=com
nss_base_shadow ou=People,dc=genfic,dc=com
nss_base_group  ou=Group,dc=genfic,dc=com
nss_base_hosts  ou=Hosts,dc=genfic,dc=com

scope one

Next, copy over the (OpenLDAP) ldap.conf file from the server to the client so the clients are aware of the LDAP environment:

(Substitute ldap-server with your LDAP server name)
# scp ldap-server:/etc/openldap/ldap.conf /etc/openldap

Finally, configure your clients so that they check the LDAP for system accounts:

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

To test the changes, type:

# getent passwd|grep 0:0

(You should get two entries back:)
root:x:0:0:root:/root:/bin/bash 
root:x:0:0:root:/root:/bin/bash

If you noticed one of the lines you pasted into your /etc/ldap.conf was commented out (the rootbinddn line): you don't need it unless you want to change a user's password as superuser. In this case you need to echo the root password to /etc/ldap.secret in plaintext. This is DANGEROUS and should be chmoded to 600. What I do is keep that file blank and when I need to change someones password thats both in the ldap and /etc/passwd I put the pass in there for 10 seconds while I change it and remove it when I'm done.

4.  LDAP Server Security Settings

OpenLDAP permissions

If we take a look at /etc/openldap/slapd.conf you'll see that you can specify the ACLs (permissions if you like) of what data users can read and/or write:

access to *
  by dn="uid=root,ou=people,dc=genfic,dc=com" write
  by users read
  by anonymous auth

access to attrs=userPassword,gecos,description,loginShell
  by self write

This gives you access to everything a user should be able to change. If it's your information, then you got write access to it; if it's another user their information then you can read it; anonymous people can send a login/pass to get logged in. There are four levels, ranking them from lowest to greatest: auth search read write.

The next ACL is a bit more secure as it blocks normal users to read other people their shadowed password:

access to attrs="userPassword"
  by dn="uid=root,ou=people,dc=genfic,dc=com" write
  by dn="uid=John,ou=People,dc=genfic,dc=com" write
  by anonymous auth
  by self write
  by * none
  
access to *
  by dn="uid=root,ou=People,dc=genfic,dc=com" write
  by * search

This example gives root and John access to read/write/search for everything in the the tree below dc=genfic,dc=com. This also lets users change their own userPassword's. As for the ending statement everyone else just has a search ability meaning they can fill in a search filter, but can't read the search results. Now you can have multiple acls but the rule of the thumb is it processes from bottom up, so your toplevel should be the most restrictive ones.

5.  Working with OpenLDAP

Maintaining the directory

You can start using the directory to authenticate users in apache/proftpd/qmail/samba. You can manage it with Webmin, which provides an easy management interface. You can also use phpldapadmin, luma, diradm or lat.

6.  Acknowledgements

We would like to thank Matt Heler for lending us his box for the purpose of this guide. Thanks also go to the cool guys in #ldap @ irc.freenode.net

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.