Intro on using LDAP with ActionApplications

OpenLDAP server software. Other LDAP servers should work, too, but the ActionApps have been tested with OpenLDAP only.

If you have already an OpenLDAP server running, you may skip the rest of this section.

Using LDAP, some thoughts about the LDAP database organization should be wasted. An LDAP database is an hierarchically structured system of objects, each member of one or more certain classes. Every object in your database has its place in the potentially global LDAP hierarchy. Each object has a unique name, the so called distinguished name, or short dn. The dn consists of the full "path" from the global LDAP name space to the object, similar to names in the domain name system.

In order to set up the LDAP server for ActionApps, you need to figure out some information you want to use:

Your base dn. This is the common part all your LDAP objects will have in their dn, describing the "path" from the global LDAP name space to your organization. It is recommended that you use a domain name you own for that. (You could also use a geographical category, but this is not described here.) A domain name can be described in a LDAP dn using the dc attribute. For example, the base dn for a possible domain name ecn.apc.org would be dc=ecn,dc=apc,dc=org or in new version we are using as default dn ou=AA.
Your LDAP administrative account. OpenLDAP's built-in access control needs a root object which has all privileges. Once it exists, the root object can be used to modify the data stored in the LDAP database. Like every object in the database, the root object needs a dn. It is recommended that you use the canonical name root. Following the example above, this gives us a root object dn of cn=root,dc=ecn,dc=apc,dc=org or in new version we are using as default a root object dn cn=root,ou=AA.

Note: As with the database server, the OpenLDAP server does not necessarily need to be running on the same machine as the ActionApps.

Step by Step instruction for Installing OpenLDAP

The OpenLDAP server does not need to be on the same host as the ActionApps themselves are.

Check if you have already the OpenLDAP server installed:


  
% man slapd
No manual entry for slapd

If the manual page appears, it is very likely you have the OpenLDAP server on the machine. (This check is preferred over the rpm way because the OpenLDAP rpm exists only for a short time so far and many machines probably have it installed without the rpm.)

OpenLDAP is included in RedHat Linux 6.1; releases prior to 6.1 don't have it. It is possible to install the rpms on any 6.x RedHat Linux though.

If you don't have the OpenLDAP server installed, and if you don't have the rpm's, get the rpm's from a RedHat mirror site, for example from ftp://ftp.tu-chemnitz.de/pub/linux/redhat-updates/6.2/i386/openldap-1.2.9-6.i386.rpm and ftp://ftp.tu-chemnitz.de/pub/linux/redhat-updates/6.2/i386/openldap-devel-1.2.9-6.i386.rpm and install them:


  
# rpm -Uv openldap-1.2.9-6.i386.rpm
openldap-1.2.9-6
# rpm -Uv openldap-devel-1.2.9-6.i386.rpm
openldap-devel-1.2.9-6

Setup: Configuration

If you didn't have an OpenLDAP server running, you will need to create the /etc/openldap/slapd.conf file - this is the server configuration file. Use the file doc/slapd.conf from the ActionApps distribution to create it. This file is well documented and contains hints about which spots need to be modified. The LDAP server will not work properly if you don't edit this file. You will need some basic data to fill in here; see at LDAP basic info for details.

The root dn password in this file can be trivial for now (leave it as it is, "password"), we will replace it shortly with a secure one. We refer to this password as the ldap root dn password.

Also you need to copy some other files from the ActionApps doc directory to the /etc/openldap/ directory and change the file mode of the main configuration file:


  
# chmod 600 /etc/openldap/slapd.conf
# cp slapd.apc.schema /etc/openldap/schema/

Edit the file /etc/openldap/ldap.conf. After installation, it only contains comments. Put in two lines containing your base dn and the host where the ldap server runs:


  
BASE    ou=AA
HOST    localhost

(This file is used by the programs that access a ldap server, not by the server itself. It only affects accessing programs on the machine where the programs run.)

