Centralized authentication using OpenLDAP

From Gentoo Wiki
Jump to: navigation, search
This page contains changes which are not marked for translation.

Other languages:
English • ‎español • ‎français • ‎italiano • ‎日本語 • ‎한국어 • ‎русский • ‎中文 • ‎中文(中国大陆)‎

This guide introduces the basics of LDAP and shows you how to setup OpenLDAP for authentication purposes between a group of computers.

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

CODE Organisational structure for GenFic, a Fictional Gentoo company
dc:         com
dc:        genfic         ## (Organisation)
          /      \
ou:   People   servers    ## (Organisational Units)
      /    \     ..
uid: ..   John            ## (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) schemas, such as the inetOrgPerson, or a frequently used schema to define users which Unix/Linux boxes can use, called posixAccount. Note there are GUI web based tools to make managing LDAP painless: see Working with OpenLDAP for an non-exhaustive list.

Interested users are encouraged to read the OpenLDAP Admin Guide.

So... What can it be used for?

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)
  • Centralised Authentication (PosixAccount)
  • ...

OpenLDAP Server setup

Common notes

The domain genfic.org is an example in this guide. You will of course want to change this. However, make sure that the top node is an official top level domain (net, com, cc, be, ...).

Let's first emerge OpenLDAP. Ensure the USE flags berkdb, crypt, gnutls, ipv6, sasl, ssl, syslog, -minimal and tcpd are used.

root #emerge --ask openldap

OpenLDAP has a main user called "rootdn" (Root Distinguished Name), which is hardcoded in the application. Unlike the classic Unix root user, the rootdn user still needs to be assigned with proper permissions. The rootdn user may be used only in the context of the configuration, but it can also be used in the directory definition. In that case a user can authenticate himself as rootdn with either the configuration used password and the tree (directory-based) password.

User passwords (regardless if it is for rootdn users or others) for verification purposes can be stored as cleartext or hashed. Multiple different hash algorithms are available, but usage of weak algorythms (up to MD5) is not recommended. SHA is currently considered sufficiently cryptographically secure.

In the below command, a hashed value is created for a given password; the result of this command can be used in the slapd.conf configuration file, or in the internal directory definition of a user:

root #slappasswd
New password: my-password
Re-enter new password: my-password

For now (stable OpenLDAP 2.4.44) you probably should not need to use simple (username/password) mech, preferring SASL. In this case your ident description is provided by ldaphoami utility.

Legacy configuration (flat config slapd.conf)

Now edit the LDAP Server configuration in /etc/openldap/slapd.conf. The provided slapd.conf is from the original OpenLDAP source. Below is a sample configuration file one can use to replace it with to get things started.

FILE /etc/openldap/slapd.conf
include	/etc/openldap/schema/core.schema
include /etc/openldap/schema/cosine.schema
include /etc/openldap/schema/inetorgperson.schema
include /etc/openldap/schema/nis.schema
include	/etc/openldap/schema/misc.schema
pidfile  /var/run/openldap/slapd.pid
argsfile /var/run/openldap/slapd.args
## ## ServerID used in case of replication
serverID 0 
loglevel 0
## ## Certificate/SSL Section
TLSCipherSuite normal
TLSCACertificateFile /etc/openldap/ssl/ldap.crt
TLSCertificateFile /etc/openldap/ssl/ldap.pem
TLSCertificateKeyFile /etc/openldap/ssl/ldap.key
TLSVerifyClient never
## ## Access Controls
access to dn.base="" by * read
access to dn.base="cn=Subschema" by * read
access to *
  by self write
  by users read
  by anonymous read
## ## Database definition
database mdb
suffix "dc=genfic,dc=org"
checkpoint 32 30
maxsize 10485760
#Note: It is important to set this to as large a value as possible,
#(relative to anticipated growth of the actual data over time)
#since growing the size later may not be practical when the system is under heavy load.

