CentOS Installation Guide

We will now take you through the installation of an OpenLDAP server on our CentOS host. The binaries are available from the CentOS repositories, and you can install them via the yum command or via the Package Manager GUI. We will install them via the yum command as follows:

$ sudo yum install openldap openldap-clients openldap-servers

This installs the necessary files for configuring, running, and managing the LDAP server. The openldap package installs the base packages required to allow the host to integrate with the OpenLDAP server. The openldap-clients package installs the tools to manage and query the LDAP server. The openldap-servers package installs the necessary files to run an OpenLDAP server.

Ubuntu Installation Guide

To install OpenLDAP on an Ubuntu host, we require the ldap-utils package and the slapd package to be installed. The following command will install these packages:

$ sudo aptitude install ldap-utils slapd

When you issue this command, the slapd package will ask you to provide a password for your root LDAP user. You can enter your password and proceed with the installation. If you do not want to supply one, you can just press the Enter key twice (we will show you how to create a password in the upcoming “Configuration” section). Once installed, the ldap-utils package will install the files needed to manage and search your LDAP directory. The slapd package installs the necessary files to run and configure your LDAP directory.

The client configuration packages are auth-client-config (PAM and NSS profile switcher) and ldap-auth-client (metapackage for LDAP authentication along with ldap-auth-config). You may want to install these too.

Requirements

Prior to configuring OpenLDAP we are going to set up a few requirements. We need to create a TLS certificate and key and a DNS name entry.

The first step is to create the DNS record. Authentication systems like LDAP are not normally exposed to the public and if they are they can be subjected to external attacks. For this reason we would not normally provide a public IP address. For your external offices that need to authenticate against the service we recommend you use the private VPN for access.

This OpenLDAP service is going to be installed on our headoffice.example.com host. We are going to provide our DNS server with the CNAME record to point ldap.example.com to headoffice.example.com. We need to be on our DNS server and issue the following command:

$ sudo nsupdate -k /etc/bind/ddns_update.key
> server localhost
> update add ldap.example.com 8600 CNAME headoffice.example.com
> send
> quit
$ host ldap.example.com
ldap.example.com is an alias for headoffice.example.com.
headoffice.example.com has address 192.168.0.1

Since this points to an internal private IPv4 address, we will not be able to use Let’s Encrypt to create our TLS certificate and will have to use our own private CA. Clients that connect to our LDAP server will need to have the CA root certificate installed.

First, create a new directory called /etc/ldap/certs and then change the permissions on it.

$ sudo mkdir /etc/ldap/certs

We will create the key and the CSR on our ldap.example.com host and run the following from inside the /etc/ldap/certs directory:

$ sudo openssl req -new -newkey rsa:4096 -nodes -keyout
ldap.example.com.key -out ldap.example.com.req

Go ahead and sign the request like we did in Chapters 11 and 15 by our private CA. We then need to add the public cert that is produced to the /etc/ssl/certs directory along with the root CA if it is not already there, cacert.pem.

When the certificates are installed into the certs directory , we should change the ownership and permissions to the following:

$ sudo chown openldap:openldap –R /etc/ldap/certs
$ sudo chmod 600 /etc/ldap/certs/ldap.example.com.key

The user running the LDAP service on CentOS is ldap and would need to be used in the previous chown command.

Configuring SLAPD

With the requirements in place, we can now get on to configuring our OpenLDAP server. When we installed our slapd packages and were asked for the administrator password on Ubuntu, the basic OpenLDAP server was configured, installed, and started (on CentOS you will have to start the slapd service prior to running this command).

In Listing 16-1 we have the output of the ldapsearch command. This command is part of the suite of commands used to interact with the LDAP server (or any LDAP server). In this example, we have passed in the –Q argument to ldapsearch to enable SASL quiet mode (as we are using elevated sudo privileges). The three Ls (-LLL) all have a meaning. Having one means print in the LDIF format; the other two reduce the output. The –H argument is the URI we want to attach to, ldapi:///, which is saying, connect to local LDAP server via the Unix socket on the local host. With this we can pass the UID and GID of the user to the LDAP server for authentication. Next, -b defines the search base; we are searching in the cn=config DIT for each dn (or distinguished name) by using dn as a filter.

Listing 16-1. Viewing the Default Configuration

$ sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn
dn: cn=config
dn: cn=module{0},cn=config
dn: cn=schema,cn=config
dn: cn={0}core,cn=schema,cn=config
dn: cn={1}cosine,cn=schema,cn=config
dn: cn={2}nis,cn=schema,cn=config
dn: cn={3}inetorgperson,cn=schema,cn=config
dn: olcBackend={0}mdb,cn=config
dn: olcDatabase={-1}frontend,cn=config
dn: olcDatabase={0}config,cn=config
dn: olcDatabase={1}mdb,cn=config

In Listing 16-1 you can also see we have passed the –Y option. This specifies the SASL authentication mechanism we want to use. EXTERNAL here says use the localhost’s authentication in this case. We pass the root user’s UID and GID via the Unix socket to LDAP for authentication. The default installation allows local root access to the installed LDAP server.

dn: <the distinguished name you wish to change>
changetype: optional change type of either add, replace, or delete
<attribute or objectclass>: value

dn: dc=example,dc=com
objectclass: dcObject
objectclass: organizationalUnit
dc: example
ou: example

dn: uid=ffrank,ou=people,dc=example,dc=com
changetype: replace
replace: userPassword
userPassword: <new password>
-

Then in Listing 16-1 we have the list of global directive DNs that are in the cn=config global configuration DIT. You can see that the global DIT is comprised of the root cn=config, and then the DNs are nested under that, like in Figure 16-3.

Figure 16-3. cn=config DIT

You can see from Listing 16-1 and Figure 16-3 that the LDAP schema, cn={1}cosine,cn=schema,cn=config, is found under the cn=schema DN, which is found under cn=config. The {1} denotes an index of the schema DN .

Also, in Listing 16-1 there are several other global directives like olcBackend and olcDatabase. These, as their names imply, describe the back-end data storage.

dn: olcBackend={0}mdb,cn=config
dn: olcDatabase={-1}frontend,cn=config
dn: olcDatabase={0}config,cn=config
dn: olcDatabase={1}mdb,cn=config

To get a full listing, or a backup, of the cn=config DIT, you can issue the following command:

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=config > slapd.ldif

We have used the same command as previously but have removed the dn filter from the end and directed the output to the slapd.ldif file. If you look at that file, you will see how the directives have been configured.

Looking at the first declaration, we have the DN for cn=config. It has an ObjectClass of olcGlobal, which is the object class that defines the global DIT. You can also see that we can declare the common name (cn:), an arguments file for slapd (olcArgsFile:), log level (olcLogLevel:), process ID (olcPidFile:), and threads to use (olcToolThreads:).

The olcToolThreads directive tells the slapd daemon to use only one CPU to run indexes on. If you have more than one CPU, you can set this to a higher number, but not higher than the number of CPUs you have. Other performance settings can be turned on, including olcThreads, olcTimeLimits, olcSockBuffMaxIncoming, and olcSockBuffMinIncoming.

Every time you declare a DN you will need to provide the object class (or classes) it belongs to. That object class will have attributes it takes. So, the olcGlobal object class has the olcArgsFile as an attribute, and this will be described in the schema file .

dn: cn=config
changetype: modify
replace: olcLogLevel
olcLogLevel: 480

$ sudo ldapmodify -Q -Y EXTERNAL -H ldapi:/// -f loglevel.ldif

$ sudo ldapsearch –Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=config cn=config
dn: cn=config
objectClass: olcGlobal
cn: config
olcArgsFile: /var/run/slapd/slapd.args
olcPidFile: /var/run/slapd/slapd.pid
olcToolThreads: 1
olcLogLevel: 480

dn: cn=module{0},cn=config
objectClass: olcModuleList
cn: module{0}
olcModulePath: /usr/lib/ldap
olcModuleLoad: {0}back_mdb

$ ll /usr/lib/ldap/pp*
-rw-r--r-- 1 root root 39328 May 11 17:11 /usr/lib/ldap/ppolicy-2.4.so.2.10.5
-rw-r--r-- 1 root root   948 May 11 17:11 /usr/lib/ldap/ppolicy.la

dn: cn=module{0},cn=config
changetype: modify
add: olcModuleLoad
olcModuleLoad: ppolicy.la

$ sudo ldapsearch -H ldapi:// -Y EXTERNAL -b "cn=config" -LLL -Q "objectClass=olcModuleList"
dn: cn=module{0},cn=config
objectClass: olcModuleList
cn: module{0}
olcModulePath: /usr/lib/ldap
olcModuleLoad: {0}back_mdb
olcModuleLoad: {1}ppolicy.la

$ sudo ldapsearch -H ldapi:/// -Y EXTERNAL -b "olcDatabase={1}mdb,cn=config" -LLL  -Q
dn: olcDatabase={1}mdb,cn=config
objectClass: olcDatabaseConfig
objectClass: olcMdbConfig
olcDatabase: {1}mdb
olcDbDirectory: /var/lib/ldap
olcAccess: {0}to attrs=userPassword by self write by anonymous auth by * none
olcAccess: {1}to attrs=shadowLastChange by self write by * read
olcAccess: {2}to * by * read
olcLastMod: TRUE
olcDbCheckpoint: 512 30
olcDbIndex: objectClass eq
olcDbIndex: cn,uid eq
olcDbIndex: uidNumber,gidNumber eq
olcDbIndex: member,memberUid eq
olcDbMaxSize: 1073741824
olcSuffix: dc=nodomain
olcRootDN: cn=admin,dc=nodomain
olcRootPW: {SSHA}EEyEuYme4zBPYbRzHc+l4rApfvrXjXnV

