From Authentication Tools for Joomla! (JAuthTools)

Revision as of 13:41, 2 June 2007

Note: This article is incomplete, and is perhaps still being written. Check back later for more information.

This is a step by step how to on how to get OpenLDAP installed and running as an authentication source for Joomla!.

OpenLDAP is a free, open source implementation of the Lightweight Directory Access Protocol (LDAP) which is often bundled with many Linux distributions. In this case we'll be using the Debian Etch distribution to install and configure OpenLDAP. Apologies for anything that might be specific to Debian.

Note: Mac OS X requires a lot of extra instructions, if you are compiling from source you will most likely have to complete similar if not the same tasks. Keep in mind that if you compile from source your Configuration directory is up to you.

Installation and Server Configuration

Platform Installation Notes:

• Debian - Configuration directory at /etc/ldap
• Mac OS X - Configuration directory at /sw/etc/openldap

Once you've got slapd installed the configuration fun begins. In the configuration directory, open up the slapd.conf file. You will need to be root to do this. By default it should have a few things like this:

Debian:

# Schema and objectClass definitions
include         /etc/ldap/schema/core.schema
include         /etc/ldap/schema/cosine.schema
include         /etc/ldap/schema/nis.schema
include         /etc/ldap/schema/inetorgperson.schema

Mac OS X: (Note: You will need to alter your slapd.conf file to add the cosine and inetorgperson entries)

include         /sw/etc/openldap/schema/core.schema
include /sw/etc/openldap/schema/cosine.schema
include /sw/etc/openldap/schema/inetorgperson.schema

Progressing through the file we see some settings, what we're looking for is rootdn' and suffix:

suffix                "dc=joomla,dc=org"
rootdn                "cn=admin,dc=joomla,dc=org"

Mac OS X will have them together. If you used Debian, some preconfiguration will have occured already.

Your suffix is whats often called the Base DN, its where your LDAP tree starts. Your root DN is typically the super user for LDAP. Finally there will also be a rootpw entry, which in the case of Mac OS X defaults to secret. Debian during install asks for this password. You should probably change this.

Now that we have our base setup fixed we can consider connecting to our LDAP server.

Connecting to the server

Again, Debian has already configured and started the server (which is very kind of it) but we get no such luck with Mac OS X. For Mac OS X we're going to have to start the server ourselves. Fortunately this isn't a hard task to achieve. First we'll test the configuration and then we'll start the server with maximum debugging in case something goes wrong.

sudo /sw/sbin/slapd -t -d 5
sudo /sw/bin/slapd -d 255

The first command should run and complete with 'config check successful', and the second one should spawn and stay alive. Since we have the server up we're going to need to create a base entry for the LDAP server, heres a sample:

dn: dc=joomla,dc=org
objectClass: top
objectClass: dcObject
objectClass: organization
dc: joomla
o: joomla

Save this to a file (in this case we called it 'base.ldif') and run the following command:

ldapadd -D 'cn=admin, dc=joomla, dc=org' -x -f base.ldif -W

Additionally you're going to want to define the admin/manager stle account, and theres an LDIF file here (called userbase.ldif):

dn: cn=admin,dc=joomla,dc=org
objectclass: organizationalRole
cn: admin

Again, we use a similar command as above to add it (instead of base.ldif its perhaps userbase.ldif).

Finally, before we get too far into things, it might be a good time to add the Joomla LDAP schema into your server setup. You're going to need to restart your server after you've done this to include it

Managing our LDAP server

So now we've got some entries, even some special Joomla! schema, but the interface isn't the most user friendly. Since we're doing all of this with the eventual goal of getting LDAP auth into Joomla!, we might as well use a web based admin tool as well. The one I suggest is phpLDAPAdmin because it seems to work so well. Now for Debian, this package is available via APT but Mac OS X set up is a bit more complicated. phpLDAPAdmin requires a few things, including gettext. The easiest way I've found to satisfy its dependencies is to install the entropy PHP package and use it instead of the system provided PHP. Theres instructions on installing entropy available on their site, and configuring phpLDAPAdmin is also documented. For my Mac, I just extracted it to somewhere in my Sites folder and configured it from there. Additionally, I use LDAP Browser/Editor to do investigative queries against systems (normally eDirectory/Active Directory). Its adding/editing interface is limited but for the most basic of operations its quite a valuable tool.

So hopefully at this point you have phpLDAPAdmin set up and its pointing to your newly configured server waiting for you to login. Login and it should have our base DN available to us. Expanding it reveals our adminisration user and a 'create new entry here option'. For Mac OS X, you can select the user, add the objectClass "simpleSecurityObject". Once you've done that, click 'add new attribute' and select 'userPassword'. Put in an entry and you'll want to probably change the type from plain to something more secure (e.g. md5). This will allow you to use this password to log into the OpenLDAP server.

Next on our list is creating a container for our users. Whilst we could put them all at the base, that ends up being quite messy. So lets create a new entry. This panel gives a large list of options to choose from, some of which will be disabled since we don't have those schemas enabled in our server. However the one we want to use is the 'organisational unit' one. So select 'organisational unit' and hit proceed where you will be prompted for its name. We'll call this one 'Users' and click through until we get to a screen displaying our newly created OU.

Now that we've created an OU, we're going to want to put users in it. Here is where a structural planning issue raises its head: do you want to put all of your users in one place or if you want to segment the users up into different sections. For example, one might have a "Core" OU, a "Public" OU and a "Working Groups" OU. And within the "Working Groups" OU there might be various other OU's to manage sub categorizations of people. For completeness I'm going to branch here into one tutorial on creating users in one location and configuring Joomla! to authenticate them and then another one with multiple OU's. If multipe OU's is your goal, read the single location one first as it covers some information you will need later.

Single OU Configuration

So we've got our Users OU set up now its time to create some users. If you still have the Users OU edit screen up you can click on "Create a child entry", alternatively ensure all the branches are expanded and s9elect "create a new entry here". In the resultant dialog this time we're going to select 'Custom' which will give us more power over our selections.

== Multiple OU Configuraton In this case we're creating sub OU's in our main OU of Users and working from there. Creating users should be done as above

Notes

I tried phpLDAPAdmin 0.9.8.3 on my Mac and had some issues with it and ended up switching to 0.9.8.4 on my Debian server. Everything stated above was done in either of those released of phpLDAPAdmin. Safari has some slight issues with phpLDAPAdmin so keep in mind if using this browser, I suggest Firefox for use with this tool.

Sources

• Setting up slapd on Mac OS X - A blog entry useful for getting me started on Mac OS X
• LDAP authentication howto for Debian Sarge - one of the original documents I read on setting up OpenLDAP originally.