rootdn "cn=Manager,dc=genfic,dc=org"
## ## rootpwd generated earlier via slappasswd command
rootpw "{SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4" 
directory "/var/lib/openldap-data"
index objectClass eq
## ## Synchronisation (pull from other LDAP server)
syncrepl rid=000
  retry="5 5 300 +"
index entryCSN eq
index entryUUID eq
mirrormode TRUE
overlay syncprov
syncprov-checkpoint 100 10

For a more detailed analysis of the configuration file, we suggest that you work through the OpenLDAP Administrator's Guide, although man 5 slapd.conf may be enough.

If it does not start, the first thing you must do is to check the config file. You can do it with the following command.

user $slaptest -v -d 1 -f /etc/openldap/slapd.conf

Vary the debug level (the "-d 1" above) for more info. If all goes well you will see config file testing succeeded. If there's an error, slaptest will list the line number to which it applies (of the slapd.conf file).

By default slapd write logs to LOCAL4 facility.

If you want to see in your common system log /var/log/messages something except slapd messages, you must either properly config slapd logging, or completely disable logs.
Note that since version 2.4.23, OpenLDAP default finally moved from traditional flat config files (slapd.conf) to OLC (OnLineConfiguration, also known through its cn=config structure) as default configuration method. One of benefits of using OLC is that the dynamic backend (cn=config) doesn't require restart of server after updating the configuration. Existing users can migrate to the new configuration method by invoking slaptest setting both -f and -F options. Traditionally OLC is stored in ldif back-end (which keep benefits of human-readability) in the /etc/openldap/slapd.d directory. In Gentoo it is not required to convert the configuration yet, but support for the currently documented approach will be removed in the future.

Migration from slapd.conf to OLC

If you want to be able to change OpenLDAP server's configuration, you must define at least write (or normally manage) access to cn=config.

The example below shows how to grant manage access to OLC (cn=config database) to the system administrator (root user) by adding the proper lines at the end of the slapd.conf file:

FILE /etc/openldap/slapd.confGranting root Linux account manage rights to cn=config
database config
access to *
        by dn.exact="gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth" manage
        by * none

slaptest utility, invoked with both -f and -F options will convert slapd.conf into ready to use (just take care about proper permissions) configuration directory (slapd.d).

root #mkdir /etc/openldap/slapd.d
root #slaptest -f /etc/openldap/slapd.conf -F /etc/openldap/slapd.d
root #chown -R ldap /etc/openldap/slapd.d

Running this command will transfer and translate the configuration. After that you are expected to update the configuration using specially prepared ldif files. And only if you aren't enough familiar with them, you can first edit slapd.conf and after that re-translate the slapd.conf into slapd.d/. Don't forget to check the directory's permissions.

For more instructions read the in-line comments of the generated files.

The below line will enable the slapd.d/ configuration method.

FILE /etc/conf.d/slapd
OPTS="-F /etc/openldap/slapd.d -h 'ldaps:// ldap:// ldapi://%2fvar%2frun%2fopenldap%2fslapd.sock'"

Finally, create the /var/lib/openldap-data structure:

To encrease database performance with default up to 2.4.39 bdb back-end you also need at least to copy /etc/openldap/DB_CONFIG.example into /var/lib/openldap-data/DB_CONFIG.

Here you need to load database dump:

root #slapadd -l data.ldif