dn: olcDatabase={1}mdb,cn=config
changetype: modify
replace: olcSuffix
olcSuffix: dc=example,dc=com
-
replace: olcRootDN
olcRootDN: cn=admin,dc=example,dc=com
-
replace: olcRootPW
olcRootPW: {SSHA}QN+NZNjLxIsG/+PGDvb/6Yg3qX2SsX95

$ sudo slappasswd

$ sudo ldapsearch -H ldapi:/// -Y EXTERNAL -b "olcDatabase={1}mdb,cn=config" -LLL –Q olcDbIndex
olcDbIndex: objectClass eq
olcDbIndex: cn,uid eq
olcDbIndex: uidNumber,gidNumber eq
olcDbIndex: member,memberUid eq

add: olcDbIndex
olcDbIndex: exampleActive pres,eq

$ sudo ldapmodify -Q -Y EXTERNAL -H ldapi:/// -f db.ldif

Listing, Adding, and Creating a Schema

A schema provides the structure of your object’s classes and attributes to the SLAPD server. While not the same as a database schema, the LDAP schema describes the object classes and attributes your LDAP server will hold, much like a database schema would describe tables and rows. You can view the currently loaded schemata with the following ldapsearch:

$ sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=schema,cn=config dn
dn: cn=schema,cn=config
dn: cn={0}core,cn=schema,cn=config
dn: cn={1}cosine,cn=schema,cn=config
dn: cn={2}nis,cn=schema,cn=config
dn: cn={3}inetorgperson,cn=schema,cn=config

The top dn is cn=schema,cn=config, and that is the parent of our schemata. We then have some default schemata that are provided by our installation. The core schema provides such object classes as the dcObject (dc) and organizationalUnit (ou). The cosine schema provides the dNSDomain object class and host attribute. The nis schema provides user account objects and attributes, such as posixAccount and shadow password settings. The inetorgperson holds other various employee-related objects and classes. You may or may not use objects and attributes that these provide.

To see all the schemata available to you, you can list the /etc/ldap/schema directory. For example, we can see that in that directory the ppolicy.schema and ppolicy.ldif files for the ppolicy schema are present.

$ ls /etc/ldap/schema/pp*
/etc/ldap/schema/ppolicy.ldif  /etc/ldap/schema/ppolicy.schema

The ppolicy.ldif file has been derived from the ppolicy.schema file for us. We are going to add our ppolicy.ldif schema to our SLAPD. We do that by using the ldapadd command. It takes similar arguments to ldapsearch and ldapmodify.

$ sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/ppolicy.ldif
adding new entry "cn=ppolicy,cn=schema,cn=config"

Let’s see if that has been loaded.

$ sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=schema,cn=config dn
dn: cn=schema,cn=config
dn: cn={0}core,cn=schema,cn=config
dn: cn={1}cosine,cn=schema,cn=config
dn: cn={2}nis,cn=schema,cn=config
dn: cn={3}inetorgperson,cn=schema,cn=config
dn: cn={4}ppolicy,cn=schema,cn=config

There you can see that our ppolicy schema has been added at index {4}. Remember that index number as we are going to need it when we add our own schema. Let’s see how we create and add our own schema.

objectclass ( 1.3.6.1.4.1.1466.344 NAME 'dcObject'
        DESC 'RFC2247: domain component object'
        SUP top AUXILIARY MUST dc )

objectclass ( <OID> NAME <name> DESC <description> SUP <parent class> <class type> <MUST|MAY> attritubutes )

# $Id$

attributetype ( 1.1.3.10 NAME 'exampleActive'
DESC 'Example User Active'
SINGLE-VALUE
EQUALITY booleanMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.7)

objectclass ( 1.1.1.2 NAME 'exampleClient'
SUP top AUXILIARY
DESC 'Example.com User objectclass'
MAY ( exampleActive ))

attributetype ( 1.3.6.1.4.1.111111.3.1.1 NAME 'exampleActive'
DESC 'Example User Active'
SINGLE-VALUE
EQUALITY booleanMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 )

objectclass ( 1.3.6.1.4.1.111111.3.2.1 NAME 'exampleClient' SUP top AUXILIARY DESC
'Example.com User objectclass'
MAY ( exampleActive ))

olcDbIndex: exampleActive pres,eq

$ sudo mkdir /etc/ldap/ldif_converted && cd /etc/ldap

include /etc/ldap/schema/exampleactive.schema

$ sudo slaptest –f schema_load.conf –F ldif_converted

 /etc/ldap/ldif_converted/cn=config/cn=schema/cn={0}exampleactive.ldif

58180fbb schema/exampleactive.schema: line 1 attributetype: Missing closing parenthesis before end of input

attributetype ( attribute detail )

objectclass ( object detail )

# AUTO-GENERATED FILE - DO NOT EDIT!! Use ldapmodify.                    
# CRC32 39f1bf5a                    
dn: cn={0}exampleactive
objectClass: olcSchemaConfig
cn: {0}exampleactive
olcAttributeTypes: {0}( 1.3.6.1.4.1.111111.3.1.1 NAME 'exampleActive' DESC '
 Example User Active' EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.
 1.7 SINGLE-VALUE )