Create the directory where the LDAP database will live (again, replace the domain name with the one your base dn was derived from):


  
# mkdir /var/lib/ldap/aa

Start the ldap server

Try to start the ldap server and check messages from the messages logfile (normally /var/log/messages):


  
# /etc/rc.d/init.d/ldap start
Starting ldap:                                             [  OK  ]
# tail /var/log/messages
[...]
Jul 17 11:01:28 ecn ldap: slapd startup succeeded

Make the ldap server start on system boots:


  
# chkconfig ldap on

Initial database creation

The OpenLDAP server needs an initial database before its first start. To create this database, you need a ldif format file which can be translated into the database by the ldapmodify command. There is an example ldif file, namely LDIF.ini, in the doc/ directory. Edit this file to suit your needs according to the following instructions.

The initial ldif file should contain five objects:

Your base object
The ActionApps account object (used by ActionApps to access the ldap server)
A group object for ActionApps users
The ActionApps APCACL object (ActionApps access control storage object) of ActionApps administrators

Objects are separated by blank lines. Each line consists of a keyword, followed by a colon, followed by a value. The first line of each object is the dn, thus the keyword is "dn". The other object lines are its attributes.

Edit these spots:

Everywhere: replace all occurances of the example "ou=AA" base dn with your own one (hopefully your editor has a good search and replace function).

Having made these modifications, we can tell the ldap server to create the objects:


  
% ldapmodify -x -a -f ldiffile -D "cn=root,ou=AA" -w password
adding new entry ou=AA

adding new entry cn=aauser,ou=AA

adding new entry ou=People,ou=AA

adding new entry ou=ACLs,ou=AA

If the server responds with an error message:

ldap_add: Insufficient access: Check the rootdn: entry in the slapd.conf file and what you typed after the -D switch to ldapmodify. They must match.
ldap_add: Object class violation: The objects in the ldif file are not consistent. Check if you accidently deleted lines from the file.

In order to check the server, search all the objects you just added. The result should be similar to the ldif file you just used.


  
% ldapsearch -x -L objectclass=\*

If you get an error message or nothing, check the /etc/openldap/ldap.conf file for the BASE and HOST entries.

LDAP passwords

There are no less than two passwords we must maintain for the ldap server. We refer to them as the root dn password, which is used to access the LDAP root account; and the aauser account password, which the ActionApps use to access the aauser account and the LDAP server.

We should now set the root dn password in /etc/openldap/slapd.conf as well as for the aauser account password. To do this, first set the auser account password using ldappasswd, then make a query to the ldap server so we get an encrypted version of the password back, and copy and paste the encrypted password into the sldap.conf file. When you issue the following commands, the password given after the -w switches must match the old root dn password which is still defined in clear text in /etc/openldap/slapd.conf. When prompted for the new password, enter the new root dn password you want to set. And remind it!


  
% ldappasswd -x -D "cn=root,ou=AA" -w password -S "cn=aauser,ou=AA"
New password:
Re-enter new password:
% ldapsearch -x -D "cn=root,ou=AA" -w password -L cn=aauser
dn: cn=aauser,ou=AA
objectclass: top
objectclass: person
cn: aa
sn: Toolkit
description: Account used by AA to access LDAP DB

If everything worked right, you get the line "userpassword" as shown. This is the encrypted version of the new root dn password you entered. Paste this string (including the "{ssha}") into the rootpw: line in /etc/openldap/slapd.conf. After the next server restart, the old root dn password "password" will no longer work, instead, you use the password you just entered.

If you want, you can change the password for the aauser account again so it is different from the root dn password.

Try to access the ldap server using your aauser account:


  
% ldapsearch -x -D "cn=aauser,ou=AA" -W -L objectclass=\*
Enter LDAP Password:

You should get all the objects that are stored. In case of an error message, check the spelling of the command line... errors most likely have to do with spelling errors.