When using legacy and planned to be removed BDB-backend it will be converted into numerous /var/lib/openldap-data/*bdb files. See man 5 slapd-bdb for details.

When using modern (default since 2.4.40) MDB-backend all data is stored into two files: /var/lib/openldap-data/data.mdb and /var/lib/openldap-data/lock.mdb. See man 5 slapd-mdb for details.

For MDB-backend you must set database size limit. For flat config — maxsize directive.
Providing separate common manual pages for flat config and OLC up to 2.4.44 upstream provides only legacy format docs for back-ends.

root #mkdir -p /var/lib/openldap-data
root #chown -R ldap:ldap /var/lib/openldap-data
root #chmod -R 0700 /var/lib/openldap-data

Start slapd:

root #/etc/init.d/slapd start

Initial setup with OLC

Initial config is shipped as standard LDAP database dump slapd.ldif.

It could be loaded (and only loaded, unlike ordinar LDAP database) by slapadd utility:

root #slapadd -d -1 -F /etc/openldap/slapd.d -n 0 -l /etc/openldap/config.ldif
Default config doesn't provide permissions to change server's configuration to anybody.

If you expect right to change configuration database, you must provide proper permissions (example giving these permissions for root system user without any additional confirmations from my production directory):

FILE config-access.ldif
# {0}config, config
dn: olcDatabase={0}config,cn=config
objectClass: olcDatabaseConfig
olcDatabase: {0}config
olcAccess: {0}to *  by dn.base="gidNumber=0+uidNumber=0,cn=peercred,cn=externa
 l,cn=auth" manage  by * none
olcAddContentAcl: TRUE
olcLastMod: TRUE
olcMaxDerefDepth: 15
olcReadOnly: FALSE
olcRootDN: cn=config
olcSyncUseSubentry: FALSE
olcMonitoring: FALSE

See man 5 slapd-config for details.

Using OLC you must NOT manually edit it's configs, so, probably it's impossible to get broken config directory.

But if you want, you may check it's consistancy with the following command:

root #slaptest -v -d 1 -F /etc/openldap/slapd.d

Server management with OLC

One of benefits of using OLC-style configuration is that you don't need to restart server to apply configuration update.
One of the features of commonly used by OLC LDIF-backend is that it doesn't allow file removing (and, possibly, file operations at all, including renaming). You can for example add overlay, but you can not remove it.

Some examples of updates on the OLC-style configuration are mentioned below.

For instance, to change the location of the OLC configuration directory (needed after translation config file to config directory):

FILE fix-configs.ldif
dn: cn=config
changetype: modify
delete: olcConfigFile
dn: cn=config
changetype: modify
replace: olcConfigDir
olcConfigDir: /etc/openldap/slapd.d

To change the log level used by the OpenLDAP instance:

FILE loglevel.ldif
dn: cn=config
changetype: modify
replace: olcLogLevel
olcLogLevel: stats stats2 sync

To add the syncprov overlay:

FILE add-syncprov-overlay.ldif
# Add indexes for replica to the frontend db.
dn: olcDatabase={1}mdb,cn=config
changetype: modify
add: olcDbIndex
olcDbIndex: entryCSN eq
add: olcDbIndex
olcDbIndex: entryUUID eq
# Load the syncprov module.
# Skip if included statically, see slapd -VVV output for details
dn: cn=module{0},cn=config
changetype: modify
add: olcModuleLoad
olcModuleLoad: syncprov
# syncrepl Provider for primary db
dn: olcOverlay=syncprov,olcDatabase={1}mdb,cn=config
changetype: add
objectClass: olcOverlayConfig
objectClass: olcSyncProvConfig
olcOverlay: syncprov
olcSpNoPresent: TRUE
olcSpCheckpoint: 100 10
olcSpSessionlog: 100

In order to apply the changes, run the following command:

root #ldapmodify -Y EXTERNAL -H ldapi:/// -f loglevel.ldif
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
modifying entry "cn=config"

OpenLDAP logging

OpenLDAP produce numerous logs, not very clear to read, but necessary for debug. So, we must describe this part.

It's rather important to repeat: if you want to have readable system logs, you must write slapd's log messages into dedicated log file, or disable it's logging at all.

To prevent DoS syslog daemons often limit amount of accepted messages from process in a period of time. For example with rsyslog:

FILE /var/log/messages
Feb  7 08:08:57 cons rsyslogd-2177: imuxsock begins to drop messages from pid 6750 due to rate-limiting
Feb  7 08:08:59 cons rsyslogd-2177: imuxsock lost 354 messages from pid 6750 due to rate-limiting

To be continued…

Access management (ACLs)

The next mandatory question is handling permissions on database's.

man 5 slapd.access:

Be warned: the rootdn can always read and write EVERYTHING!
      access to <what> [ by <who> [ <access> ] [ <control> ] ]+

Access level Privileges Description
none 0 no access
disclose d needed for information disclosure on error
auth dx needed to authenticate (bind)
compare cdx needed to compare
search scdx needed to apply search filters
read rscdx needed to read search results
add|delete} wrscdx needed to modify/rename
manage mwrscdx needed to manage

For details about exact privilege setting see manual pages and official docs.

Config file

ACLs are parsed, starting from the end of file, overriding previously set permissions.

For example:

FILE /etc/openldap/slapd.conf
access to attrs=userPassword
         by dn="cn=ldapreader,dc=genfic,dc=org" read
         by self read
         by anonymous auth
         by * none

access to dn.base="cn=Subschema" by users read
access to dn.base="" by * read

Means that first ACL allows everybody to read the tree.

Second ACL overrides permissions of the first ACL allowing access to subschemas for authenticated users.

Third ACL overrides permissions of previous ACLs limiting access to userPassword attribute, allowing authenticated user and replication user read it and anonymous auth. Remember, that rootdn could read and write everything.

Config directory

Access control is managed by enumerated olcAccess directives, similiarly starting from maximum number to the first (zero).

Example ldifs to add permissions, same with config, quoted above:

FILE add_acl.ldif
dn: olcDatabase={-1}frontend,cn=config
changetype: modify
add: olcAccess
olcAccess: {0}to dn.base="cn=subschema"  by users read
olcAccess: {1}to dn.base="" by * read

Insert ACL example:

FILE insert_acl.ldif
dn: olcDatabase={-1}frontend,cn=config
changetype: modify
add: olcAccess
olcAccess: {0}to attrs=userPassword  by dn="cn=ldapreader,dc=genfic,dc=org" read by self read by anonymous auth by * noneby * none

Numbers of all existing ACLs, starting from inserted one, grew on 1. 0 became 1, 1 becvae 2 and so long.

Delete ACL example:

FILE delete_acl.ldif
dn: olcDatabase={-1}frontend,cn=config
changetype: modify
delete: olcAccess
olcAccess: {1}

SASL authentication

Also mandatory for description, but not even planned yet.

Most common mech is EXTERNAL:

root #ldapmodify -Y EXTERNAL -H ldapi:/// -f set_slapd.loglevel.ldif
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
modifying entry "cn=config"

man 5 slapd-config:

      localSSF <SSF>
             Specifies  the  Security  Strength  Factor  (SSF)  to  be given local LDAP sessions, such as those to the ldapi://
             listener.  For a description of SSF values, see sasl-secprops's minssf option description.  The default is 71.

Primary develop/debug util — ldapwhoami.

Configuring the OpenLDAP Client tools

Edit the LDAP Client configuration file. This file is read by ldapsearch and other ldap command line tools.

FILE /etc/openldap/ldap.confAdd the following
BASE         dc=genfic, dc=org
URI          ldap://ldap.genfic.org:389/ ldap://ldap1.genfic.org:389/ ldap://ldap2.genfic.org:389/

You can test the running server with the following command:

user $ldapsearch -x -D "cn=Manager,dc=genfic,dc=org" -W

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

Client Configuration for Centralised Authentication

There are numerous methods/tools that can be used for remote authentication. Some distributions also have their own easy to use configuration tool. Below there are some in no particular order. It is possible to combine local users and centrally authorized accounts at the same time. This is important because, for instance, if the LDAP server cannot be accessed one can still login as root.

  • SSSD (Single Sign-on Services Daemon). Its primary function is to provide access to identity and authentication remote resource through a common framework that can provide caching and offline support to the system. It provides PAM and NSS modules, and in the future will support D-Bus interfaces for extended user information. It also provides a better database to store local users as well as extended user data.
  • Use pam_ldap to login to the LDAP server and authenticate. Passwords are not sent over the network in clear text.
  • NSLCD (Name Service Look up Daemon). Similar to SSSD, but older.
  • NSS (Name Service Switch) using the traditional pam_unix module to fetch password hashes over the network. To permit users to update their password this has to be combined with the pam_ldap method.

The first two are demonstrated below with the minimum necessary configuration options to get working.

Client PAM configuration SSSD Method

Here is the more direct method. The three files that are required to be edited are mentioned below.

FILE /etc/sssd/sssd.conf
config_file_version = 2
services = nss, pam
domains = genfic
debug_level = 5
filter_users = root,ldap,named,avahi,haldaemon,dbus,radiusd,news,nscd
id_provider = ldap
auth_provider = ldap
ldap_search_base = dc=genfic,dc=org
ldap_tls_reqcert = never
# primary and backup ldap servers below [first server and],[second server]
ldap_uri = ldap://X.X.X.X,ldap://X.X.X.X

Add sss to the end as shown below to enable the lookup to be handed to the sssd system service. Once you have finished editing start the sssd daemon.

FILE /etc/nsswitch.confExample nsswitch.conf with SSSD support
passwd:     files sss
shadow:     files sss
group:      files sss
netgroup:   files sss
automount:  files sss
sudoers:    files sss

The last file is the most critical. Open an extra root terminal as a fallback before editing this. The lines that end with # have been added to enable remote authentication. Note the use of pam_mkhomedir.so to support creating the user home directories.

FILE /etc/pam.d/system-authEnable pam_sss support
# This file is auto-generated.
# User changes will be destroyed the next time authconfig is run.
auth        required      pam_env.so
auth        sufficient    pam_unix.so nullok try_first_pass
auth        requisite     pam_succeed_if.so uid >= 500 quiet
auth        sufficient    pam_sss.so use_first_pass                                         #
auth        required      pam_deny.so
account     required      pam_unix.so
account     sufficient    pam_localuser.so
account     sufficient    pam_succeed_if.so uid < 500 quiet
account     [default=bad success=ok user_unknown=ignore] pam_sss.so                         #
account     required      pam_permit.so
password    requisite     pam_cracklib.so try_first_pass retry=3
password    sufficient    pam_unix.so md5 shadow nullok try_first_pass use_authtok
password    sufficient    pam_sss.so use_authtok                                            #
password    required      pam_deny.so
session     required      pam_mkhomedir.so skel=/etc/skel/ umask=0077
session     optional      pam_keyinit.so revoke
session     required      pam_limits.so
session     [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid
session     required      pam_unix.so
session     optional      pam_sss.so                                                        #

Now try logging in from another box.

Client PAM configuration the pam_ldap Module Method

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

root #emerge --ask pam_ldap nss_ldap

The last file is the most critical. Open a few extra root terminals as a backup before editing this. The lines that end with # have been added to enable remote authentication.

FILE /etc/pam.d/system-auth
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:

FILE /etc/ldap.conf
## #host
## #base dc=padl,dc=com
base dc=genfic,dc=org
## #rootbinddn uid=root,ou=People,dc=genfic,dc=org
bind_policy soft
bind_timelimit 2
ldap_version 3
nss_base_group ou=Group,dc=genfic,dc=org
nss_base_hosts ou=Hosts,dc=genfic,dc=org
nss_base_passwd ou=People,dc=genfic,dc=org
nss_base_shadow ou=People,dc=genfic,dc=org
pam_filter objectclass=posixAccount
pam_login_attribute uid
pam_member_attribute memberuid
pam_password exop
scope one
timelimit 2
uri ldap://ldap.genfic.org/ ldap://ldap1.genfic.org ldap://ldap2.genfic.org

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

root #scp ldap-server:/etc/openldap/ldap.conf /etc/openldap

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

FILE /etc/nsswitch.conf
passwd:         files ldap
group:          files ldap
shadow:         files ldap

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 you might want to do is keep that file blank and when you need to change someone's password that's both in the LDAP and /etc/passwd, put the pass in there for 10 seconds while changing the users password and remove it when done.

Migrate existing data to LDAP

Configuring OpenLDAP for centralized administration and management of common Linux/Unix items isn't easy, but thanks to some tools and scripts available on the Internet, migrating a system from a single-system administrative point-of-view towards an OpenLDAP-based, centralized managed system isn't hard either.

Go to http://www.padl.com/OSS/MigrationTools.html and fetch the scripts there. You'll need the migration tools and the make_master.sh script.

Next, extract the tools and copy the make_master.sh script inside the extracted location:

root #mktemp -d
root #cd /tmp/tmp.zchomocO3Q
root #tar xvzf /path/to/MigrationTools.tgz
root #mv /path/to/make_master.sh MigrationTools-47
root #cd MigrationTools-47</pre>

The next step now is to migrate the information of your system to OpenLDAP. The make_master.sh script will do this for you, after you have provided it with the information regarding your LDAP structure and environment.

At the time of writing, the tools require the following input:

Input Description Example
LDAP BaseDN The base location (root) of your tree dc=genfic,dc=org
Mail domain Domain used in e-mail addresses genfic.org
Mail host FQDN of your mail server infrastructure smtp.genfic.org
LDAP Root DN Administrative account information for your LDAP structure cn=Manager,dc=genfic,dc=org
LDAP Root Password Password for the administrative account, cfr earlier slappasswd command

The tool will also ask you which accounts and settings you want to migrate.

You don't need to make changes to pam.d/system-auth


High availability

To setup replication of changes across multiple LDAP systems. Replication within OpenLDAP is, in this guide, set up using a specific replication account ( ldapreader ) which has read rights on the primary LDAP server and which pulls in changes from the primary LDAP server to the secondary.

This setup is then mirrored, allowing the secondary LDAP server to act as a primary. Thanks to OpenLDAP's internal structure, changes are not re-applied if they are already in the LDAP structure.

Setting Up Replication

To setup replication, first setup a second OpenLDAP server, similarly as above. However take care that, in the configuration file:

  • The sync replication provider is pointing to the other system
  • The serverID of each OpenLDAP system is different
Using a mirrored installation means that the OpenLDAP service should be configured like a single server installation, so the serverID value on each of the nodes must be the same. Instances are identified by rid values, which must be unique.

Next, create the synchronisation account. We will create an LDIF file (the format used as data input for LDAP servers) and add it to each LDAP server:

user $slappasswd -s myreaderpassword
user $cat ldapreader.ldif
dn: cn=ldapreader,dc=genfic,dc=org
userPassword: {SSHA}XvbdAv6rdskp9HgFaFL9YhGkJH3HSkiM
objectClass: organizationalRole
objectClass: simpleSecurityObject
cn: ldapreader
description: LDAP reader used for synchronization
user $ldapadd -x -W -D "cn=Manager,dc=genfic,dc=org" -f ldapreader.ldif
Password: ## enter the administrative password

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:

FILE /etc/openldap/slapd.conf
access to attrs=userPassword,gecos,description,loginShell
  by self write
access to *
  by dn="uid=root,ou=People,dc=genfic,dc=org" write
  by users read
  by anonymous auth

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:

FILE /etc/openldap/slapd.conf
access to attrs="userPassword"
  by dn="uid=root,ou=People,dc=genfic,dc=org" write
  by dn="uid=John,ou=People,dc=genfic,dc=org" write
  by anonymous auth
  by self write
  by * none
access to *
  by dn="uid=root,ou=People,dc=genfic,dc=org" write
  by dn="uid=John,ou=People,dc=genfic,dc=org" write
  by * search

This example gives root and John access to read/write/search for everything in the the tree below dc=genfic,dc=org. 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 one.

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 LAM (Ldap Account Manager), phpldapadmin, diradm, jxplorer, or lat, which provide easy management interfaces.


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
This article is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Benjamin Coles, swift, Brandon Hale, Benny Chuang, jokey, nightmorph
They are listed here as the Wiki history does not allow for any external attribution. If you edit the Wiki article, please do not add yourself here; your contributions are recorded on the history page.