olcObjectClasses: {0}( 1.3.6.1.4.1.111111.3.2.1 NAME 'exampleClient' DESC 'E
 xample.com User objectclass' SUP top AUXILIARY MAY exampleActive )
structuralObjectClass: olcSchemaConfig                    
entryUUID: 53a98d60-3432-1036-9ae2-35c34321a848                    
creatorsName: cn=config                    
createTimestamp: 20161101035217Z                    
entryCSN: 20161101035217.399551Z#000000#000#000000                    
modifiersName: cn=config                    
modifyTimestamp: 20161101035217Z                    

dn: cn={0}exampleactive

dn: cn={5}exampleactive

$ sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f schema/exampleactive.ldif
adding new entry "cn={5}exampleactive,cn=schema,cn=config"

Access Control Lists

Every connection that accesses your LDAP server has to be given specific access to various parts of the tree if you want it to be secure. The default access for OpenLDAP is read, and you will want to lock this down if you store secret such as passwords. You can specify from where you accept connections, the level of security, or the encryption that connection must have to gain access, right down to the branch or attribute that you allow access to. You also have several levels of access that you can then grant to the requesting connection: manage, write, read, search, and auth.

$ sudo ldapsearch -H ldapi:/// -Y EXTERNAL -b "olcDatabase={1}mdb,cn=config" -LLL  -Q
dn: olcDatabase={1}mdb,cn=config
objectClass: olcDatabaseConfig
objectClass: olcMdbConfig
olcDatabase: {1}mdb
olcDbDirectory: /var/lib/ldap
olcSuffix: dc=example,dc=com
olcAccess: {0}to attrs=userPassword by self write by anonymous auth by * none                    
olcAccess: {1}to attrs=shadowLastChange by self write by * read                    
olcAccess: {2}to * by * read                    
olcLastMod: TRUE
...

(access) to attrs=userPassword                    
    by self write              
    by anonymous auth              
    by * none              

[access|{n}]to what [ by who [ access-level ] [ control ] ]

to *
   by * read stop

to dn.subtree=ou=people,dc=example,dc=com
   by dn.exact="cn=admin,ou=meta,dc=example,dc=com" read

dn.base
dn.one
dn.subtree
dn.children

0: dc=example,dc=com
1: cn=Manager,dc=example,dc=com
2: ou=people,dc=example,dc=com
3: uid=jsmith,ou=people,dc=example,dc=com
4: cn=addresses,uid=jsmith,ou=people,dc=example,dc=com
5: uid=ataylor,ou=people,dc=example,dc=com

dn.base="ou=people,dc=example,dc=com" match 2;
dn.one="ou=people,dc=example,dc=com" match 3, and 5;                      
dn.subtree="ou=people,dc=example,dc=com" match 2, 3, 4, and 5; and                      
dn.children="ou=people,dc=example,dc=com" match 3, 4, and 5.

to dn.subtree="ou=people,dc=example,dc=com" attrs="userPassword"
   by dn.exact="cn=admin,ou=meta,dc=example,dc=com" write
   by * none

to *
     by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth manage
     by * break

olcAccess: {1}to attrs=userPassword,shadowLastChange,entry,member
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" tls_ssf=128 auth
        by anonymous tls_ssf=128 auth
        by group.exact="cn=admins,ou=groups,dc=example,dc=com" tls_ssf=128 write
        by self tls_ssf=128 write
        by * tls_ssf=128 search
        by * none stop

by * none stop

to dn.children="ou=meta,dc=example,dc=com"
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" read
        by group.exact="cn=admins,ou=groups,dc=example,dc=com" write
        by self read

to dn.children="ou=people,dc=example,dc=com"
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" read
        by group.exact="cn=admins,ou=groups,dc=example,dc=com" write
        by self write
        by users read

to dn.children="ou=groups,dc=example,dc=com"
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" read
        by group.exact="cn=admins,ou=groups,dc=example,dc=com" write
        by anonymous read

to dn.children="ou=hosts,dc=example.com"
        by group.exact="cn=admins,ou=groups,dc=example,dc=com" write
        by anonymous read

to * by * none stop

dn: olcDatabase={1}mdb,cn=config
changetype: modify
replace: olcAccess
olcAccess: {0}to *
        by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth manage
        by * break
-
add: olcAccess
olcAccess: {1}to attrs=userPassword,shadowLastChange,entry,member
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" tls_ssf=128 auth
        by anonymous tls_ssf=128 auth
        by group.exact="cn=admins,ou=groups,dc=example,dc=com" tls_ssf=128 write
        by self tls_ssf=128 write
        by * tls_ssf=128 search
        by * none stop
-
add: olcAccess
olcAccess: {2}to dn.children="ou=meta,dc=example,dc=com"
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" read
        by group.exact="cn=admins,ou=groups,dc=example,dc=com" write
        by self read
-
add: olcAccess
olcAccess: {3}to dn.children="ou=people,dc=example,dc=com"
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" read
        by group.exact="cn=admins,ou=groups,dc=example,dc=com" write
        by self write
        by users read
-
add: olcAccess
olcAccess: {4}to dn.children="ou=groups,dc=example,dc=com"
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" read
        by group.exact="cn=admins,ou=groups,dc=example,
dc=com" write
        by anonymous read
-
add: olcAccess
olcAccess: {5}to dn.children="ou=hosts,dc=example.com"
        by group.exact="cn=admins,ou=groups,dc=example,dc=com" write
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" search
-
add: olcAccess
olcAccess: {6}to * by * none

dn: olcDatabase={1}mdb,cn=config
changetype: modify
replace: olcAccess
olcAccess: {0}<access list>
-
add: olcAccess
olcAccess: {1}<access list>

$ sudo ldapmodify -H ldapi:/// -Y EXTERNAL  -f access.ldif

Working with the slapd Daemon

You can run your slapd daemon in two ways: with the slapd.d configuration engine (dynamic configuration) or without it. As mentioned previously, the configuration engine enables the SLAPD configuration to be changed on the fly using LDIF syntax and LDAP commands.

The other way is to load in a slapd.conf file that has the older style directives. We saw an example of the slapd.conf syntax when we included our exampleactive.schema file to convert it to LDIF format.

Both ways are supported, but running with the old-style slapd.conf will be deprecated, so we don’t recommend starting slapd with it. You can convert your old-style slapd.conf into the dynamic LDIF configuration engine by issuing the following command (SLAPD cannot be already running):

$ sudo slapd -f slapd.conf -F slapd.d -u openldap -g openldap

This is similar to our slaptest command we ran previously. You will notice that this is being run in the foreground, and you can see whether there are any problems when it tries to start. For CentOS hosts, you would use -u ldap -g ldap for the user that runs OpenLDAP instead of -u openldap, which is for Ubuntu hosts. Then -f slapd.conf points to the configuration file we want to read in, and -F points to the slapd.d directory, which will hold the LDIF files for your configuration engine.

When your slapd instance starts, you will see that the slapd.d directory now contains several files and directories. These files contain the LDAP settings you have specified in slapd.conf and other included files in an LDIF file format.

For troubleshooting, it can often be useful to run the SLAPD daemon in debug mode in the foreground to see exactly what the service is doing. To do that, you would issue the following (on Ubuntu, use –u ldap and –g ldap for CentOS):

$ sudo slapd -F /etc/ldap/slapd.d -d -1 -u openldap -g openldap -h ldapi:///

You can manually start or stop an SLAPD server service using the following on either CentOS or Ubuntu:

$ sudo systemctl start slapd
$ sudo systemctl stop slapd

You can then check the status of the daemon with the following:

$ sudo systemctl status slapd

You can enable at boot with the following:

$ sudo systemctl enable slapd

Once the service is started, you can tail the journal logs to see any logging information.

$ sudo journalctl -xfe -u slapd

You can use the logs to monitor and solve problems with your access requests.

dn: cn=config
changetype: modify
add: olcTLSCACertificateFile
olcTLSCACertificateFile: /etc/ldap/certs/cacert.pem
-
add: olcTLSCertificateFile
olcTLSCertificateFile: /etc/ldap/certs/ldap.example.com.cert
-
add: olcTLSCertificateKeyFile
olcTLSCertificateKeyFile: /etc/ldap/certs/ldap.example.com.key
-
add: olcTLSVerifyClient
olcTLSVerifyClient: allow

$ sudo ldapmodify -Q -Y EXTERNAL -H ldapi:/// -f tls.ldif

$ sudo ldapsearch -H ldapi:/// -Y EXTERNAL -b "cn=config" -LLL  -Q |grep TLS
olcTLSCACertificateFile: /etc/ldap/certs/cacert.pem
olcTLSCertificateFile: /etc/ldap/certs/ldap.example.com.cert
olcTLSCertificateKeyFile: /etc/ldap/certs/ldap.example.com.key

dn: cn=config
changetype: modify
add: olcSecurity
olcSecurity: ssf=128 update_ssf=256 simple_bind=128 tls=256

Setting Up Your LDAP Client

Ubuntu and CentOS both use the ldap.conf file to configure system-wide LDAP defaults for clients (there is also another method using the sssd program that we will discuss in the “Single Sign-On: Centralized Linux Authentication” section). Applications that use the OpenLDAP libraries will use these files to get the LDAP details. You will find Ubuntu’s file in the directory /etc/ldap and CentOS’s in /etc/openldap.

You will need to edit your ldap.conf file by adding the following lines of text. In our case, we are going to cheat a little and not worry about setting up client SSL certificates for our LDAP clients. If this host was being used to replicate our LDAP server, we would definitely ensure that both the server and client had SSL verification enabled. Check the man page for ldap.conf for details.

URI ldap://ldap.example.com/
BASE dc=example,dc=com
TLS_CACERT /etc/ldap/certs/cacert.pem
TLS_REQCERT demand

The URI points to our LDAP server. The BASE is the default base DN for LDAP operations. TLS_CACERT points to our CA certificate file, which will contain our example.com CA certificate. On some clients you may have installed the CA cert into the default location of /etc/ssl/certs. The demand we specify in the TLS_REQCERT field means that we will try to verify the certificate, and if it cannot be verified, we cancel the connection (this is the default). Other options are try, which means the connection will continue if no certificate is provided, but if a bad certificate is provided, the connection is stopped immediately; allow, which means that if the certificate provided is bad, the session can continue anyway; and never, which means your host will not request or check the server certificate before establishing the connection.

If you were looking at a CentOS host, you would most likely find your SSL CA certificate in the /etc/pki/tls/certs directory.

LDIFs and Adding Users

At the top of the DIT sits the rootDN. The DIT starts with the declaration of the dcObject class. The following is a snippet of the LDIF text file we will use to populate our LDAP server:

dn: dc=example,dc=com
objectclass: dcObject
objectClass: organization
dc: example
o: example

This declares that we are going to create the rootDN dc=example,dc=com. According to the dcObject object class in the core.schema on Ubuntu, we must include the dc attribute. Let’s look at the object class declaration from the core.schema file:

objectclass ( 1.3.6.1.4.1.1466.344 NAME 'dcObject'
         DESC 'RFC2247: domain component object'
         SUP top AUXILIARY MUST dc )

You can see how we use the preceding object class in the declaration of the DN: dc=example, dc=com. We specify the dc attribute as we are directed to use, indicated by the MUST clause in the object definition. Remember, this is an AUXILLARY object class and cannot be used to create an entry. We need a STRUCTUAL object class, and organization is such a class. It requires the o attribute for organization. We will add this entry when we add our users in the next section. This should be the first entry you add to your LDAP server.

It should be noted here that depending on if you are using Ubuntu, rootDN may already exist. You can find out by running the following:

$ sudo ldapsearch -D "cn=admin,dc=example,dc=com" -b "dc=example,dc=com" –ZZ -H ldap://ldap.example.com –W
# example.com
dn: dc=example,dc=com
objectClass: top
objectClass: dcObject
objectClass: organization
o: example
dc: example

If this is the case, do not include this in users.ldif or you will get an error like the following when you try to add it:

adding new entry "dc=example,dc=com"
ldap_add: Already exists (68)

Next, we want to set up the users in our organization, so we will now declare our people organizational unit. We could separate this section into a new file for just our people entries if we wanted.

dn: ou=people,dc=example,dc=com
objectclass: organizationalUnit
ou: people

You can see that the LDIF format requires the declaration of the DN, followed by the object classes we want to use and the attributes. Each declaration should be separated by a blank line. The order of declaration is also important; you can’t create a user in ou=people,dc=example,dc=com until that organizational unit is created. The object class organizationalUnit requires that we declare the ou attribute as we have here, ou: people.

Now we are going to add a user, jsmith.

dn: uid=jsmith,ou=people,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: posixAccount
objectclass: exampleClient
cn: Jane Smith
sn: Smith
uid: jsmith
uidNumber: 1000
gidNumber: 1000
exampleActive: TRUE
homeDirectory: /home/jsmith
userPassword: {SSHA}IZ6u7bmw12t345s3GajRt4D4YHkDScH8

So, let’s look at the DN first. You can see that we declare our DN using the uid attribute. We could have used a couple variations here other than uid=jsmith: cn=Jane Smith or [email protected]. Which of these you end up using on your system depends on what you think will be best for your server (keeping indexes in mind), and you should be aware that these must be unique (SINGLE-VALUE).

Next, we have to declare the object class top and person. The top object class, an ABSTRACT superclass, is required to provide the other object classes and is used to terminate the hierarchy.

The person object class provides the sn (surname) and cn (common name) attributes. Let’s quickly view the schema for this object class.

objectclass ( 2.5.6.6 NAME 'person'
        DESC 'RFC2256: a person'
        SUP top STRUCTURAL
        MUST ( sn $ cn )
        MAY ( userPassword $ telephoneNumber $ seeAlso $ description ) )

The parent of the person object class is top (SUP top), and it is a STRUCTURAL object class, meaning that its attributes can form an entry in the DIT. For the person class, we MUST provide a cn and an sn entry. We MAY provide userPassword, telephone, seeAlso, and description.

It is optional to include the posixAccount and exampleClient object classes. The object class posixAccount will provide the attributes useful for Unix/Linux hosts such as userPassword, uid, uidNumber, gidNumber, and homeDirectory. The exampleClient object class that we created in the schema section provides the exampleActive attribute, which we can use to activate and deactivate our users. Please note that the attribute value for Boolean attributes such as exampleActive must be uppercase, and because it is an SINGLE-VALUE attribute, we can declare it only once.

We’ll now add groups as an organizationalUnit so that we can make use of groups to manage access to our users. Again, we can create a new LDIF text file for our groups.

dn: ou=groups,dc=example,dc=com
objectclass: top
objectclass: organizationalUnit
ou: groups

You can see that creating the organizational unit for groups is similar to the way we declared the people organizational unit earlier. As required by the schema definition, we have used and declared the ou attribute to name our DN. Next, we declare the group admins that we will use to group our administrators.

dn: cn=admins,ou=groups,dc=example,dc=com
objectclass: top
objectclass: groupOfNames
cn: admins
member: uid=ataylor,ou=people,dc=example,dc=com

We declare a group list with the groupOfNames object class, which allows us to just add members. We could have also used the posixGroup object class, which would allow us to use gidNumbers as well. We can add as many members to the group as we like by adding member: DN on a separate line.

Now we can look at adding our details to the LDAP database. To do so, we will use the ldapadd tool that comes with OpenLDAP.

Adding Users from LDIF Files

The LDAP tools all share a common set of options that you can provide to connect to your LDAP server. The OpenLDAP client tools can be used to connect to other LDAP servers provided by other software manufacturers. Table 16-4 lists the common options that are available to most LDAP tools.

Most commonly you will use the –D option to specify the user you are binding as to make a query or modification and will use the -xW option to perform a simple bind and be prompted for a password (as opposed to a SASL bind –Y). Some of the options we have shown in Table 16-4 will not be available to all LDAP tools. The syntax of the LDAP tool commands usually looks like this:

ldaptool <options> filter entry                  

Several LDAP tools are available. The main ones are ldapadd, ldapmodify, ldapsearch, and ldapdelete, and as we said, they all share some or all of the common options shown previously. For the exact options available, please refer to the man pages for those tools. We are going to give you examples of how to use these commands and options in the upcoming next sections.

Adding users to our LDAP server is easy now that we have created our LDIF file. Let’s look at the complete LDIF file. As we have mentioned, we need to add the dc entry, or the top level of our DIT, at the top of this file (remember to remove it from the file if it already exists). If you are adding hundreds of users, you may want to use a script or program that handles the existing users (or LDAP errors generated from trying to re-add an existing user or DN).

$ sudo cat users.ldif
dn: dc=example,dc=com
objectclass: dcObject
objectclass: organizationalUnit
dc: example
ou: example

dn: ou=people,dc=example,dc=com
objectclass: organizationalUnit
ou: people

dn: uid=jsmith,ou=people,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: posixAccount
objectclass: exampleClient
cn: Jane Smith
sn: Smith
uid: jsmith
uidNumber: 1000
gidNumber: 1000
exampleActive: TRUE
homeDirectory: /home/jsmith
userPassword: {SSHA}IZ6u7bmw12t345s3GajRt4D4YHkDScH8

dn: uid=ataylor,ou=people,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: posixAccount
objectclass: exampleClient
cn: Angela Taylor
sn: Taylor
uid: ataylor
uidNumber: 1002
gidNumber: 1000
exampleActive: TRUE
homeDirectory: /home/ataylor
userPassword: {SSHA}PRqu69QU5WK5i8/dvqQuvFXo0xJ74OFG

dn: ou=meta,dc=example,dc=com
objectclass: organizationalUnit
objectclass: top
ou: meta

dn: cn=webadmin,ou=meta,dc=example,dc=com
objectClass: organizationalRole
objectclass: simpleSecurityObject
userPassword: {SSHA}KE0JMvJjYjQ/9lpigDCbLla5iNoBb8O8

dn: ou=groups,dc=example,dc=com
objectclass: top
objectclass: organizationalUnit
ou: groups

dn: cn=staff,ou=groups,dc=example,dc=com
objectclass: top
objectclass: posixGroup
gidNumber: 1000
cn: staff

dn: cn=admins,ou=groups,dc=example,dc=com
objectclass: top
objectclass: groupOfNames
cn: admins
member: uid=ataylor,ou=people,dc=example,dc=com

dn: ou=hosts,dc=example,dc=com
objectclass: top
objectclass: organizationalUnit
ou: hosts

We are now going to add our users using the file users.ldif. The ldapadd tool is versatile and takes many options. The way we will use it is as follows:

$ sudo ldapadd -D "cn=admin,dc=example,dc=com" -ZZ -H ldap://ldap.example.com
 -xWv -f users.ldif

The ldapadd command can use the SASL authentication method or the simple method. As we have mentioned earlier, if you have SASL set up, you can bind without sending the password across the wire, with the simple authentication method the password is sent to be verified on the LDAP server, so it should be sent over a secure transport like TLS. The -x will make ldapadd use the simple method. -W tells ldapadd that we want to be prompted for a password. -v is to be verbose in its information. When you specify -D, you give the username you want to bind with. In this case, we are using the cn=admin,dc=example,dc=com user, and as you may remember, this is the rootDN we added to the SLAPD server earlier. The -h switch is the hostname, ldap.example.com. -Z tells the command to use STARTTLS, or make a TLS connection to the LDAP host, but if you have TLS already set in /etc/ldap/ldap.conf or /etc/openldap/ldap.conf, your command will fail. Finally, -f indicates the file we want to use to add our users, users.ldif.

The options you use here are the same for all the other LDAP tools; see the man page for more details. When you issue this command, you will get something like this:

jsmith@ldap:/etc/ldap$ ldapadd -xWv -D cn=admin,dc=example,dc=com
-h ldap.example.com -Z -f users.ldif
ldap_initialize( ldap://ldap.example.com )
Enter LDAP Password:
add objectclass:
        top
        person
        exampleClient
        posixAccount
add cn:
        Jane Smith
add sn:
        Smith
add uid:
        jsmith
add uidNumber:
        1000
add gidNumber:
        1000
add exampleActive:
        TRUE
add homeDirectory:
        /home/jsmith
add userPassword:
        {SSHA}IZ6u7bmw12t345s3GajRt4D4YHkDScH8
adding new entry "uid=jsmith,ou=people,dc=example,dc=com"
modify complete

If successful, you will see a “Modify complete” message. If something goes wrong, you will receive an error on the console output, and you can use journalctl to further examine the log entries produced.

$ journalctl –xe –u slapd

Remember to adjust your LogLevel entry like described previously if you are not seeing enough detail in the logs.

Searching Your LDAP Tree

Now that we have some entries in our LDAP database, we can search it to make sure we can return useful information. Let’s look at ways we can search our LDAP directory.

$ ldapsearch -xvW -H ldap://ldap.example.com -ZZ 
-D cn=admin,dc=example,dc=com 
-b ou=people,dc=example,dc=com -s sub 
'(&(&(objectclass=person)(uid=jsmith))(exampleActive=TRUE))' cn

The arguments we use for the search are similar to the ones we use for the ldapadd command. We first specify that we are performing a simple bind with verbose output, and we want to be prompted for a password, -xvW. -h declares the host we want to connect to, and -Z says try to make a connection using TLS (a -ZZ would mean to confirm that the TLS connection was successful before proceeding). Angela Taylor is a user that we have put in cn=admins,ou=groups,dc=example,dc=com; remember that we have given write access to all entries under ou=people,dc=example,dc=com through our access control list. We have just added the user Jane Smith to our LDAP directory, and we will conduct a search to look at her details.

In our ldapsearch command, you can see we include a filter to make use of indexes and to reduce our search response time. We know that all user entries have the object class person. As we explained, in our slapd.conf file all object classes are indexed, so choosing one that you know is in the entity you are looking for will speed your searches. The uid attributes are also indexed, so we also want to filter on the uid of the entry we are looking for. Our search filter looks like this:

 (&(&(objectclass=person)(uid=jsmith))(exampleActive=TRUE)),

These are read inside out; let’s take the first part.

&(objectclass=person)(uid=jsmith)

This means to filter on entries where the object class is person AND uid is jsmith. The second part looks like this:

(&(<first match>)(exampleActive=TRUE))

Here we match on the first match AND that the account is active, as indicated by exampleActive=TRUE. The & operator indicates that we are searching for one AND the other. We can also use the | symbol to indicate we want to search for one OR the other.

We specify the base of the DIT tree we wish to start searching from, -b ou=people, dc=example,dc=com, and the scope of our search is -s sub, or everything under it. And finally, we are searching for Jane’s common name, or cn. The results of this search will look like the following:

ldap_initialize( ldap://ldap.example.com )
filter: (&(&(objectclass=person)(uid=jsmith))(exampleActive=TRUE))requesting: cn
# extended LDIF
#
# LDAPv3
# base <ou=people,dc=example,dc=com> with scope subtree

# filter: (&(&(objectclass=person)(uid=jsmith))(exampleActive=TRUE))
# requesting: cn
#

# jsmith, People, example.com
dn: uid=jsmith,ou=people,dc=example,dc=com
cn: Jane Smith

# search result
search: 3
result: 0 Success

# numResponses: 2
# numEntries: 1

Here you can see that we have returned the DN we were looking for and the common name for that entry. Next, let’s look at deleting entries.

Deleting Entries from Your LDAP Directory

The other thing you are going to want to do often is delete entries in your LDAP directory. To delete entries, use the ldapdelete command. Again, this takes the same arguments as ldapadd and ldapsearch. For deleting more than one entry, you can input a text file, or you can delete entries individually. Assume we have the following entries in a new users.ldif file, and we want to delete them.

uid=jbob,ou=people,dc=example,dc=com uid=tbird,ou=people,dc=example,dc=com

We can now add these two entries to a file called deluser.ldif and then run the ldapdelete command with the -f argument as follows:

ldapdelete -xvW -D uid=ataylor,ou=people,dc=example,dc=com 
-h ldap.example.com -Z -f deluser.ldif
ldap_initialize( ldap://ldap.example.com )
deleting entry "uid=jbob,ou=people,dc=example,dc=com"
deleting entry "uid=tbird,ou=people,dc=example,dc=com"

As a result, these entries are no longer in our directory and have been deleted.

Password Policy Overlay

Setting the password policy overlay allows us greater control over password aging and change history. Overlays, as explained earlier, provide extra functionality for your OpenLDAP server. We want to set our password aging to 7776000 (90 days in seconds) and our password history to 3, meaning we will store the previous three passwords supplied by users so they can’t keep using the same one. The password will need to have a minimum of eight characters.

dn: ou=policies,dc=example,dc=com
objectClass: organizationalUnit
ou: policies

dn: olcOverlay={0}ppolicy,olcDatabase={1}mdb,cn=config
objectClass: olcOverlayConfig
objectClass: olcPPolicyConfig
olcOverlay: {0}ppolicy
olcPPolicyDefault: cn=default,ou=policies,dc=example,dc=com
olcPPolicyHashCleartext: FALSE
olcPPolicyUseLockout: TRUE
olcPPolicyForwardUpdates: FALSE

dn: cn=default,ou=policies,dc=example,dc=com
objectClass: top                    
objectClass: device                    
objectClass: pwdPolicy                    
cn: default                    
pwdAttribute: userPassword                    
pwdMaxAge: 7776000                    
pwdExpireWarning: 6912000                    
pwdInHistory: 3                    
pwdCheckQuality: 1                    
pwdMinLength: 8                    
pwdMaxFailure: 4                    
pwdLockout: TRUE                    
pwdLockoutDuration: 1920                    
pwdGraceAuthNLimit: 0                    
pwdFailureCountInterval: 0                    
pwdMustChange: TRUE                    
pwdAllowUserChange: TRUE                    
pwdSafeModify: FALSE

$ sudo ldapadd -H ldapi:/// -Y EXTERNAL -f ppolicy.ldif

Testing Your Access Control Lists

From time to time, you will run into permission issues because of incorrectly functioning access control lists. There is a tool you can use to test your ACLs called slapacl. This tool tests access to attributes and object classes by the DN you want to grant access to. For example, if we want to make sure that the DN cn=webadmin,ou=meta,dc=example,dc=com, which is the user we use to bind our web services during authentication, has auth access to the userPassword attribute of our user Angela Taylor, we would issue the following:

sudo slapacl -F /etc/ldap/slapd.d 
  -b uid=ataylor,ou=people,dc=example,dc=com 
  -D cn=webadmin,ou=meta,dc=example,dc=com 
  -o tls_ssf=128 
  -v userPassword/auth

The slapacl command requires sudo access. You need to specify the slapd config directory you want to test against with -F /etc/ldap/slapd.d on an Ubuntu host; on a CentOS host, you would need to use the /etc/openldap/slapd.d directory. The -b uid=ataylor,ou=people,dc=example,dc=com DN is the DN we want to test our access on. -D cn=webadmin,ou=meta,dc=example,dc=com is the DN that we want to confirm has auth access to the DN of uid=ataylor,ou=people,dc=example,dc=com. The –o allows us to provide options that are related to slapd access. In this case, since we need to mimic our TLS security strength factor, we add the tls_ssf=128. The –v is for verbose. We specify the attribute and authentication level we want to test, in this case the attribute userPassword against the access auth. As you know, we need at least auth access for the DN cn=webadmin,ou=meta,dc=example,dc=com to authenticate with userPassword. If we are successful, we will get the following result:

authcDN: "cn=webadmin,ou=meta,dc=example,dc=com"
auth access to userPassword: ALLOWED

This confirms that the line in our access control list is working like we expect.

olcAccess: {1}to attrs=userPassword,shadowLastChange,entry,member
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" tls_ssf=128 auth

We’ll test to see whether we can get write access to the same attribute to confirm that our access control list doesn’t have a security hole in it.

sudo slapacl -F /etc/ldap/slapd.d 
  -b uid=ataylor,ou=people,dc=example,dc=com 
  -D cn=webadmin,ou=meta,dc=example,dc=com 
  -o tls_ssf=128 
  -v userPassword/write
 authcDN: "cn=webadmin,ou=meta,dc=example,dc=com"
write access to uid: DENIED

This is as we expect: we should be denied everything but auth access and below. You can also pass in other options that allow you to test access against such things as peernames and ssf.

One of the other useful ways to figure out what is going on with your access control lists, which can be hard to get right, is to have the following in your access control list while you are testing:

access to * by * search

You can combine this with modifying the logging configuration in your SLAPD, changing your log level to something like this:

olcLogLevel:  416

This will show the search filter and the access control list processing as well as connection management and configuration file processing. You can use the journalctl command to access the logs. When a request comes in, it will produce output like the following:

$ journalctl –xe –u slapd
slapd[1350]: conn=1011 op=2 SRCH base="ou=people,dc=example,dc=com" scope=2 deref=0 filter=”(&(objectClass=person)(uid=jsmith))"                  
slapd[1350]: conn=1011 op=2 SRCH attr=uid                  
...<snip>...                  
slapd[1350]: => access_allowed: read access to "uid=jsmith,ou=people,dc=example,dc=com" "uid" requested                  
slapd[1350]: => acl_get: [1] attr uid                  
slapd[1350]: => acl_mask: access to entry "uid=jsmith,ou=people,dc=example,dc=com", attr "uid" requested                  
slapd[1350]: => acl_mask: to value by "uid=ataylor,ou=people,dc=example,dc=com", (=0)                  
slapd[1350]: <= check a_dn_pat: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth                  
slapd[1350]: <= check a_dn_pat: *                  
slapd[1350]: <= acl_mask: [2] applying +0 (break)                  
slapd[1350]: <= acl_mask: [2] mask: =0                  
slapd[1350]: => dn: [3] ou=people,dc=example,dc=com                  
slapd[1350]: => acl_get: [3] matched                  
slapd[1350]: => acl_get: [3] attr uid                  
slapd[1350]: => acl_mask: access to entry "uid=jsmith,ou=people,dc=example,dc=com", attr "uid" requested                  
slapd[1350]: => acl_mask: to value by "uid=ataylor,ou=people,dc=example,dc=com", (=0)                  
slapd[1350]: <= check a_dn_pat: cn=webadmin,ou=meta,dc=example,dc=com                  
slapd[1350]: <= check a_group_pat: cn=admins,ou=groups,dc=example,dc=com                  
slapd[1350]: <= acl_mask: [2] applying write(=wrscxd) (stop)                  
slapd[1350]: <= acl_mask: [2] mask: write(=wrscxd)                  
slapd[1350]: => slap_access_allowed: read access granted by write(=wrscxd)                  
slapd[1350]: => access_allowed: read access granted by write(=wrscxd)                  

The first line shows the search string of the request, SRCH base="ou=people,dc=example,dc=com" scope=2 deref=3 filter="(&(objectClass=*)(uid=jsmith))", and we are looking for the attribute UID.

The output also shows the user making the request, uid=ataylor,ou=people,dc=example,dc=com. You can see the process of the request for access starts with a search of ou=people,dc=example,dc=com and then the final acceptance for the search (and read), via the check a_group_pat: cn=admins,ou=groups,dc=example,dc=com, and that gives ataylor write access.

With a combination of logs, the slapacl and ldapsearch tools, and the useful OpenLDAP mailing list, you can achieve intricate access control lists. Let’s look at the other tools you can use to manage your LDAP servers, including the ldapsearch tool we just mentioned.

Backing Up Your LDAP Directory

Text-based files are great for building or restoring your LDAP directory. Once your directory is implemented, we suggest that you set up a script that might regularly output your LDAP database into a text file and save it. In Chapter 14, we introduced you to the Bareos backup server and showed you how to use the Client Run Before Job and Client Run After Job options when we backed up our MySQL database. You can do a similar thing with the LDAP database, as shown in Listing 16-4.

Listing 16-4. slapcat LDIF Dump

#!/bin/bash

case $1 in
start)
   slapcat -b dc=example,dc=com -l /var/lib/ldap/backup.ldif
    if [ $? -eq 0 ] ; then
         echo "backup successful"
     else
        echo "backup failed"
        exit 1;
   fi
;;

stop)
  if [ -e /var/lib/ldap/backup.ldif ] ; then
      rm -f /var/lib/ldap/backup.ldif
      if [ $? -eq 0 ] ; then
           echo "removal of file successful"
       else
           echo "failed to remove file"
         exit 1;
     fi

  fi
 ;;
esac
exit 0

To get a perfect backup, you would want to stop the OpenLDAP directory server before you run the command in Listing 16-4; however, this is not always possible, and hot backups are preferable over no backups at all.

You use the slapcat command to dump the LDAP database to a file on disk using the Client Run Before Job script. You then get Bareos to back it up; Bareos can delete it by running the Client Run After Job script (see Listing 16-5).

Listing 16-5. The Job Definition for Bareos Backup Service

Job {
   Name = ldap.example.com
   Client = ldap-fd
   Enabled = yes
   JobDefs = "DefaultLinux"
   Client Run Before Job = "/usr/local/bin/ldap_backup start"
   Client Run After Job = "/usr/local/bin/ldap_backup stop"
}

This is based on the proviso that you have your LDAP backup script installed in /usr/local/bin on your ldap.example.com host.

Restoring your LDAP database is then simply a matter of restoring the file on your host and running the slapadd command with the following parameters (OpenLDAP should be shut down for this process):

$ slapadd -b dc=example,dc=com -F /etc/ldap/slapd.d -l restored.ldif.backup.file

Here we have restored our LDAP database to how it was when we performed the last save. Because LDAP has no write-ahead logs, you cannot replay your most recent updates to your LDAP directory server like you can in a fully featured transactional relational database, so regular backups are important. We suggest at minimum you make backups nightly.

Managing your directory server via text files can get tiresome. Luckily, we have a solution if you’re one of those who prefer a web-based GUI to do all the fiddly work for you, and we’ll discuss this next.

LDAP Account Manager: Web-Based GUI

Several tools are available to manage your LDAP directories. We have decided to focus on one of them in this book, LDAP Account Manager (LAM). This is a web-based GUI that can take some of the administrative pain away from updating text files. It is available in two versions: a free version and an enterprise version that requires a fee. If you discover you do not like using this tool, you might want to try some of the others that exist, such as the following:

• Luma: http://luma.sourceforge.net/

• GQ: http://sourceforge.net/projects/gqclient/

• phpldapAdmin: http://phpldapadmin.sourceforge.net/

• web2ldap: https://web2ldap.de/web2ldap.html

• LDAPAdmin: https://github.com/ibv/LDAP-Admin (Linux version)

Some of these are old, and some more are recent. OpenLDAP hasn’t changed very much over the years, so you are free to try any you choose. We chose to show you LAM because it is designed not only to manage LDAP but also to provision user accounts. It allows you to create users based on templates that are easy to follow. It is also flexible enough to allow you to integrate your Samba user administration if you choose to do so.

Installation and Configuration

LAM is available for download with Ubuntu from its online repositories. It is a few releases old, and if you are looking for a more recent version, you can get the .deb packages from the web site’s download page ( https://www.ldap-account-manager.org/lamcms/releases ) or from the Debian repository.

For LAM, you will need a version of PHP installed on your host higher or equal to 5.2.4.

To install it, you issue the following:

$ sudo aptitude install php-mcrypt php-zip ldap-account-manager apache2

At the time of writing, the version provided in the Ubuntu repository (5.2-1ubuntu1) does not support the default PHP (7.x) installed with Xenial. The solution is to install the .deb package first from the download page and manually install it similar to how we will do it with CentOS.

For CentOS hosts you have to download the Fedora/CentOS RPMs from the web site ( https://www.ldap-account-manager.org/lamcms/releases ). This will link to a SourceForge download, and you can get a copy to the direct link (removing the mirror information from the URL). Then use yum to install the package like in this example:

$ sudo yum install -y httpd php php-ldap php-xml
$ sudo yum install -y http://downloads.sourceforge.net/project/lam/LAM/5.5/ldap-account-manager-5.5-0.fedora.1.noarch.rpm

The CentOS installation puts all the LAM files under /usr/share/ldap-account-manager. All the configuration files are installed under /var/lib/ldap-account-manager/config/.

LAM is fairly easy to configure. On Ubuntu, some configuration files are installed into /etc/ldap-account-manager. You will find an example configuration for your Apache web server and the configuration file, /etc/ldap-account-manager/config.cfg, containing the default username and password for your LAM installation.

$ sudo vi /etc/ldap-account-manager/config.cfg
# password to add/delete/rename configuration profiles
password: {SSHA}tj1yDeQfLJbmISXwh8JfjMb2ro3v5u44

# default profile, without ".conf"
default: lam

In the config.cfg file, you can see we have set our own password to {SSHA}tj1yDeQfLJbmISXwh8JfjMb2ro3v5u44 (be careful with your ownership and permissions). We also need to change the following file to add our own LDAP directory details. First, we make a copy of the file /var/lib/ldap-account-manager/config/lam.conf. We then make the changes in bold to the /var/lib/ldap-account-manager/config/lam.conf file.

$ sudo vi /var/lib/ldap-account-manager/config/lam.conf
# LDAP Account Manager configuration

# server address (e.g. ldap://localhost:389 or ldaps://localhost:636)
ServerURL: ldaps://ldap.example.com              

# list of users who are allowed to use LDAP Account Manager
Admins: cn=admin,dc=example,dc=com              

# password to change these preferences via webfrontend
Passwd: somepassword

# suffix of tree view
treesuffix: dc=example,dc=com                    

# maximum number of rows to show in user/group/host lists
maxlistentries: 30

# default language (a line from config/language)
defaultLanguage: en_GB.utf8:UTF-8:English (Great Britain)

# Number of minutes LAM caches LDAP searches.
cachetimeout: 5

# Module settings
modules: posixAccount_minUID: 1000              
modules: posixAccount_maxUID: 30000              
modules: posixAccount_minMachine: 50000              
modules: posixAccount_maxMachine: 60000              
modules: posixGroup_minGID: 1000              
modules: posixGroup_maxGID: 20000              
modules: posixGroup_pwdHash: SSHA
modules: posixAccount_pwdHash: SSHA

In the first section of this file, we add the details for our LDAP directory including the connection details, tree information, Posix UID, GID, and machine numbers. The UID and GIDs are used when we create new users in the LAM interface; they will be incremented in those ranges listed previously.

# List of active account types.
activeTypes: user,group,host                    

types: suffix_user: ou=people,dc=example,dc=com              
types: attr_user: #uid;#givenName;#sn;#uidNumber;#gidNumber
types: modules_user: person,posixAccount,shadowAccount,exampleClient              

types: suffix_group: ou=groups,dc=example,dc=com              
types: attr_group: #cn;#gidNumber;#memberUID;#description
types: modules_group: posixGroup              

types: suffix_host: ou=hosts,dc=example,dc=com              
types: attr_host: #cn;#description;#uidNumber;#gidNumber
types: modules_host: account,posixAccount              

# Access rights for home directories scriptRights: 750              

In the last section of the file, we detail the account types we want to enable in the activeTypes section and the LDAP branches that house these. The LAM administration tool will use these details to create the user accounts for us in our LDAP server.

Adding the Apache Virtual Host for LAM

We are going to add an Apache virtual host to our web server to host our LAM site. In Chapter 11, we showed you how to set up an Apache virtual host. The web service can run on any host; it does not have to be on the same host as the LDAP server, but in our example, this will be the case. We have chosen to house this site on our host with the IP address 192.168.0.1 and DNS name of ldap.example.com, also known as headoffice.example.com.

On our Ubuntu host, we will have the following configuration: the main sections of this virtual host have been provided by the LAM package and can be found in /etc/ldap-account-manager/apache.conf. We are going to include this file in our VirtualHost information. The VirtualHost will be placed in /etc/apache2/sites-available and will be called ldap.example.com.conf. On CentOS, we would include the file in the /etc/httpd/conf.d/ directory.

$ sudo vi /etc/apache2/sites-available/ldap.example.com.conf
<VirtualHost 192.168.0.1:443>
  ServerName ldap.example.com
  SSLEngine on
  SSLCertificateFile /etc/ldap/certs/ldap.example.com.cert
  SSLCertificateKeyFile /etc/ldap/certs/ldap.example.com.key
  SSLCACertificateFile /etc/ldap/certs/cacert.pem

  LogFormat "%v %l %u %t "%r" %>s %b" comonvhost
  CustomLog /var/log/apache2/ldap.example.com_access.log comonvhost
  ErrorLog /var/log/apache2/ldap.example.com_error.log
  Loglevel debug

  Include /etc/ldap-account-manager/apache.conf

</VirtualHost>

We have created a VirtualHost enclosed between the <VirtualHost> </VirtualHost> tags. In this VirtualHost we have added our TLS/SSL keys pointing to our /etc/ldap/certs directory and have created separate log files in the /var/log/apache2 directory to aid diagnosis of any problems relating to this VirtualHost.

We have included (Include /etc/.../apache.conf) the Apache configuration file provided by the LAM package. This allows that package to be managed by the package manager and updated accordingly.

On Ubuntu we need to enable the site and make sure SSL is also enabled. We do that with the following:

$ sudo a2ensite ldap.example.com.conf
$ sudo a2enmod ssl

On CentOS hosts, there is a lam.apache.conf file placed in the /etc/httpd/conf.d/ directory. You may like add the VirtualHost directives in our Ubuntu example into a copy of this file to include the SSL and logging directives. If you don’t, the LAM GUI will be available from http://ldap.example.com/lam . Refer to Chapter 11 for more information on managing CentOS virtual hosts.

Next, we start the Apache web server and point our browser at https://ldap.example.com/lam . We are now presented with the login page for the LAM configuration tool, as shown in Figure 16-4.

Figure 16-4. LAM login page

In the top right notice the LAM configuration link. This is used to perform general maintenance on the LAM configuration tool. On the login page, you will be asked for the password you have added to /var/lib/ldap-account-manager/config.cfg. Here you can change the general login settings as well as the password for your manager.

The admin user you can see in Figure 16-4 refers to the rootDN we specified in /var/lib/ldap-account-manager/config/lam.conf. When we enter the password for our rootDN, we are presented with the users we have already configured, as shown in Figure 16-5.

Figure 16-5. Front page of the LAM web GUI

We are now going to create a new user using the standard profile . Profiles serve as templates for creating users. We start by clicking the New User button to bring up the page shown in Figure 16-6.

Figure 16-6. Creating a new user

We now need to click the Personal tab and fill out the details required there. The only details we will enter in the Personal tab are first name, last name, and description (see Figure 16-6); you can, of course, add as much detail as you want.

In the Unix tab, we fill in the details required to add a Unix/Linux account, as shown in Figure 16-7. If we do not enter a UID number, one will be generated for us according to the limits we specified in the lam.conf file. We are attaching users to the staff group, and we can add more, providing the groups already exist, by clicking the “Edit groups” button.

Figure 16-7. Linux(Unix) details

Prior to the enabling the Shadow section, we need to enable the shadow extension. Once this is done, you will see the screen in Figure 16-8.

Figure 16-8. Shadow details

In the Shadow tab, we will leave the defaults as is. You can see these defaults in Figure 16-9.

Figure 16-9. User add complete

To finish creating our user, we go back to the Main tab and click the Create Account button. We then see a confirmation screen like the one in Figure 16-9 indicating a successful operation.

As you can see in Figure 16-10, our new user, tbird, has been created.

Figure 16-10. Listing the new user

You can use LAM to add and remove group and host entries in your LDAP directory, which we will leave you to explore further on your own. Remember, LAM is not the only LDAP management tool. If you do not like this LDAP management client for managing your LDAP service, we suggest you try one of the other clients we mentioned earlier.

For further documentation on configuring LAM, please visit the following:

• https://www.ldap-account-manager.org/static/doc/manual-onePage/index.html

Single Sign-On: Centralized Linux Authentication

We are now going to show you how to centralize your user accounts on your Linux hosts. Having several Linux hosts with several user accounts on each can become cumbersome to manage. Passwords can get out of sync, and you might not remove users when they leave your company from all your hosts, creating potential security risks. To simplify this kind of user management, you could centralize your authentication service by pointing your Linux hosts to your LDAP server. To show you how to do that, we will first go through installing the necessary software and then examine the files used in the configuration. The good thing is that you should be able to use the authentication tools provided by your distribution to configure the necessary files that make single sign-on work.

We are going to need a modification to our access lists. There are certain entries that we will need anonymous access. When we authenticate against our LDAP server, we need to first access certain entries. There are two ways to do this; the first is with a bind DN and password, like a proxy, that will bind and get access to the entries, and the second is with anonymous bind, where no bind is done (remember that bind is another word for authentication). If we use a proxy bind DN, we need to set a password in clear text on every host that connects. In this exercise, we have chosen not to do that.

There are several other authentication methods you could choose to use instead of simple authentication. You can set up authentication with SASL or Kerberos if you wanted, and we talked about these authentication methods in Chapter 13.

The access control list now looks like this. You will see the changes in bold; we have given anonymous the ability to read certain attributes that are looked up during authentication and have given auth access to the userPassword attribute. We have also prevented users from changing certain attributes that they shouldn’t have write access to, such as uidNumber, homeDirectory, and so on.

dn: olcDatabase={1}mdb,cn=config
changetype: modify
replace: olcAccess
olcAccess: {0}to *
        by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth manage
        by * none break
-
add: olcAccess
olcAccess: {1}to attr=entry,member,objectClass,uid,uidNumber,gidNumber,homeDirectory,cn,shadowWarning,modifyTimestamp                  
        by group.exact="cn=admins,ou=Groups,dc=example,dc=com" tls_ssf=128 write            
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" tls_ssf=128 read            
        by anonymous tls_ssf=128 read            
        by self tls_ssf=128 read            
-
add: olcAccess
olcAccess: {2}to attrs=userPassword
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" tls_ssf=128 auth
        by group.exact="cn=admins,ou=Groups,dc=example,dc=com" tls_ssf=128 write
        by self tls_ssf=128 write
        by anonymous tls_ssf=128 auth            
        by * none stop
-
add: olcAccess
olcAccess: {3}to dn.children="ou=People,dc=example,dc=com"
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" read
        by group.exact="cn=admins,ou=Groups,dc=example,dc=com" write
        by self write
        by users read
-
add: olcAccess                          
olcAccess: {4}to dn.children="ou=Groups,dc=example,dc=com"
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" read
        by group.exact="cn=admins,ou=Groups,dc=example,dc=com" write
-
add: olcAccess
olcAccess: {5}to dn.children="ou=meta,dc=example,dc=com"
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" read
        by group.exact="cn=admins,ou=Groups,dc=example,dc=com" write
        by self read
-
add: olcAccess                          
olcAccess: {6}to dn.children="ou=Hosts,dc=example.com"
        by group.exact="cn=admins,ou=Groups,dc=example,dc=com" write
        by dn.exact="cn=webadmin,ou=meta,dc=example,dc=com" search
-
add: olcAccess
olcAccess: {7}to * by * none

Setting Up sssd

To authenticate against an LDAP server from our Linux clients, we will install a package called sssd. It is designed as a daemon that will authenticate against a wide range of authentication services, including LDAP.

On Ubuntu, you need these packages installed:

$ sudo aptitude install sssd

On CentOS, of course, you would use YUM to install the same package name. They also take the same configuration. We need to create a file called /etc/sssd/sssd.conf. This file needs to have the 0600 permission set.

This file itself will have the following contents:

[sssd]
config_file_version = 2
services = nss, pam
domains = LDAP

[domain/LDAP]
cache_credentials = true

id_provider = ldap
auth_provider = ldap

ldap_uri = ldap://ldap.example.com
ldap_search_base = dc=example,dc=com
ldap_id_use_start_tls = true
ldap_tls_reqcert = demand
ldap_tls_cacert = /etc/ssl/certs/cacert.pem
chpass_provider = ldap
ldap_chpass_uri = ldap://ldap.example.com
entry_cache_timeout = 6
ldap_network_timeout = 2
ldap_group_member = uniquemember
ldap_pwdlockout_dn = cn=ppolicy,ou=policies,dc=example,dc=com
ldap_access_order = lockout

The main directives in this file can be found in man sssd.conf and sssd-ldap. But the first section tells sssd that we are going to use nss and pam to run our LDAP domain. In the LDAP domain section we have the provider for id and auth and then the connection details including TLS settings and password policy details.

When Linux looks for a piece of information such as a host or a password, it checks a file called /etc/nsswitch.conf for where to find that information. The nsswitch.conf file will need to be updated with the following information to tell it to use sssd for passwd, group, and shadow files; this is the information required to log in.

passwd:     files sss
group:      files sss
shadow:     files sss
gshadow:    files

hosts:      files mdns4_minimal [NOTFOUND=return] dns
networks:   files

protocols:  db files
services:   db files sss
ethers:     db files
rpc:        db files

# pre_auth-client-config # netgroup:       nis
netgroup:   nis sss
sudoers:    files sss

We have the information we seek on the left, and then we have where to look for that information on the right and the order to look for it. For example, when we require information that is normally contained in the /etc/passwd file (like username), we first look in that file. If the username is not found in the file, we then query the sssd daemon (or sss). The same applies for group and shadow.

The next part we need to update is the PAM authentication modules. We need to allow us to use sss(d) for authentication via PAM. On Ubuntu we do that by changing the following (we have removed the comments from the example):

/etc/pam.d/common-auth
auth    [success=3 default=ignore]     pam_unix.so nullok_secure
auth    [success=2 default=ignore]     pam_sss.so use_first_pass                      
auth    [success=1 default=ignore]     pam_ldap.so use_first_pass
auth    requisite                      pam_deny.so
auth    required                       pam_permit.so

/etc/pam.d/common-password
password   requisite                   pam_pwquality.so retry=3
password   [success=3 default=ignore]   pam_unix.so obscure use_authtok try_first_pass sha512
password   sufficient                  pam_sss.so use_authtok                      
password   [success=1 user_unknown=ignore default=die]  pam_ldap.so use_authtok try_first_pass
password   requisite                   pam_deny.so
password   required                    pam_permit.so
password   optional                    pam_gnome_keyring.so

/etc/pam.d/common-account
account    [success=2 new_authtok_reqd=done default=ignore]    pam_unix.so
account    [success=1 default=ignore]  pam_ldap.so
account    requisite                   pam_deny.so
account    required                    pam_permit.so
account    sufficient                  pam_localuser.so
account    [default=bad success=ok user_unknown=ignore]    pam_sss.so                      

/etc/pam.d/common-session
session    [default=1]        pam_permit.so
session    requisite          pam_deny.so
session    required           pam_permit.so
session    optional           pam_umask.so
session    required           pam_unix.so
session    optional           pam_sss.so                      
session    optional           pam_ldap.so
session    optional           pam_systemd.so
session    required           pam_mkhomedir.so skel=/etc/skel umask=0022                      

These files should be updated for you when you have installed sssd on Ubuntu, and we will not need to change them. You will note that at the end of the common-session file we are allowing authenticated users to make their own home directories and populate them with the contents of /etc/skel.

On CentOS you may have to add these pam directives to /etc/pam.d/system-auth yourself. They are slightly different but basically the same for both distributions.

auth        required      pam_env.so
auth        sufficient    pam_fprintd.so
auth        sufficient    pam_unix.so nullok try_first_pass
auth        sufficient    pam_sss.so use_first_pass                      
auth        requisite     pam_succeed_if.so uid >= 1000 quiet_success
auth        required      pam_deny.so

account     required      pam_unix.so
account     sufficient    pam_localuser.so
account     sufficient    pam_succeed_if.so uid < 1000 quiet
account     [default=bad success=ok user_unknown=ignore]  pam_sss.so                      
account     required      pam_permit.so

password    requisite     pam_pwquality.so try_first_pass local_users_only retry=3 authtok_type=
password    sufficient    pam_unix.so sha512 shadow nullok try_first_pass use_authtok
password    sufficient    pam_sss.so use_authtok                      
password    required      pam_deny.so

session     optional      pam_keyinit.so revoke
session     required      pam_limits.so
-session    optional      pam_systemd.so
session     [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid
session     optional      pam_mkhomedir.so skel=/etc/skel umask=0022                      
session     required      pam_unix.so

We discussed configuring PAM in Chapter 5, but we are going to talk about it some more in the “How PAM Works” section coming up.

Now that we have PAM and sssd configured, we only need to make sure that we can connect to the LDAP server from the client. In our sssd.conf file, we specified the ldap_tls_cacert. We need to make sure that we have /etc/ssl/certs/cacert.pem installed in the correct location; otherwise, we will be rejected from the LDAP server.

Once we have placed cacert.pem in the correct place, we can test to see whether we can query the LDAP server for users.

$ grep ataylor /etc/passwd

On our host, this returns no result, meaning that the user ataylor has not been created, but we did create her in our LDAP configuration. We are going to use a command called getent to query the passwd file and the sssd (as directed by our configuration in nsswitch.conf; getent is a tool for querying those entries).

$ getent passwd ataylor
ataylor:*:1002:1000:Angela Taylor:/home/ataylor:

We have been returned the user details for Angela Taylor, including the UID/GID and home directory information. This means we can talk and return information from our LDAP server successfully.

The next step is to prove that we can log in as her. To do that, we are going to use the su command, or superuser command. This command allows you to sign in as the root user or into another account. When we issue this command, we will be asked to provide Angela’s password.

jsmith@au-mel-ubuntu-2:∼$ su - ataylor
Password:
ataylor@au-mel-ubuntu-2:∼$

Here we have successfully signed into a user that exists only in LDAP. A home directory has been created as we signed in for the first time. Now any LDAP user can sign into our hosts and have their home directories created.

We can further refine our sssd.conf file to filter for certain users, like only if they have exampleActive set to TRUE.

ldap_access_filter = (exampleActive=TRUE)

If you are using the Ubuntu Unity desktop, you will need to make a change to the following file to allow other users to log in from the desktop:

/usr/share/lightdm/lightdm.conf.d/50-unity-greeter.conf
[Seat:*]
greeter-session=unity-greeter
greeter-show-manual-login=true

This will allow you to see a screen like in Figure 16-11 after a reboot of your Ubuntu desktop. After you enter your username, you’ll enter your password, as shown in Figure 16-12.

Figure 16-11. Logging in via LDAP to the desktop

Figure 16-12. Providing the LDAP password

You will be able to provide an LDAP username and password with CentOS too, without having to configure anything special.

How PAM Works

As explained in Chapter 5, Linux can use Pluggable Authentication Modules (PAM) to authenticate services against your LDAP service. PAM provides authentication, authorization, and password-changing abilities for hosts against LDAP servers. PAM is configured via the files located in the /etc/pam.d directory. As described in Chapter 5, the main PAM file on your CentOS host is the /etc/pam.d/system-auth file. Listing 16-6 shows an example of the settings required to establish LDAP authentication on your host.

Listing 16-6. PAM Settings for system-auth on CentOS

auth        required      pam_env.so
auth        sufficient    pam_fprintd.so
auth        sufficient    pam_unix.so nullok try_first_pass
auth        sufficient    pam_sss.so use_first_pass                    
auth        requisite     pam_succeed_if.so uid >= 1000 quiet_success
auth        required      pam_deny.so

account     required      pam_unix.so
account     sufficient    pam_localuser.so
account     sufficient    pam_succeed_if.so uid < 1000 quiet
account     [default=bad success=ok user_unknown=ignore]  pam_sss.so                    
account     required      pam_permit.so

password    requisite     pam_pwquality.so try_first_pass local_users_only retry=3 authtok_type=
password    sufficient    pam_unix.so sha512 shadow nullok try_first_pass use_authtok
password    sufficient    pam_sss.so use_authtok                    
password    required      pam_deny.so

session     optional      pam_keyinit.so revoke
session     required      pam_limits.so
-session    optional      pam_systemd.so
session     [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid
session     optional      pam_mkhomedir.so skel=/etc/skel umask=0022                    
session     required      pam_unix.so

This file is generated for you, and you should not have to alter it yourself unless there is a good reason. You can see from Listing 16-6 that the file is made up of four independent management groups: auth, account, password, and session.

Take a look at the following line, which is an example of the auth management group:

auth        sufficient    pam_sss.so use_first_pass                  

This group authenticates the user usually by some password challenge-response mechanism. The sufficient control value says that if this module is successful, consider the user authenticated. pam_sss.so is the PAM shared object to be used, the code that determines how a user is authenticated. Lastly, use_first_pass is the optional syntax that says instead of asking for your password again, use the first one provided by one of the higher modules in the stack.

On Ubuntu hosts, the corresponding files are common-auth, common-password, common-session, and common-account in the /etc/pam.d directory.

The other file central to PAM authenticating against an LDAP service is /etc/nsswitch.conf. This file requires the passwd, group, and shadow keywords to have these values:

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

As we have explained, these tell PAM what authentication databases to use and the order in which to use them. So when we are looking for information we would normally find in /etc/passwd, we would first use the files on the host and then use LDAP. The same goes for group and shadow. The PAM and nsswitch.conf files should be configured for you by the authentication configuration tools provided by your distribution.

LDAP and Apache Authentication

Let’s now look at how we get our web server to use our LDAP server to authenticate clients. When clients try to access the https://ldap.example.com web site, they will be required to enter their LDAP username and password before they gain access. We will do two things to our web server to achieve this: make all our communications with our web server secure by enabling SSL on our web host and add the LDAP details to the ldap.example.com virtual host.

We will assume this is being run from the ldap.example.com host and that there is no other Apache service running on it.

Next, let’s examine the changes we will make to our ldap.example.com virtual host file.

$ sudo vi /etc/apache2/sites-available/ldap.example.com.conf
LDAPTrustedGlobalCert CA_BASE64 /etc/ldap/certs/cacert.pem
LDAPTrustedMode TLS

<VirtualHost 192.168.0.1:443>
  ServerName ldap.example.com
  SSLEngine on
  SSLCertificateFile /etc/ldap/certs/ldap.example.com.cert
  SSLCertificateKeyFile /etc/ldap/certs/ldap.example.com.key
  SSLCACertificateFile /etc/ldap/certs/cacert.pem

  LogFormat "%v %l %u %t "%r" %>s %b" comonvhost
  CustomLog /var/log/apache2/ldap.example.com_access.log comonvhost
  ErrorLog /var/log/apache2/ldap.example.com_error.log
  Loglevel debug

  <Location /lam >
     AuthType Basic              
     AuthName "LDAP example.com"              
     AuthBasicProvider ldap              
     AuthLDAPBindAuthoritative on              
     AuthLDAPURL ldap://ldap.example.com/ou=people,dc=example,dc=com?uid?sub              
     AuthLDAPBindDN cn=webadmin,ou=meta,dc=example,dc=com              
     AuthLDAPBindPassword <thewebadminpasswordincleartext>              
     Require valid-user              
     Require ldap-group cn=admins,ou=groups,dc=example,dc=com              
  </Location>

  Include /etc/ldap-account-manager/apache.conf

</VirtualHost>

Inside the <VirtualHost> tags, we have added a Location directive . The Location directive says that any URI matching /lam will now trigger the following configuration, prompting the user to authenticate against LDAP:

AuthType Basic
AuthName "LDAP example.com"
AuthBasicProvider ldap
AuthLDAPBindAuthoritative on
AuthLDAPURL ldap://ldap.example.com/ou=people,dc=example,dc=com?uid?sub
AuthLDAPBindDN cn=webadmin,ou=meta,dc=example,dc=com
AuthLDAPBindPassword Zf3If7Ay
Require valid-user
Require ldap-group cn=admins,ou=groups,dc=example,dc=com

We have set AuthType to Basic and AuthName to LDAP example.com. AuthType defines the method of authentication, and you have a choice between Basic and Digest. LDAP authentication requires Basic. AuthName is the name in the authentication window that pops up.

AuthBasicProvider ldap defines the server we are going to use, in this case the LDAP server, to provide our authentication mechanism. We indicate that we want the LDAP server to be the authoritative service to accept or decline access by specifying AuthzLDAPAuthoritative on. Next is the LDAP URL we are going to use for our authentication service, AuthLDAPURL ldap:// ldap.example.com/ou=people,dc=example,dc=com?uid?sub. It specifies the base of our searches, ou=people,dc=example,dc=com; the attribute we are interested in, uid; and the scope of our searches, sub. Here you can now see where we are using the cn=webadmin,ou=meta,dc=example,dc=com meta account, which will bind to our LDAP server with the password also provided. You don’t have to provide the password as clear text; if it makes you uncomfortable, you can try these other methods as well:

• https://httpd.apache.org/docs/2.4/mod/mod_authnz_ldap.html#authldapbindpassword

Finally, we specify that we require a valid user, and the authenticating user must also belong to the LDAP group cn=admin,ou=groups,dc=example,dc=com.

Before we proceed, we will need to make sure that the modules are added to our web host, and on Ubuntu we would do the following:

$ sudo a2enmod authnz_ldap
$ sudo a2enmod ldap
$ sudo a2enmod ssl

For CentOS, we need to make sure that the packages mod_ssl and mod_ldap are installed; this will create the file in the conf.modules.d directory.

$ cat /etc/httpd/conf.modules.d/01-ldap.conf
# This file configures the LDAP modules:
LoadModule ldap_module modules/mod_ldap.so
LoadModule authnz_ldap_module modules/mod_authnz_ldap.so

We need to now restart our Apache service (restart apache2 for Ubuntu).

$ sudo systemctl restart httpd

We use our web browser now to connect to the LAM web GUI at the following address: https://ldap.example.com/lam .

In Figure 16-13, you can see the authentication challenge provided by Apache. We have entered the uid of ataylor, whom we know is a member of the cn=admins,ou=groups,dc=example,dc=com group, which is required by our Apache configuration.

Figure 16-13. The Apache request for username and password

You should now be able to access LAM , and you should see the successful login in the Apache logs.

...authorization result of Require ldap-group cn=admins,ou=groups,dc=example,dc=com...
...auth_ldap authenticate: accepting ataylor....
...authorization result of Require valid-user : granted...

This shows that the LDAP server is authenticating our request using the username ataylor and testing that this user is a member of the cn=admin,ou=groups,dc=example,dc=com group. This level of detail is provided by the debug logging option in the virtual host LogLevel directive.